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