Commit | Line | Data |
---|---|---|
93dc3a11 JC |
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 | ||
93dc3a11 | 67 | .. kernel-doc:: lib/debugobjects.c |
8da3dc53 | 68 | :functions: debug_object_init |
93dc3a11 JC |
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 | ||
8da3dc53 JC |
90 | .. kernel-doc:: lib/debugobjects.c |
91 | :functions: debug_object_init_on_stack | |
93dc3a11 JC |
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 | ||
8da3dc53 JC |
114 | .. kernel-doc:: lib/debugobjects.c |
115 | :functions: debug_object_activate | |
93dc3a11 JC |
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 | ||
8da3dc53 JC |
138 | |
139 | .. kernel-doc:: lib/debugobjects.c | |
140 | :functions: debug_object_deactivate | |
93dc3a11 JC |
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 | ||
8da3dc53 JC |
152 | .. kernel-doc:: lib/debugobjects.c |
153 | :functions: debug_object_destroy | |
93dc3a11 JC |
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 | ||
8da3dc53 JC |
171 | .. kernel-doc:: lib/debugobjects.c |
172 | :functions: debug_object_free | |
93dc3a11 JC |
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 | ||
8da3dc53 JC |
187 | |
188 | .. kernel-doc:: lib/debugobjects.c | |
189 | :functions: debug_object_assert_init | |
93dc3a11 JC |
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). |