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