diff options
Diffstat (limited to 'Documentation/DocBook/debugobjects.tmpl')
| -rw-r--r-- | Documentation/DocBook/debugobjects.tmpl | 443 |
1 files changed, 0 insertions, 443 deletions
diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl deleted file mode 100644 index 7e4f34fde697..000000000000 --- a/Documentation/DocBook/debugobjects.tmpl +++ /dev/null @@ -1,443 +0,0 @@ -<?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="debug-objects-guide"> - <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> - - <copyright> - <year>2008</year> - <holder>Thomas Gleixner</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - debugobjects is a generic infrastructure to track the life time - of kernel objects and validate the operations on those. - </para> - <para> - debugobjects is useful to check for the following error patterns: - <itemizedlist> - <listitem><para>Activation of uninitialized objects</para></listitem> - <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 - 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 live system instead of hard core debugging - with serial consoles and stack trace transcripts from the - monitor. - </para> - <para> - The debug calls provided by debugobjects are: - <itemizedlist> - <listitem><para>debug_object_init</para></listitem> - <listitem><para>debug_object_init_on_stack</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> - <listitem><para>debug_object_assert_init</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 are printk'ed including a full stack trace. - </para> - <para> - The statistics are available via /sys/kernel/debug/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, - debugobjects allocates a tracker object for the real object - and sets the tracker object state to ODEBUG_STATE_INIT. It - verifies that the object is not on the callers stack. If it is - on the callers stack then a limited number of warnings - including a full stack trace is printk'ed. The calling code - must use debug_object_init_on_stack() and remove the object - before leaving the function which allocated it. See next - section. - </para> - </sect1> - - <sect1 id="debug_object_init_on_stack"> - <title>debug_object_init_on_stack</title> - <para> - This function is called whenever the initialization function - of a real object which resides on the stack 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 - debugobjects allocates a tracker object for the real object - and sets the tracker object state to ODEBUG_STATE_INIT. It - verifies that the object is on the callers stack. - </para> - <para> - An object which is on the stack must be removed from the - tracker by calling debug_object_free() before the function - which allocates the object returns. Otherwise we keep track of - stale objects. - </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 legitimate activation of statically - 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 legitimate, then the state of the - associated 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 legitimate, then the state of the - 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 legitimate, then the state of the - 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> - - <sect1 id="debug_object_assert_init"> - <title>debug_object_assert_init</title> - <para> - This function is called to assert that an object has been - initialized. - </para> - <para> - When the real object is not tracked by debugobjects, it calls - fixup_assert_init of the object type description structure - provided by the caller, with the hardcoded object state - ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem - by calling debug_object_init and other specific initializing - functions. - </para> - <para> - When the real object is already tracked by debugobjects it is - ignored. - </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 true when the fixup was successful, - otherwise false. The return value is used to update the - statistics. - </para> - <para> - Note, that the function needs to call the debug_object_init() - function again, after the damage has been repaired in order to - 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 true when the fixup was successful, - otherwise false. The return value is used to update the - statistics. - </para> - <para> - Note that the function needs to call the debug_object_activate() - function again after the damage has been repaired in order to - 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 legitimate case of a - statically 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 false because this is not a real - 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 true when the fixup was successful, - otherwise false. The return value is used to update the - 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 kfree/vfree, when an active object is - 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 true when the fixup was successful, - otherwise false. The return value is used to update the - statistics. - </para> - </sect1> - <sect1 id="fixup_assert_init"> - <title>fixup_assert_init</title> - <para> - This function is called from the debug code whenever a problem - in debug_object_assert_init is detected. - </para> - <para> - Called from debug_object_assert_init() with a hardcoded state - ODEBUG_STATE_NOTAVAILABLE when the object is not found in the - debug bucket. - </para> - <para> - The function returns true when the fixup was successful, - otherwise false. The return value is used to update the - statistics. - </para> - <para> - Note, this function should make sure debug_object_init() is - called before returning. - </para> - <para> - The handling of statically initialized objects is a special - case. The fixup function should check if this is a legitimate - case of a statically initialized object or not. In this case only - debug_object_init() should be called to make the object known to - the tracker. Then the function should return false because this - is not - a real fixup. - </para> - </sect1> - </chapter> - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None (knock on wood). - </para> - </chapter> -</book> |