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       </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>