About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / core-api / debug-objects.rst




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.

1	============================================
2	The object-lifetime debugging infrastructure
3	============================================
4	
5	:Author: Thomas Gleixner
6	
7	Introduction
8	============
9	
10	debugobjects is a generic infrastructure to track the life time of
11	kernel objects and validate the operations on those.
12	
13	debugobjects is useful to check for the following error patterns:
14	
15	-  Activation of uninitialized objects
16	
17	-  Initialization of active objects
18	
19	-  Usage of freed/destroyed objects
20	
21	debugobjects is not changing the data structure of the real object so it
22	can be compiled in with a minimal runtime impact and enabled on demand
23	with a kernel command line option.
24	
25	Howto use debugobjects
26	======================
27	
28	A kernel subsystem needs to provide a data structure which describes the
29	object type and add calls into the debug code at appropriate places. The
30	data structure to describe the object type needs at minimum the name of
31	the object type. Optional functions can and should be provided to fixup
32	detected problems so the kernel can continue to work and the debug
33	information can be retrieved from a live system instead of hard core
34	debugging with serial consoles and stack trace transcripts from the
35	monitor.
36	
37	The debug calls provided by debugobjects are:
38	
39	-  debug_object_init
40	
41	-  debug_object_init_on_stack
42	
43	-  debug_object_activate
44	
45	-  debug_object_deactivate
46	
47	-  debug_object_destroy
48	
49	-  debug_object_free
50	
51	-  debug_object_assert_init
52	
53	Each of these functions takes the address of the real object and a
54	pointer to the object type specific debug description structure.
55	
56	Each detected error is reported in the statistics and a limited number
57	of errors are printk'ed including a full stack trace.
58	
59	The statistics are available via /sys/kernel/debug/debug_objects/stats.
60	They provide information about the number of warnings and the number of
61	successful fixups along with information about the usage of the internal
62	tracking objects and the state of the internal tracking objects pool.
63	
64	Debug functions
65	===============
66	
67	.. kernel-doc:: lib/debugobjects.c
68	   :functions: debug_object_init
69	
70	This function is called whenever the initialization function of a real
71	object is called.
72	
73	When the real object is already tracked by debugobjects it is checked,
74	whether the object can be initialized. Initializing is not allowed for
75	active and destroyed objects. When debugobjects detects an error, then
76	it calls the fixup_init function of the object type description
77	structure if provided by the caller. The fixup function can correct the
78	problem before the real initialization of the object happens. E.g. it
79	can deactivate an active object in order to prevent damage to the
80	subsystem.
81	
82	When the real object is not yet tracked by debugobjects, debugobjects
83	allocates a tracker object for the real object and sets the tracker
84	object state to ODEBUG_STATE_INIT. It verifies that the object is not
85	on the callers stack. If it is on the callers stack then a limited
86	number of warnings including a full stack trace is printk'ed. The
87	calling code must use debug_object_init_on_stack() and remove the
88	object before leaving the function which allocated it. See next section.
89	
90	.. kernel-doc:: lib/debugobjects.c
91	   :functions: debug_object_init_on_stack
92	
93	This function is called whenever the initialization function of a real
94	object which resides on the stack is called.
95	
96	When the real object is already tracked by debugobjects it is checked,
97	whether the object can be initialized. Initializing is not allowed for
98	active and destroyed objects. When debugobjects detects an error, then
99	it calls the fixup_init function of the object type description
100	structure if provided by the caller. The fixup function can correct the
101	problem before the real initialization of the object happens. E.g. it
102	can deactivate an active object in order to prevent damage to the
103	subsystem.
104	
105	When the real object is not yet tracked by debugobjects debugobjects
106	allocates a tracker object for the real object and sets the tracker
107	object state to ODEBUG_STATE_INIT. It verifies that the object is on
108	the callers stack.
109	
110	An object which is on the stack must be removed from the tracker by
111	calling debug_object_free() before the function which allocates the
112	object returns. Otherwise we keep track of stale objects.
113	
114	.. kernel-doc:: lib/debugobjects.c
115	   :functions: debug_object_activate
116	
117	This function is called whenever the activation function of a real
118	object is called.
119	
120	When the real object is already tracked by debugobjects it is checked,
121	whether the object can be activated. Activating is not allowed for
122	active and destroyed objects. When debugobjects detects an error, then
123	it calls the fixup_activate function of the object type description
124	structure if provided by the caller. The fixup function can correct the
125	problem before the real activation of the object happens. E.g. it can
126	deactivate an active object in order to prevent damage to the subsystem.
127	
128	When the real object is not yet tracked by debugobjects then the
129	fixup_activate function is called if available. This is necessary to
130	allow the legitimate activation of statically allocated and initialized
131	objects. The fixup function checks whether the object is valid and calls
132	the debug_objects_init() function to initialize the tracking of this
133	object.
134	
135	When the activation is legitimate, then the state of the associated
136	tracker object is set to ODEBUG_STATE_ACTIVE.
137	
138	
139	.. kernel-doc:: lib/debugobjects.c
140	   :functions: debug_object_deactivate
141	
142	This function is called whenever the deactivation function of a real
143	object is called.
144	
145	When the real object is tracked by debugobjects it is checked, whether
146	the object can be deactivated. Deactivating is not allowed for untracked
147	or destroyed objects.
148	
149	When the deactivation is legitimate, then the state of the associated
150	tracker object is set to ODEBUG_STATE_INACTIVE.
151	
152	.. kernel-doc:: lib/debugobjects.c
153	   :functions: debug_object_destroy
154	
155	This function is called to mark an object destroyed. This is useful to
156	prevent the usage of invalid objects, which are still available in
157	memory: either statically allocated objects or objects which are freed
158	later.
159	
160	When the real object is tracked by debugobjects it is checked, whether
161	the object can be destroyed. Destruction is not allowed for active and
162	destroyed objects. When debugobjects detects an error, then it calls the
163	fixup_destroy function of the object type description structure if
164	provided by the caller. The fixup function can correct the problem
165	before the real destruction of the object happens. E.g. it can
166	deactivate an active object in order to prevent damage to the subsystem.
167	
168	When the destruction is legitimate, then the state of the associated
169	tracker object is set to ODEBUG_STATE_DESTROYED.
170	
171	.. kernel-doc:: lib/debugobjects.c
172	   :functions: debug_object_free
173	
174	This function is called before an object is freed.
175	
176	When the real object is tracked by debugobjects it is checked, whether
177	the object can be freed. Free is not allowed for active objects. When
178	debugobjects detects an error, then it calls the fixup_free function of
179	the object type description structure if provided by the caller. The
180	fixup function can correct the problem before the real free of the
181	object happens. E.g. it can deactivate an active object in order to
182	prevent damage to the subsystem.
183	
184	Note that debug_object_free removes the object from the tracker. Later
185	usage of the object is detected by the other debug checks.
186	
187	
188	.. kernel-doc:: lib/debugobjects.c
189	   :functions: debug_object_assert_init
190	
191	This function is called to assert that an object has been initialized.
192	
193	When the real object is not tracked by debugobjects, it calls
194	fixup_assert_init of the object type description structure provided by
195	the caller, with the hardcoded object state ODEBUG_NOT_AVAILABLE. The
196	fixup function can correct the problem by calling debug_object_init
197	and other specific initializing functions.
198	
199	When the real object is already tracked by debugobjects it is ignored.
200	
201	Fixup functions
202	===============
203	
204	Debug object type description structure
205	---------------------------------------
206	
207	.. kernel-doc:: include/linux/debugobjects.h
208	   :internal:
209	
210	fixup_init
211	-----------
212	
213	This function is called from the debug code whenever a problem in
214	debug_object_init is detected. The function takes the address of the
215	object and the state which is currently recorded in the tracker.
216	
217	Called from debug_object_init when the object state is:
218	
219	-  ODEBUG_STATE_ACTIVE
220	
221	The function returns true when the fixup was successful, otherwise
222	false. The return value is used to update the statistics.
223	
224	Note, that the function needs to call the debug_object_init() function
225	again, after the damage has been repaired in order to keep the state
226	consistent.
227	
228	fixup_activate
229	---------------
230	
231	This function is called from the debug code whenever a problem in
232	debug_object_activate is detected.
233	
234	Called from debug_object_activate when the object state is:
235	
236	-  ODEBUG_STATE_NOTAVAILABLE
237	
238	-  ODEBUG_STATE_ACTIVE
239	
240	The function returns true when the fixup was successful, otherwise
241	false. The return value is used to update the statistics.
242	
243	Note that the function needs to call the debug_object_activate()
244	function again after the damage has been repaired in order to keep the
245	state consistent.
246	
247	The activation of statically initialized objects is a special case. When
248	debug_object_activate() has no tracked object for this object address
249	then fixup_activate() is called with object state
250	ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether
251	this is a legitimate case of a statically initialized object or not. In
252	case it is it calls debug_object_init() and debug_object_activate()
253	to make the object known to the tracker and marked active. In this case
254	the function should return false because this is not a real fixup.
255	
256	fixup_destroy
257	--------------
258	
259	This function is called from the debug code whenever a problem in
260	debug_object_destroy is detected.
261	
262	Called from debug_object_destroy when the object state is:
263	
264	-  ODEBUG_STATE_ACTIVE
265	
266	The function returns true when the fixup was successful, otherwise
267	false. The return value is used to update the statistics.
268	
269	fixup_free
270	-----------
271	
272	This function is called from the debug code whenever a problem in
273	debug_object_free is detected. Further it can be called from the debug
274	checks in kfree/vfree, when an active object is detected from the
275	debug_check_no_obj_freed() sanity checks.
276	
277	Called from debug_object_free() or debug_check_no_obj_freed() when
278	the object state is:
279	
280	-  ODEBUG_STATE_ACTIVE
281	
282	The function returns true when the fixup was successful, otherwise
283	false. The return value is used to update the statistics.
284	
285	fixup_assert_init
286	-------------------
287	
288	This function is called from the debug code whenever a problem in
289	debug_object_assert_init is detected.
290	
291	Called from debug_object_assert_init() with a hardcoded state
292	ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug
293	bucket.
294	
295	The function returns true when the fixup was successful, otherwise
296	false. The return value is used to update the statistics.
297	
298	Note, this function should make sure debug_object_init() is called
299	before returning.
300	
301	The handling of statically initialized objects is a special case. The
302	fixup function should check if this is a legitimate case of a statically
303	initialized object or not. In this case only debug_object_init()
304	should be called to make the object known to the tracker. Then the
305	function should return false because this is not a real fixup.
306	
307	Known Bugs And Assumptions
308	==========================
309	
310	None (knock on wood).
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.