Documentation/DocBook/debugobjects.tmpl

   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>