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 </itemizedlist> 100 Each of these functions takes the address of the real object and 101 a pointer to the object type specific debug description 102 structure. 103 </para> 104 <para> 105 Each detected error is reported in the statistics and a limited 106 number of errors are printk'ed including a full stack trace. 107 </para> 108 <para> 109 The statistics are available via debugfs/debug_objects/stats. 110 They provide information about the number of warnings and the 111 number of successful fixups along with information about the 112 usage of the internal tracking objects and the state of the 113 internal tracking objects pool. 114 </para> 115 </chapter> 116 <chapter id="debugfunctions"> 117 <title>Debug functions</title> 118 <sect1 id="prototypes"> 119 <title>Debug object function reference</title> 120!Elib/debugobjects.c 121 </sect1> 122 <sect1 id="debug_object_init"> 123 <title>debug_object_init</title> 124 <para> 125 This function is called whenever the initialization function 126 of a real object is called. 127 </para> 128 <para> 129 When the real object is already tracked by debugobjects it is 130 checked, whether the object can be initialized. Initializing 131 is not allowed for active and destroyed objects. When 132 debugobjects detects an error, then it calls the fixup_init 133 function of the object type description structure if provided 134 by the caller. The fixup function can correct the problem 135 before the real initialization of the object happens. E.g. it 136 can deactivate an active object in order to prevent damage to 137 the subsystem. 138 </para> 139 <para> 140 When the real object is not yet tracked by debugobjects, 141 debugobjects allocates a tracker object for the real object 142 and sets the tracker object state to ODEBUG_STATE_INIT. It 143 verifies that the object is not on the callers stack. If it is 144 on the callers stack then a limited number of warnings 145 including a full stack trace is printk'ed. The calling code 146 must use debug_object_init_on_stack() and remove the object 147 before leaving the function which allocated it. See next 148 section. 149 </para> 150 </sect1> 151 152 <sect1 id="debug_object_init_on_stack"> 153 <title>debug_object_init_on_stack</title> 154 <para> 155 This function is called whenever the initialization function 156 of a real object which resides on the stack is called. 157 </para> 158 <para> 159 When the real object is already tracked by debugobjects it is 160 checked, whether the object can be initialized. Initializing 161 is not allowed for active and destroyed objects. When 162 debugobjects detects an error, then it calls the fixup_init 163 function of the object type description structure if provided 164 by the caller. The fixup function can correct the problem 165 before the real initialization of the object happens. E.g. it 166 can deactivate an active object in order to prevent damage to 167 the subsystem. 168 </para> 169 <para> 170 When the real object is not yet tracked by debugobjects 171 debugobjects allocates a tracker object for the real object 172 and sets the tracker object state to ODEBUG_STATE_INIT. It 173 verifies that the object is on the callers stack. 174 </para> 175 <para> 176 An object which is on the stack must be removed from the 177 tracker by calling debug_object_free() before the function 178 which allocates the object returns. Otherwise we keep track of 179 stale objects. 180 </para> 181 </sect1> 182 183 <sect1 id="debug_object_activate"> 184 <title>debug_object_activate</title> 185 <para> 186 This function is called whenever the activation function of a 187 real object is called. 188 </para> 189 <para> 190 When the real object is already tracked by debugobjects it is 191 checked, whether the object can be activated. Activating is 192 not allowed for active and destroyed objects. When 193 debugobjects detects an error, then it calls the 194 fixup_activate function of the object type description 195 structure if provided by the caller. The fixup function can 196 correct the problem before the real activation of the object 197 happens. E.g. it can deactivate an active object in order to 198 prevent damage to the subsystem. 199 </para> 200 <para> 201 When the real object is not yet tracked by debugobjects then 202 the fixup_activate function is called if available. This is 203 necessary to allow the legitimate activation of statically 204 allocated and initialized objects. The fixup function checks 205 whether the object is valid and calls the debug_objects_init() 206 function to initialize the tracking of this object. 207 </para> 208 <para> 209 When the activation is legitimate, then the state of the 210 associated tracker object is set to ODEBUG_STATE_ACTIVE. 211 </para> 212 </sect1> 213 214 <sect1 id="debug_object_deactivate"> 215 <title>debug_object_deactivate</title> 216 <para> 217 This function is called whenever the deactivation function of 218 a real object is called. 219 </para> 220 <para> 221 When the real object is tracked by debugobjects it is checked, 222 whether the object can be deactivated. Deactivating is not 223 allowed for untracked or destroyed objects. 224 </para> 225 <para> 226 When the deactivation is legitimate, then the state of the 227 associated tracker object is set to ODEBUG_STATE_INACTIVE. 228 </para> 229 </sect1> 230 231 <sect1 id="debug_object_destroy"> 232 <title>debug_object_destroy</title> 233 <para> 234 This function is called to mark an object destroyed. This is 235 useful to prevent the usage of invalid objects, which are 236 still available in memory: either statically allocated objects 237 or objects which are freed later. 238 </para> 239 <para> 240 When the real object is tracked by debugobjects it is checked, 241 whether the object can be destroyed. Destruction is not 242 allowed for active and destroyed objects. When debugobjects 243 detects an error, then it calls the fixup_destroy function of 244 the object type description structure if provided by the 245 caller. The fixup function can correct the problem before the 246 real destruction of the object happens. E.g. it can deactivate 247 an active object in order to prevent damage to the subsystem. 248 </para> 249 <para> 250 When the destruction is legitimate, then the state of the 251 associated tracker object is set to ODEBUG_STATE_DESTROYED. 252 </para> 253 </sect1> 254 255 <sect1 id="debug_object_free"> 256 <title>debug_object_free</title> 257 <para> 258 This function is called before an object is freed. 259 </para> 260 <para> 261 When the real object is tracked by debugobjects it is checked, 262 whether the object can be freed. Free is not allowed for 263 active objects. When debugobjects detects an error, then it 264 calls the fixup_free function of the object type description 265 structure if provided by the caller. The fixup function can 266 correct the problem before the real free of the object 267 happens. E.g. it can deactivate an active object in order to 268 prevent damage to the subsystem. 269 </para> 270 <para> 271 Note that debug_object_free removes the object from the 272 tracker. Later usage of the object is detected by the other 273 debug checks. 274 </para> 275 </sect1> 276 </chapter> 277 <chapter id="fixupfunctions"> 278 <title>Fixup functions</title> 279 <sect1 id="debug_obj_descr"> 280 <title>Debug object type description structure</title> 281!Iinclude/linux/debugobjects.h 282 </sect1> 283 <sect1 id="fixup_init"> 284 <title>fixup_init</title> 285 <para> 286 This function is called from the debug code whenever a problem 287 in debug_object_init is detected. The function takes the 288 address of the object and the state which is currently 289 recorded in the tracker. 290 </para> 291 <para> 292 Called from debug_object_init when the object state is: 293 <itemizedlist> 294 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> 295 </itemizedlist> 296 </para> 297 <para> 298 The function returns 1 when the fixup was successful, 299 otherwise 0. The return value is used to update the 300 statistics. 301 </para> 302 <para> 303 Note, that the function needs to call the debug_object_init() 304 function again, after the damage has been repaired in order to 305 keep the state consistent. 306 </para> 307 </sect1> 308 309 <sect1 id="fixup_activate"> 310 <title>fixup_activate</title> 311 <para> 312 This function is called from the debug code whenever a problem 313 in debug_object_activate is detected. 314 </para> 315 <para> 316 Called from debug_object_activate when the object state is: 317 <itemizedlist> 318 <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem> 319 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> 320 </itemizedlist> 321 </para> 322 <para> 323 The function returns 1 when the fixup was successful, 324 otherwise 0. The return value is used to update the 325 statistics. 326 </para> 327 <para> 328 Note that the function needs to call the debug_object_activate() 329 function again after the damage has been repaired in order to 330 keep the state consistent. 331 </para> 332 <para> 333 The activation of statically initialized objects is a special 334 case. When debug_object_activate() has no tracked object for 335 this object address then fixup_activate() is called with 336 object state ODEBUG_STATE_NOTAVAILABLE. The fixup function 337 needs to check whether this is a legitimate case of a 338 statically initialized object or not. In case it is it calls 339 debug_object_init() and debug_object_activate() to make the 340 object known to the tracker and marked active. In this case 341 the function should return 0 because this is not a real fixup. 342 </para> 343 </sect1> 344 345 <sect1 id="fixup_destroy"> 346 <title>fixup_destroy</title> 347 <para> 348 This function is called from the debug code whenever a problem 349 in debug_object_destroy is detected. 350 </para> 351 <para> 352 Called from debug_object_destroy when the object state is: 353 <itemizedlist> 354 <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem> 355 </itemizedlist> 356 </para> 357 <para> 358 The function returns 1 when the fixup was successful, 359 otherwise 0. The return value is used to update the 360 statistics. 361 </para> 362 </sect1> 363 <sect1 id="fixup_free"> 364 <title>fixup_free</title> 365 <para> 366 This function is called from the debug code whenever a problem 367 in debug_object_free is detected. Further it can be called 368 from the debug checks in kfree/vfree, when an active object is 369 detected from the debug_check_no_obj_freed() sanity checks. 370 </para> 371 <para> 372 Called from debug_object_free() or debug_check_no_obj_freed() 373 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 </chapter> 385 <chapter id="bugs"> 386 <title>Known Bugs And Assumptions</title> 387 <para> 388 None (knock on wood). 389 </para> 390 </chapter> 391</book> 392