linux/Documentation/DocBook/debugobjects.tmpl
<<
>>
Prefs
   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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.