Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) Dynamic debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) +++++++++++++
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) This document describes how to use the dynamic debug (dyndbg) feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Dynamic debug is designed to allow you to dynamically enable/disable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) kernel code to obtain additional kernel information.  Currently, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) ``CONFIG_DYNAMIC_DEBUG`` is set, then all ``pr_debug()``/``dev_dbg()`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) ``print_hex_dump_debug()``/``print_hex_dump_bytes()`` calls can be dynamically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) enabled per-callsite.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) If you do not want to enable dynamic debug globally (i.e. in some embedded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) system), you may set ``CONFIG_DYNAMIC_DEBUG_CORE`` as basic support of dynamic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) debug and add ``ccflags := -DDYNAMIC_DEBUG_MODULE`` into the Makefile of any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) modules which you'd like to dynamically debug later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) If ``CONFIG_DYNAMIC_DEBUG`` is not set, ``print_hex_dump_debug()`` is just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) shortcut for ``print_hex_dump(KERN_DEBUG)``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) its ``prefix_str`` argument, if it is constant string; or ``hexdump``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26) in case ``prefix_str`` is built dynamically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) Dynamic debug has even more useful features:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30)  * Simple query language allows turning on and off debugging
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31)    statements by matching any combination of 0 or 1 of:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33)    - source filename
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34)    - function name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35)    - line number (including ranges of line numbers)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36)    - module name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37)    - format string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39)  * Provides a debugfs control file: ``<debugfs>/dynamic_debug/control``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40)    which can be read to display the complete list of known debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41)    statements, to help guide you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) Controlling dynamic debug Behaviour
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) ===================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) The behaviour of ``pr_debug()``/``dev_dbg()`` are controlled via writing to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) control file in the 'debugfs' filesystem. Thus, you must first mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) the debugfs filesystem, in order to make use of this feature.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) Subsequently, we refer to the control file as:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) ``<debugfs>/dynamic_debug/control``. For example, if you want to enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) printing from source file ``svcsock.c``, line 1603 you simply do::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53)   nullarbor:~ # echo 'file svcsock.c line 1603 +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) If you make a mistake with the syntax, the write will fail thus::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58)   nullarbor:~ # echo 'file svcsock.c wtf 1 +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60)   -bash: echo: write error: Invalid argument
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) Note, for systems without 'debugfs' enabled, the control file can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) found in ``/proc/dynamic_debug/control``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) Viewing Dynamic Debug Behaviour
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) You can view the currently configured behaviour of all the debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) statements via::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71)   nullarbor:~ # cat <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72)   # filename:lineno [module]function flags format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73)   net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74)   net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline       : %d\012"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75)   net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth         : %d\012"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76)   net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests     : %d\012"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77)   ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) You can also apply standard Unix text manipulation filters to this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) data, e.g.::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83)   nullarbor:~ # grep -i rdma <debugfs>/dynamic_debug/control  | wc -l
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84)   62
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86)   nullarbor:~ # grep -i tcp <debugfs>/dynamic_debug/control | wc -l
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87)   42
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) The third column shows the currently enabled flags for each debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) statement callsite (see below for definitions of the flags).  The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) default value, with no flags enabled, is ``=_``.  So you can view all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) the debug statement callsites with any non-default flags::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94)   nullarbor:~ # awk '$3 != "=_"' <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95)   # filename:lineno [module]function flags format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96)   net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98) Command Language Reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) At the lexical level, a command comprises a sequence of words separated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) by spaces or tabs.  So these are all equivalent::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)   nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)   nullarbor:~ # echo -n '  file   svcsock.c     line  1603 +p  ' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)   nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) Command submissions are bounded by a write() system call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) Multiple commands can be written together, separated by ``;`` or ``\n``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)   ~# echo "func pnpacpi_get_resources +p; func pnp_assign_mem +p" \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)      > <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) If your query set is big, you can batch them too::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)   ~# cat query-batch-file > <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Another way is to use wildcards. The match rule supports ``*`` (matches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) zero or more characters) and ``?`` (matches exactly one character). For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) example, you can match all usb drivers::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)   ~# echo "file drivers/usb/* +p" > <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) At the syntactical level, a command comprises a sequence of match
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) specifications, followed by a flags change specification::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)   command ::= match-spec* flags-spec
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) The match-spec's are used to choose a subset of the known pr_debug()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) callsites to which to apply the flags-spec.  Think of them as a query
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) with implicit ANDs between each pair.  Note that an empty list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) match-specs will select all debug statement callsites.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) A match specification comprises a keyword, which controls the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) attribute of the callsite to be compared, and a value to compare
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) against.  Possible keywords are:::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)   match-spec ::= 'func' string |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) 		 'file' string |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 		 'module' string |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) 		 'format' string |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 		 'line' line-range
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)   line-range ::= lineno |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) 		 '-'lineno |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) 		 lineno'-' |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) 		 lineno'-'lineno
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)   lineno ::= unsigned-int
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)   ``line-range`` cannot contain space, e.g.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)   "1-30" is valid range but "1 - 30" is not.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) The meanings of each keyword are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) func
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)     The given string is compared against the function name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)     of each callsite.  Example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) 	func svc_tcp_accept
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) 	func *recv*		# in rfcomm, bluetooth, ping, tcp
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170)     The given string is compared against either the src-root relative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)     pathname, or the basename of the source file of each callsite.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172)     Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) 	file svcsock.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 	file kernel/freezer.c	# ie column 1 of control file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) 	file drivers/usb/*	# all callsites under it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 	file inode.c:start_*	# parse :tail as a func (above)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) 	file inode.c:1-100	# parse :tail as a line-range (above)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)     The given string is compared against the module name
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)     of each callsite.  The module name is the string as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)     seen in ``lsmod``, i.e. without the directory or the ``.ko``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)     suffix and with ``-`` changed to ``_``.  Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) 	module sunrpc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) 	module nfsd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) 	module drm*	# both drm, drm_kms_helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191)     The given string is searched for in the dynamic debug format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)     string.  Note that the string does not need to match the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)     entire format, only some part.  Whitespace and other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)     special characters can be escaped using C octal character
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)     escape ``\ooo`` notation, e.g. the space character is ``\040``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)     Alternatively, the string can be enclosed in double quote
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)     characters (``"``) or single quote characters (``'``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)     Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) 	format svcrdma:         // many of the NFS/RDMA server pr_debugs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) 	format readahead        // some pr_debugs in the readahead cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) 	format nfsd:\040SETATTR // one way to match a format with whitespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) 	format "nfsd: SETATTR"  // a neater way to match a format with whitespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) 	format 'nfsd: SETATTR'  // yet another way to match a format with whitespace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) line
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)     The given line number or range of line numbers is compared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)     against the line number of each ``pr_debug()`` callsite.  A single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)     line number matches the callsite line number exactly.  A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)     range of line numbers matches any callsite between the first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)     and last line number inclusive.  An empty first number means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)     the first line in the file, an empty last line number means the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)     last line number in the file.  Examples::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) 	line 1603           // exactly line 1603
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) 	line 1600-1605      // the six lines from line 1600 to line 1605
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) 	line -1605          // the 1605 lines from line 1 to line 1605
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) 	line 1600-          // all lines from line 1600 to the end of the file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) The flags specification comprises a change operation followed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) by one or more flag characters.  The change operation is one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) of the characters::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)   -    remove the given flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)   +    add the given flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226)   =    set the flags to the given flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) The flags are::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230)   p    enables the pr_debug() callsite.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)   f    Include the function name in the printed message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232)   l    Include line number in the printed message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)   m    Include module name in the printed message
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)   t    Include thread ID in messages not generated from interrupt context
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)   _    No flags are set. (Or'd with others on input)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only ``p`` flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) have meaning, other flags ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) For display, the flags are preceded by ``=``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) (mnemonic: what the flags are currently equal to).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) To clear all flags at once, use ``=_`` or ``-flmpt``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) Debug messages during Boot Process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) To activate debug messages for core code and built-in modules during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) the boot process, even before userspace and debugfs exists, use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) ``dyndbg="QUERY"``, ``module.dyndbg="QUERY"``, or ``ddebug_query="QUERY"``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) (``ddebug_query`` is obsoleted by ``dyndbg``, and deprecated).  QUERY follows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) the syntax described above, but must not exceed 1023 characters.  Your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) bootloader may impose lower limits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) These ``dyndbg`` params are processed just after the ddebug tables are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) processed, as part of the early_initcall.  Thus you can enable debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) messages in all code run after this early_initcall via this boot
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) On an x86 system for example ACPI enablement is a subsys_initcall and::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)    dyndbg="file ec.c +p"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) will show early Embedded Controller transactions during ACPI setup if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) your machine (typically a laptop) has an Embedded Controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) PCI (or other devices) initialization also is a hot candidate for using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) this boot parameter for debugging purposes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) boot time, without effect, but will be reprocessed when module is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) loaded later. ``ddebug_query=`` and bare ``dyndbg=`` are only processed at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) boot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) Debug Messages at Module Initialization Time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) ============================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) ``foo.params``, strips ``foo.``, and passes them to the kernel along with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) params given in modprobe args or ``/etc/modprob.d/*.conf`` files,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) in the following order:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) 1. parameters given via ``/etc/modprobe.d/*.conf``::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 	options foo dyndbg=+pt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) 	options foo dyndbg # defaults to +p
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) 2. ``foo.dyndbg`` as given in boot args, ``foo.`` is stripped and passed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) 	foo.dyndbg=" func bar +p; func buz +mp"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) 3. args to modprobe::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) 	modprobe foo dyndbg==pmf # override previous settings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) These ``dyndbg`` queries are applied in order, with last having final say.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) This allows boot args to override or modify those from ``/etc/modprobe.d``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) (sensible, since 1 is system wide, 2 is kernel or boot specific), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) modprobe args to override both.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) In the ``foo.dyndbg="QUERY"`` form, the query must exclude ``module foo``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) ``foo`` is extracted from the param-name, and applied to each query in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) ``QUERY``, and only 1 match-spec of each type is allowed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) The ``dyndbg`` option is a "fake" module parameter, which means:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) - modules do not need to define it explicitly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) - every module gets it tacitly, whether they use pr_debug or not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) - it doesn't appear in ``/sys/module/$module/parameters/``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)   To see it, grep the control file, or inspect ``/proc/cmdline.``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) enabled by ``-DDEBUG`` flag during compilation) can be disabled later via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) the debugfs interface if the debug messages are no longer needed::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)    echo "module module_name -p" > <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) Examples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) ========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)   // enable the message at line 1603 of file svcsock.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)   nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)   // enable all the messages in file svcsock.c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)   nullarbor:~ # echo -n 'file svcsock.c +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)   // enable all the messages in the NFS server module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334)   nullarbor:~ # echo -n 'module nfsd +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337)   // enable all 12 messages in the function svc_process()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)   nullarbor:~ # echo -n 'func svc_process +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)   // disable all 12 messages in the function svc_process()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342)   nullarbor:~ # echo -n 'func svc_process -p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)   // enable messages for NFS calls READ, READLINK, READDIR and READDIR+.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)   nullarbor:~ # echo -n 'format "nfsd: READ" +p' >
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) 				<debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)   // enable messages in files of which the paths include string "usb"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)   nullarbor:~ # echo -n '*usb* +p' > <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)   // enable all messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)   nullarbor:~ # echo -n '+p' > <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)   // add module, function to all enabled messages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)   nullarbor:~ # echo -n '+mf' > <debugfs>/dynamic_debug/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)   // boot-args example, with newlines and comments for readability
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)   Kernel command line: ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)     // see whats going on in dyndbg=value processing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)     dynamic_debug.verbose=1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)     // enable pr_debugs in 2 builtins, #cmt is stripped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363)     dyndbg="module params +p #cmt ; module sys +p"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)     // enable pr_debugs in 2 functions in a module loaded later
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)     pc87360.dyndbg="func pc87360_init_device +p; func pc87360_find +p"