lkml.org 
[lkml]   [2008]   [Mar]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    Date
    From
    SubjectRe: [patch 4/5] debugobjects: add documentation
    On Wed, 05 Mar 2008 16:04:02 -0000 Thomas Gleixner wrote:

    > Add a DocBook for debugobjects.

    Thanks!

    > Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
    > Acked-by: Ingo Molnar <mingo@elte.hu>
    > ---
    > Documentation/DocBook/Makefile | 3
    > Documentation/DocBook/debugobjects.tmpl | 354 ++++++++++++++++++++++++++++++++
    > 2 files changed, 356 insertions(+), 1 deletion(-)
    >
    > Index: linux-2.6/Documentation/DocBook/debugobjects.tmpl
    > ===================================================================
    > --- /dev/null
    > +++ linux-2.6/Documentation/DocBook/debugobjects.tmpl
    > @@ -0,0 +1,354 @@
    > +<?xml version="1.0" encoding="UTF-8"?>
    > +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    > + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
    > +
    > +<book id="debog-objects-guide">
    debug-

    > + <bookinfo>
    > + <title>Debug objects life time</title>
    > +
    > + <authorgroup>
    > + <author>
    > + <firstname>Thomas</firstname>
    > + <surname>Gleixner</surname>
    > + <affiliation>
    > + <address>
    > + <email>tglx@linutronix.de</email>
    > + </address>
    > + </affiliation>
    > + </author>
    > + </authorgroup>
    ...
    > +
    > + <chapter id="intro">
    > + <title>Introduction</title>
    > + <para>
    > + debugobjects is a generic infrastructure to track the life time
    > + of kernel objects and validate the operation on those.

    operations

    > + </para>
    > + <para>
    > + debugobjects is useful to check for the following error patterns:
    > + <itemizedlist>
    > + <listitem><para>Activtation of uninitialized objects</para></listitem>

    Activation

    > + <listitem><para>Initialization of active objects</para></listitem>
    > + <listitem><para>Usage of freed/destroyed objects</para></listitem>
    > + </itemizedlist>
    > + </para>
    > + <para>
    > + debugobjects is not changing the data structure of the real

    debugobjects does not change the data ...

    > + object so it can be compiled in with a minimal runtime impact
    > + and enabled on demand with a kernel command line option.
    > + </para>
    > + </chapter>
    > +
    > + <chapter id="howto">
    > + <title>Howto use debugobjects</title>
    > + <para>
    > + A kernel subsystem needs to provide a data structure which
    > + describes the object type and add calls into the debug code at
    > + appropriate places. The data structure to describe the object
    > + type needs at minimum the name of the object type. Optional
    > + functions can and should be provided to fixup detected problems
    > + so the kernel can continue to work and the debug information can
    > + be retrieved from a alive system instead of hard core debugging

    live

    > + with serial consoles and stack trace transscripts from the

    transcripts

    > + monitor.
    > + </para>
    > + <para>
    > + The debug calls provided by debugobjects are:
    > + <itemizedlist>
    > + <listitem><para>debug_object_init</para></listitem>
    > + <listitem><para>debug_object_activate</para></listitem>
    > + <listitem><para>debug_object_deactivate</para></listitem>
    > + <listitem><para>debug_object_destroy</para></listitem>
    > + <listitem><para>debug_object_free</para></listitem>
    > + </itemizedlist>
    > + Each of these functions takes the address of the real object and
    > + a pointer to the object type specific debug description
    > + structure.
    > + </para>
    > + <para>
    > + Each detected error is reported in the statistics and a limited
    > + number of errors is printk'ed including a full stack trace.

    are

    > + </para>
    > + <para>
    > + The statistics are available via debugfs/debug_objects/stats.
    > + They provide information about the number of warnings and the
    > + number of successful fixups along with information about the
    > + usage of the internal tracking objects and the state of the
    > + internal tracking objects pool.
    > + </para>
    > + </chapter>
    > + <chapter id="debugfunctions">
    > + <title>Debug functions</title>
    > + <sect1 id="prototypes">
    > + <title>Debug object function reference</title>
    > +!Elib/debugobjects.c
    > + </sect1>
    > + <sect1 id="debug_object_init">
    > + <title>debug_object_init</title>
    > + <para>
    > + This function is called whenever the initialization function
    > + of a real object is called.
    > + </para>
    > + <para>
    > + When the real object is already tracked by debugobjects it is
    > + checked, whether the object can be initialized. Initializing
    > + is not allowed for active and destroyed objects. When
    > + debugobjects detects an error, then it calls the fixup_init
    > + function of the object type description structure if provided
    > + by the caller. The fixup function can correct the problem
    > + before the real initialization of the object happens. E.g. it
    > + can deactivate an active object in order to prevent damage to
    > + the subsystem.
    > + </para>
    > + <para>
    > + When the real object is not yet tracked by debugobjects

    End above line with comma.

    > + debugobjects allocates a tracker object for the real object
    > + and sets the tracker object state to ODEBUG_STATE_INIT.
    > + </para>
    > + </sect1>
    > +
    > + <sect1 id="debug_object_activate">
    > + <title>debug_object_activate</title>
    > + <para>
    > + This function is called whenever the activation function of a
    > + real object is called.
    > + </para>
    > + <para>
    > + When the real object is already tracked by debugobjects it is
    > + checked, whether the object can be activated. Activating is
    > + not allowed for active and destroyed objects. When
    > + debugobjects detects an error, then it calls the
    > + fixup_activate function of the object type description
    > + structure if provided by the caller. The fixup function can
    > + correct the problem before the real activation of the object
    > + happens. E.g. it can deactivate an active object in order to
    > + prevent damage to the subsystem.
    > + </para>
    > + <para>
    > + When the real object is not yet tracked by debugobjects then
    > + the fixup_activate function is called if available. This is
    > + necessary to allow the legit activation of statically

    legitimate

    > + allocated and initialized objects. The fixup function checks
    > + whether the object is valid and calls the debug_objects_init()
    > + function to initialize the tracking of this object.
    > + </para>
    > + <para>
    > + When the activation is legit, then the state of the associated

    legitimate,

    > + tracker object is set to ODEBUG_STATE_ACTIVE.
    > + </para>
    > + </sect1>
    > +
    > + <sect1 id="debug_object_deactivate">
    > + <title>debug_object_deactivate</title>
    > + <para>
    > + This function is called whenever the deactivation function of
    > + a real object is called.
    > + </para>
    > + <para>
    > + When the real object is tracked by debugobjects it is checked,
    > + whether the object can be deactivated. Deactivating is not
    > + allowed for untracked or destroyed objects.
    > + </para>
    > + <para>
    > + When the deactivation is legit, then the state of the

    legitimate,

    > + associated tracker object is set to ODEBUG_STATE_INACTIVE.
    > + </para>
    > + </sect1>
    > +
    > + <sect1 id="debug_object_destroy">
    > + <title>debug_object_destroy</title>
    > + <para>
    > + This function is called to mark an object destroyed. This is
    > + useful to prevent the usage of invalid objects, which are
    > + still available in memory: either statically allocated objects
    > + or objects which are freed later.
    > + </para>
    > + <para>
    > + When the real object is tracked by debugobjects it is checked,
    > + whether the object can be destroyed. Destruction is not
    > + allowed for active and destroyed objects. When debugobjects
    > + detects an error, then it calls the fixup_destroy function of
    > + the object type description structure if provided by the
    > + caller. The fixup function can correct the problem before the
    > + real destruction of the object happens. E.g. it can deactivate
    > + an active object in order to prevent damage to the subsystem.
    > + </para>
    > + <para>
    > + When the destruction is legit, then the state of the

    legitimate,

    > + associated tracker object is set to ODEBUG_STATE_DESTROYED.
    > + </para>
    > + </sect1>
    > +
    > + <sect1 id="debug_object_free">
    > + <title>debug_object_free</title>
    > + <para>
    > + This function is called before an object is freed.
    > + </para>
    > + <para>
    > + When the real object is tracked by debugobjects it is checked,
    > + whether the object can be freed. Free is not allowed for
    > + active objects. When debugobjects detects an error, then it
    > + calls the fixup_free function of the object type description
    > + structure if provided by the caller. The fixup function can
    > + correct the problem before the real free of the object
    > + happens. E.g. it can deactivate an active object in order to
    > + prevent damage to the subsystem.
    > + </para>
    > + <para>
    > + Note that debug_object_free removes the object from the
    > + tracker. Later usage of the object is detected by the other
    > + debug checks.
    > + </para>
    > + </sect1>
    > + </chapter>
    > + <chapter id="fixupfunctions">
    > + <title>Fixup functions</title>
    > + <sect1 id="debug_obj_descr">
    > + <title>Debug object type description structure</title>
    > +!Iinclude/linux/debugobjects.h
    > + </sect1>
    > + <sect1 id="fixup_init">
    > + <title>fixup_init</title>
    > + <para>
    > + This function is called from the debug code whenever a problem
    > + in debug_object_init is detected. The function takes the
    > + address of the object and the state which is currently
    > + recorded in the tracker.
    > + </para>
    > + <para>
    > + Called from debug_object_init when the object state is:
    > + <itemizedlist>
    > + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
    > + </itemizedlist>
    > + </para>
    > + <para>
    > + The function returns "1" then the fixup was successful,
    > + otherwise "0". The return value is used to update the
    > + statistics.

    We usually don't quote numbers unless they are strings (instead of
    numbers).

    > + </para>
    > + <para>
    > + Note, that the function needs to call the debug_object_init()

    Drop comma.

    > + function again, after the damage has been repaired in order to

    Ditto.

    > + keep the state consistent.
    > + </para>
    > + </sect1>
    > +
    > + <sect1 id="fixup_activate">
    > + <title>fixup_activate</title>
    > + <para>
    > + This function is called from the debug code whenever a problem
    > + in debug_object_activate is detected.
    > + </para>
    > + <para>
    > + Called from debug_object_activate when the object state is:
    > + <itemizedlist>
    > + <listitem><para>ODEBUG_STATE_NOTAVAILABLE</para></listitem>
    > + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
    > + </itemizedlist>
    > + </para>
    > + <para>
    > + The function returns "1" then the fixup was successful,
    > + otherwise "0". The return value is used to update the
    > + statistics.

    1 or 0

    > + </para>
    > + <para>
    > + Note, that the function needs to call the debug_object_activate()

    Drop comma.

    > + function again, after the damage has been repaired in order to

    Ditto.

    > + keep the state consistent.
    > + </para>
    > + <para>
    > + The activation of statically initialized objects is a special
    > + case. When debug_object_activate() has no tracked object for
    > + this object address then fixup_activate() is called with
    > + object state ODEBUG_STATE_NOTAVAILABLE. The fixup function
    > + needs to check whether this is a legit case of a statically

    legitimate

    > + initialized object or not. In case it is it calls
    > + debug_object_init() and debug_object_activate() to make the
    > + object known to the tracker and marked active. In this case
    > + the function should return "0" because this is not a real

    0

    > + fixup.
    > + </para>
    > + </sect1>
    > +
    > + <sect1 id="fixup_destroy">
    > + <title>fixup_destroy</title>
    > + <para>
    > + This function is called from the debug code whenever a problem
    > + in debug_object_destroy is detected.
    > + </para>
    > + <para>
    > + Called from debug_object_destroy when the object state is:
    > + <itemizedlist>
    > + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
    > + </itemizedlist>
    > + </para>
    > + <para>
    > + The function returns "1" then the fixup was successful,
    > + otherwise "0". The return value is used to update the

    1 or 0

    > + statistics.
    > + </para>
    > + </sect1>
    > + <sect1 id="fixup_free">
    > + <title>fixup_free</title>
    > + <para>
    > + This function is called from the debug code whenever a problem
    > + in debug_object_free is detected. Further it can be called
    > + from the debug checks in k/v free, when an active object is

    kfree/vfree ?

    > + detected from the debug_check_no_obj_freed() sanity checks.
    > + </para>
    > + <para>
    > + Called from debug_object_free() or debug_check_no_obj_freed()
    > + when the object state is:
    > + <itemizedlist>
    > + <listitem><para>ODEBUG_STATE_ACTIVE</para></listitem>
    > + </itemizedlist>
    > + </para>
    > + <para>
    > + The function returns "1" then the fixup was successful,
    > + otherwise "0". The return value is used to update the

    1 or 0

    > + statistics.
    > + </para>
    > + </sect1>
    > + </chapter>
    > + <chapter id="bugs">
    > + <title>Known Bugs And Assumptions</title>
    > + <para>
    > + None (knock on wood).
    > + </para>
    > + </chapter>
    > +</book>
    >
    > --

    ---
    ~Randy

    \
     
     \ /
      Last update: 2008-03-10 21:21    [W:0.057 / U:0.300 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site