dynamic debug: update docs

updates the documentation for 'dynamic debug' feature.

Signed-off-by: Greg Banks <gnb@sgi.com>
Signed-off-by: Jason Baron <jbaron@redhat.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

1 files changed, 41 insertions, 31 deletions

diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index 0dd1c04c7323..8fee0a13ac58 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -848,59 +848,69 @@ config BUILD_DOCSRC
           Say N if you are unsure.
 
 config DYNAMIC_DEBUG
-        bool "Enable dynamic printk() call support"
+        bool "Enable dynamic printk() support"
         default n
         depends on PRINTK
+        depends on DEBUG_FS
         select PRINTK_DEBUG
         help
 
           Compiles debug level messages into the kernel, which would not
           otherwise be available at runtime. These messages can then be
-          enabled/disabled on a per module basis. This mechanism implicitly
-          enables all pr_debug() and dev_dbg() calls. The impact of this
-          compile option is a larger kernel text size of about 2%.
+          enabled/disabled based on various levels of scope - per source file,
+          function, module, format string, and line number. This mechanism
+          implicitly enables all pr_debug() and dev_dbg() calls. The impact of
+          this compile option is a larger kernel text size of about 2%.
 
           Usage:
 
-          Dynamic debugging is controlled by the debugfs file,
-          dynamic_printk/modules. This file contains a list of the modules that
-          can be enabled. The format of the file is the module name, followed
-          by a set of flags that can be enabled. The first flag is always the
-          'enabled' flag. For example:
+          Dynamic debugging is controlled via the 'dynamic_debug/ddebug' file,
+          which is contained in the 'debugfs' filesystem. Thus, the debugfs
+          filesystem must first be mounted before making use of this feature.
+          We refer the control file as: <debugfs>/dynamic_debug/ddebug. This
+          file contains a list of the debug statements that can be enabled. The
+          format for each line of the file is:
 
-                <module_name> <enabled=0/1>
-                                .
-                                .
-                                .
+                filename:lineno [module]function flags format
 
-          <module_name> : Name of the module in which the debug call resides
-          <enabled=0/1> : whether the messages are enabled or not
+          filename : source file of the debug statement
+          lineno : line number of the debug statement
+          module : module that contains the debug statement
+          function : function that contains the debug statement
+          flags : 'p' means the line is turned 'on' for printing
+          format : the format used for the debug statement
 
           From a live system:
 
-                snd_hda_intel enabled=0
-                fixup enabled=0
-                driver enabled=0
+                nullarbor:~ # cat <debugfs>/dynamic_debug/ddebug
+                # filename:lineno [module]function flags format
+                fs/aio.c:222 [aio]__put_ioctx - "__put_ioctx:\040freeing\040%p\012"
+                fs/aio.c:248 [aio]ioctx_alloc - "ENOMEM:\040nr_events\040too\040high\012"
+                fs/aio.c:1770 [aio]sys_io_cancel - "calling\040cancel\012"
 
-          Enable a module:
+          Example usage:
 
-                $echo "set enabled=1 <module_name>" > dynamic_printk/modules
+                // enable the message at line 1603 of file svcsock.c
+                nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
+                                                <debugfs>/dynamic_debug/ddebug
 
-          Disable a module:
+                // enable all the messages in file svcsock.c
+                nullarbor:~ # echo -n 'file svcsock.c +p' >
+                                                <debugfs>/dynamic_debug/ddebug
 
-                $echo "set enabled=0 <module_name>" > dynamic_printk/modules
+                // enable all the messages in the NFS server module
+                nullarbor:~ # echo -n 'module nfsd +p' >
+                                                <debugfs>/dynamic_debug/ddebug
 
-          Enable all modules:
+                // enable all 12 messages in the function svc_process()
+                nullarbor:~ # echo -n 'func svc_process +p' >
+                                                <debugfs>/dynamic_debug/ddebug
 
-                $echo "set enabled=1 all" > dynamic_printk/modules
+                // disable all 12 messages in the function svc_process()
+                nullarbor:~ # echo -n 'func svc_process -p' >
+                                                <debugfs>/dynamic_debug/ddebug
 
-          Disable all modules:
-
-                $echo "set enabled=0 all" > dynamic_printk/modules
-
-          Finally, passing "dynamic_printk" at the command line enables
-          debugging for all modules. This mode can be turned off via the above
-          disable command.
+          See Documentation/dynamic-debug-howto.txt for additional information.
 
 source "samples/Kconfig"