Documentation/admin-guide/dynamic-debug-howto.rst

1 Dynamic debug
8 Dynamic debug allows you to dynamically enable/disable kernel
9 debug-print code to obtain additional kernel information.
11 If ``/proc/dynamic_debug/control`` exists, your kernel has dynamic
14 Dynamic debug provides:
22    - source filename
23    - function name
24    - line number (including ranges of line numbers)
25    - module name
26    - format string
27    - class name (as known/declared by each module)
29 NOTE: To actually get the debug-print output on the console, you may
32 Documentation/admin-guide/kernel-parameters.rst.
34 Viewing Dynamic Debug Behaviour
39   :#> head -n7 /proc/dynamic_debug/control
48 The 3rd space-delimited column shows the current flags, preceded by
51 Controlling dynamic debug Behaviour
60   :#> ddcmd '-p; module main func run* +p'
69   :#> ddcmd mode foo +p
70   dyndbg: unknown keyword "mode"
75 also under the mount-dir, typically ``/sys/kernel/debug/``.
95   :#> cat query-batch-file > /proc/dynamic_debug/control
106   command ::= match-spec* flags-spec
108 The match-spec's select *prdbgs* from the catalog, upon which to apply
109 the flags-spec, all constraints are ANDed together.  An absent keyword
117   match-spec ::= 'func' string |
122 		 'line' line-range
124   line-range ::= lineno |
125 		 '-'lineno |
126 		 lineno'-' |
127 		 lineno'-'lineno
129   lineno ::= unsigned-int
133   ``line-range`` cannot contain space, e.g.
134   "1-30" is valid range but "1 - 30" is not.
147     The given string is compared against either the src-root relative
155 	file inode.c:1-100	# parse :tail as a line-range (above)
161     suffix and with ``-`` changed to ``_``.  Examples::
168     The given string is searched for in the dynamic debug format
190 	class JUNK		# silent non-match
203 	line 1600-1605      // the six lines from line 1600 to line 1605
204 	line -1605          // the 1605 lines from line 1 to line 1605
205 	line 1600-          // all lines from line 1600 to the end of the file
211   -    remove the given flags
220   Decorator flags add to the message-prefix, in order:
230 Note the regexp ``^[-+=][fslmpt_]+$`` matches a flags specification.
231 To clear all flags at once, use ``=_`` or ``-fslmpt``.
237 To activate debug messages for core code and built-in modules during
257 If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at
289 ``foo`` is extracted from the param-name, and applied to each query in
290 ``QUERY``, and only 1 match-spec of each type is allowed.
294 - modules do not need to define it explicitly
295 - every module gets it tacitly, whether they use pr_debug or not
296 - it doesn't appear in ``/sys/module/$module/parameters/``
299 For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or
300 enabled by ``-DDEBUG`` flag during compilation) can be disabled later via
303    echo "module module_name -p" > /proc/dynamic_debug/control
323   :#> ddcmd 'func svc_process -p'
337   // boot-args example, with newlines and comments for readability
352 Dynamic Debug is enabled via kernel config items::
357 If you do not want to enable dynamic debug globally (i.e. in some embedded
358 system), you may set ``CONFIG_DYNAMIC_DEBUG_CORE`` as basic support of dynamic
359 debug and add ``ccflags := -DDYNAMIC_DEBUG_MODULE`` into the Makefile of any
366 The following functions are cataloged and controllable when dynamic
374 Otherwise, they are off by default; ``ccflags += -DDEBUG`` or