Documentation/core-api/debug-objects.rst

2 The object-lifetime debugging infrastructure
10 debugobjects is a generic infrastructure to track the life time of
11 kernel objects and validate the operations on those.
13 debugobjects is useful to check for the following error patterns:
21 debugobjects is not changing the data structure of the real object so it
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
34 debugging with serial consoles and stack trace transcripts from the
37 The debug calls provided by debugobjects are:
53 Each of these functions takes the address of the real object and a
54 pointer to the object type specific debug description structure.
56 Each detected error is reported in the statistics and a limited number
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.
70 This function is called whenever the initialization function of a real
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
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
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.
93 This function is called whenever the initialization function of a real
94 object which resides on the stack is called.
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
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
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.
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
117 This function is called whenever the activation function of a real
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
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.
128 When the real object is not yet tracked by debugobjects then the
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
135 When the activation is legitimate, then the state of the associated
142 This function is called whenever the deactivation function of a real
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
149 When the deactivation is legitimate, then the state of the associated
156 prevent the usage of invalid objects, which are still available in
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.
168 When the destruction is legitimate, then the state of the associated
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
182 prevent damage to the subsystem.
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.
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
199 When the real object is already tracked by debugobjects it is ignored.
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.
217 Called from debug_object_init when the object state is:
221 The function returns true when the fixup was successful, otherwise
222 false. The return value is used to update the statistics.
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
231 This function is called from the debug code whenever a problem in
234 Called from debug_object_activate when the object state is:
240 The function returns true when the fixup was successful, otherwise
241 false. The return value is used to update the statistics.
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
247 The activation of statically initialized objects is a special case. When
250 ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether
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.
259 This function is called from the debug code whenever a problem in
262 Called from debug_object_destroy when the object state is:
266 The function returns true when the fixup was successful, otherwise
267 false. The return value is used to update the statistics.
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
278 the object state is:
282 The function returns true when the fixup was successful, otherwise
283 false. The return value is used to update the statistics.
288 This function is called from the debug code whenever a problem in
292 ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug
295 The function returns true when the fixup was successful, otherwise
296 false. The return value is used to update the statistics.
301 The handling of statically initialized objects is a special case. The
304 should be called to make the object known to the tracker. Then the