[patch 2.6.22-git] dev_vdbg(), available with -DVERBOSE_DEBUG

[patch 2.6.22-git] dev_vdbg(), available with -DVERBOSE_DEBUG

[David Brownell]

This defines a dev_vdbg() call, which is enabled with -DVERBOSE_DEBUG.
When enabled, dev_vdbg() acts just like dev_dbg().  When disabled, it
is a NOP ... just like dev_dbg() without -DDEBUG.  The specific code
was moved out of a USB patch, but lots of drivers have similar support.

That is, code can now be written to use an additional level of debug
output, selected at compile time.  Many driver authors have found this
idiom to be very useful.  A typical usage model is for "normal" debug
messages to focus on fault paths and not be very "chatty", so that
those messages can be left on during normal operation without much of
a performance or syslog load.  On the other hand "verbose" messages
would be noisy enough that they wouldn't normally be enabled; they
might even affect timings enough to change system or driver behavior.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
---
 drivers/usb/core/driver.c |    7 -------
 include/linux/device.h    |   10 ++++++++++
 2 files changed, 10 insertions(+), 7 deletions(-)

--- g26.orig/drivers/usb/core/driver.c	2007-07-12 20:09:34.000000000 -0700
+++ g26/drivers/usb/core/driver.c	2007-07-12 20:11:35.000000000 -0700
@@ -29,13 +29,6 @@
 #include "hcd.h"
 #include "usb.h"
 
-#define VERBOSE_DEBUG	0
-
-#if VERBOSE_DEBUG
-#define dev_vdbg	dev_dbg
-#else
-#define dev_vdbg(dev, fmt, args...)	do { } while (0)
-#endif
 
 #ifdef CONFIG_HOTPLUG
 
--- g26.orig/include/linux/device.h	2007-07-12 20:09:16.000000000 -0700
+++ g26/include/linux/device.h	2007-07-12 20:11:13.000000000 -0700
@@ -572,6 +572,16 @@ dev_dbg(struct device * dev, const char 
 }
 #endif
 
+#ifdef VERBOSE_DEBUG
+#define dev_vdbg	dev_dbg
+#else
+static inline int __attribute__ ((format (printf, 2, 3)))
+dev_vdbg(struct device * dev, const char * fmt, ...)
+{
+	return 0;
+}
+#endif
+
 #define dev_err(dev, format, arg...)		\
 	dev_printk(KERN_ERR , dev , format , ## arg)
 #define dev_info(dev, format, arg...)		\

Re: [patch 2.6.22-git] dev_vdbg(), available with -DVERBOSE_DEBUG

[Andrew Morton]

On Thu, 12 Jul 2007 20:30:49 -0700 David Brownell <david-b@pacbell.net> wrote:

> This defines a dev_vdbg() call, which is enabled with -DVERBOSE_DEBUG.
> When enabled, dev_vdbg() acts just like dev_dbg().  When disabled, it
> is a NOP ... just like dev_dbg() without -DDEBUG.  The specific code
> was moved out of a USB patch, but lots of drivers have similar support.

I suppose we should find some way of telling people about this.  Maybe
in the `make help' output?

Re: [patch 2.6.22-git] dev_vdbg(), available with -DVERBOSE_DEBUG

[David Brownell]

On Thursday 12 July 2007, Andrew Morton wrote:
> On Thu, 12 Jul 2007 20:30:49 -0700 David Brownell <david-b@pacbell.net> wrote:
> 
> > This defines a dev_vdbg() call, which is enabled with -DVERBOSE_DEBUG.
> > When enabled, dev_vdbg() acts just like dev_dbg().  When disabled, it
> > is a NOP ... just like dev_dbg() without -DDEBUG.  The specific code
> > was moved out of a USB patch, but lots of drivers have similar support.
> 
> I suppose we should find some way of telling people about this.  Maybe
> in the `make help' output?

Whereever people learn about "-DDEBUG", they should probably
be able to learn about "-DVERBOSE_DEBUG".  Which is likely
from existing kernel code (although most C coders will expect
that "-DDEBUG" does *something* interesting).

I suspect maybe Documentation/CodingStyle would be better..

- Dave

====	CUT HERE
Update CodingStyle to talk about "-DDEBUG" message conventions and the
new "-DVERBOSE_DEBUG" convention.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
---
 Documentation/CodingStyle |   20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

--- g26.orig/Documentation/CodingStyle	2007-07-12 23:03:25.000000000 -0700
+++ g26/Documentation/CodingStyle	2007-07-12 23:53:52.000000000 -0700
@@ -621,12 +621,27 @@ covers RTL which is used frequently with
 
 Kernel developers like to be seen as literate. Do mind the spelling
 of kernel messages to make a good impression. Do not use crippled
-words like "dont" and use "do not" or "don't" instead.
+words like "dont"; use "do not" or "don't" instead.  Make the messages
+concise, clear, and unambiguous.
 
 Kernel messages do not have to be terminated with a period.
 
 Printing numbers in parentheses (%d) adds no value and should be avoided.
 
+There are a number of driver model diagnostic macros in <linux/device.h>
+which you should use to make sure messages are matched to the right device
+and driver, and are tagged with the right level:  dev_err(), dev_warn(),
+dev_info(), and so forth.  For messages that aren't associated with a
+particular device, <linux/kernel.h> defines pr_debug() and pr_info().
+
+Coming up with good debugging messages can be quite a challenge; and once
+you have them, they can be a huge help for remote troubleshooting.  Such
+messages should be compiled out when the DEBUG symbol is not defined (that
+is, by default they are not included).  When you use dev_dbg() or pr_debug(),
+that's automatic.  Many subsystems have Kconfig options to turn on -DDEBUG.
+A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
+ones already enabled by DEBUG.
+
 
 		Chapter 14: Allocating memory
 
@@ -751,4 +766,5 @@ Kernel CodingStyle, by greg@kroah.com at
 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
 
 --
-Last updated on 2006-December-06.
+Last updated on 2007-July-13.
+