From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756383AbYCJUQr (ORCPT ); Mon, 10 Mar 2008 16:16:47 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1756708AbYCJUOW (ORCPT ); Mon, 10 Mar 2008 16:14:22 -0400 Received: from rgminet01.oracle.com ([148.87.113.118]:58192 "EHLO rgminet01.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1756092AbYCJUOT (ORCPT ); Mon, 10 Mar 2008 16:14:19 -0400 Date: Mon, 10 Mar 2008 13:13:11 -0700 From: Randy Dunlap To: Thomas Gleixner Cc: LKML , Andrew Morton , Greg KH , Peter Zijlstra , Ingo Molnar Subject: Re: [patch 4/5] debugobjects: add documentation Message-Id: <20080310131311.23e02eec.randy.dunlap@oracle.com> In-Reply-To: <20080305155117.567966119@linutronix.de> References: <20080305154829.185609547@linutronix.de> <20080305155117.567966119@linutronix.de> Organization: Oracle Linux Eng. X-Mailer: Sylpheed 2.4.7 (GTK+ 2.8.10; x86_64-unknown-linux-gnu) Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 05 Mar 2008 16:04:02 -0000 Thomas Gleixner wrote: > Add a DocBook for debugobjects. Thanks! > Signed-off-by: Thomas Gleixner > Acked-by: Ingo Molnar > --- > 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 @@ > + > + + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> > + > + debug- > + > + Debug objects life time > + > + > + > + Thomas > + Gleixner > + > +
> + tglx@linutronix.de > +
> + > + > + ... > + > + > + Introduction > + > + debugobjects is a generic infrastructure to track the life time > + of kernel objects and validate the operation on those. operations > + > + > + debugobjects is useful to check for the following error patterns: > + > + Activtation of uninitialized objects Activation > + Initialization of active objects > + Usage of freed/destroyed objects > + > + > + > + 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. > + > + > + > + > + Howto use debugobjects > + > + 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. > + > + > + The debug calls provided by debugobjects are: > + > + debug_object_init > + debug_object_activate > + debug_object_deactivate > + debug_object_destroy > + debug_object_free > + > + Each of these functions takes the address of the real object and > + a pointer to the object type specific debug description > + structure. > + > + > + Each detected error is reported in the statistics and a limited > + number of errors is printk'ed including a full stack trace. are > + > + > + 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. > + > + > + > + Debug functions > + > + Debug object function reference > +!Elib/debugobjects.c > + > + > + debug_object_init > + > + This function is called whenever the initialization function > + of a real object is called. > + > + > + 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. > + > + > + 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. > + > + > + > + > + debug_object_activate > + > + This function is called whenever the activation function of a > + real object is called. > + > + > + 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. > + > + > + 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. > + > + > + When the activation is legit, then the state of the associated legitimate, > + tracker object is set to ODEBUG_STATE_ACTIVE. > + > + > + > + > + debug_object_deactivate > + > + This function is called whenever the deactivation function of > + a real object is called. > + > + > + 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. > + > + > + When the deactivation is legit, then the state of the legitimate, > + associated tracker object is set to ODEBUG_STATE_INACTIVE. > + > + > + > + > + debug_object_destroy > + > + 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. > + > + > + 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. > + > + > + When the destruction is legit, then the state of the legitimate, > + associated tracker object is set to ODEBUG_STATE_DESTROYED. > + > + > + > + > + debug_object_free > + > + This function is called before an object is freed. > + > + > + 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. > + > + > + Note that debug_object_free removes the object from the > + tracker. Later usage of the object is detected by the other > + debug checks. > + > + > + > + > + Fixup functions > + > + Debug object type description structure > +!Iinclude/linux/debugobjects.h > + > + > + fixup_init > + > + 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. > + > + > + Called from debug_object_init when the object state is: > + > + ODEBUG_STATE_ACTIVE > + > + > + > + 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). > + > + > + 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. > + > + > + > + > + fixup_activate > + > + This function is called from the debug code whenever a problem > + in debug_object_activate is detected. > + > + > + Called from debug_object_activate when the object state is: > + > + ODEBUG_STATE_NOTAVAILABLE > + ODEBUG_STATE_ACTIVE > + > + > + > + The function returns "1" then the fixup was successful, > + otherwise "0". The return value is used to update the > + statistics. 1 or 0 > + > + > + 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. > + > + > + 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. > + > + > + > + > + fixup_destroy > + > + This function is called from the debug code whenever a problem > + in debug_object_destroy is detected. > + > + > + Called from debug_object_destroy when the object state is: > + > + ODEBUG_STATE_ACTIVE > + > + > + > + The function returns "1" then the fixup was successful, > + otherwise "0". The return value is used to update the 1 or 0 > + statistics. > + > + > + > + fixup_free > + > + 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. > + > + > + Called from debug_object_free() or debug_check_no_obj_freed() > + when the object state is: > + > + ODEBUG_STATE_ACTIVE > + > + > + > + The function returns "1" then the fixup was successful, > + otherwise "0". The return value is used to update the 1 or 0 > + statistics. > + > + > + > + > + Known Bugs And Assumptions > + > + None (knock on wood). > + > + > + > > -- --- ~Randy