Re: [PATCH v6 31/31] docs/dyndbg: add classmap info to howto

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 11222 bytes --]

On Tue, Nov 18, 2025 at 01:18:41PM -0700, Jim Cromie wrote:
> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
> index 1ceadf4f28f9..adac32a5cd23 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst
> @@ -146,7 +146,9 @@ keywords are:::
>    "1-30" is valid range but "1 - 30" is not.
>  
>  
> -The meanings of each keyword are:
> +Keywords:::
> +
> +The meanings of each keyword are::
>  
>  func
>      The given string is compared against the function name
> @@ -194,16 +196,6 @@ format
>  	format "nfsd: SETATTR"  // a neater way to match a format with whitespace
>  	format 'nfsd: SETATTR'  // yet another way to match a format with whitespace
>  
> -class
> -    The given class_name is validated against each module, which may
> -    have declared a list of known class_names.  If the class_name is
> -    found for a module, callsite & class matching and adjustment
> -    proceeds.  Examples::
> -
> -	class DRM_UT_KMS	# a DRM.debug category
> -	class JUNK		# silent non-match
> -	// class TLD_*		# NOTICE: no wildcard in class names
> -
>  line
>      The given line number or range of line numbers is compared
>      against the line number of each ``pr_debug()`` callsite.  A single
> @@ -218,6 +210,24 @@ line
>  	line -1605          // the 1605 lines from line 1 to line 1605
>  	line 1600-          // all lines from line 1600 to the end of the file
>  
> +class
> +
> +    The given class_name is validated against each module, which may
> +    have declared a list of class_names it accepts.  If the class_name
> +    accepted by a module, callsite & class matching and adjustment
> +    proceeds.  Examples::
> +
> +	class DRM_UT_KMS	# a drm.debug category
> +	class JUNK		# silent non-match
> +	// class TLD_*		# NOTICE: no wildcard in class names
> +
> +.. note ::
> +
> +    Unlike other keywords, classes are "name-to-change", not
> +    "omitting-constraint-allows-change".  See Dynamic Debug Classmaps
> +
> +Flags:::
> +
>  The flags specification comprises a change operation followed
>  by one or more flag characters.  The change operation is one
>  of the characters::
> @@ -238,11 +248,15 @@ The flags are::
>    s    Include the source file name
>    l    Include line number
>  
> +Notes:
> +
> +To query without changing	``+_`` or ``-_``.
> +To clear all flags		``=_`` or ``-fslmpt``.
> +
>  For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only
>  the ``p`` flag has meaning, other flags are ignored.
>  
> -Note the regexp ``^[-+=][fslmpt_]+$`` matches a flags specification.
> -To clear all flags at once, use ``=_`` or ``-fslmpt``.
> +The regexp ``^[-+=][fslmpt_]+$`` matches a flags specification.
>  
>  
>  Debug messages during Boot Process
> @@ -394,3 +408,92 @@ just a shortcut for ``print_hex_dump(KERN_DEBUG)``.
>  For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is
>  its ``prefix_str`` argument, if it is constant string; or ``hexdump``
>  in case ``prefix_str`` is built dynamically.
> +
> +Dynamic Debug Classmaps
> +=======================
> +
> +The "class" keyword selects prdbgs based on author supplied,
> +domain-oriented names.  This complements the nested-scope keywords:
> +module, file, function, line.
> +
> +The main difference from the others: classes must be named to be
> +changed.  This protects them from unintended overwrite:
> +
> +  # IOW this cannot undo any drm.debug settings
> +  :#> ddcmd -p
> +
> +This protection is needed; /sys/module/drm/parameters/debug is ABI.
> +drm.debug is authoritative when dyndbg is not used, dyndbg-under-DRM
> +is an implementation detail, and must not behave erratically, just
> +because another admin fed >control something unrelated.
> +
> +So each class must be enabled individually (no wildcards):
> +
> +  :#> ddcmd class DRM_UT_CORE +p
> +  :#> ddcmd class DRM_UT_KMS +p
> +  # or more selectively
> +  :#> ddcmd class DRM_UT_CORE module drm +p
> +
> +That makes direct >control wordy and annoying, but it is a secondary
> +interface; it is not intended to replace the ABI, just slide in
> +underneath and reimplement the guaranteed behavior.  So DRM would keep
> +using the convenient way, and be able to trust it.
> +
> +  :#> echo 0x1ff > /sys/module/drm/parameters/debug
> +
> +That said, since the sysfs/kparam is the ABI, if the author omits the
> +CLASSMAP_PARAM, theres no ABI to guard, and he probably wants a less
> +pedantic >control interface.  In this case, protection is dropped.
> +
> +Dynamic Debug Classmap API
> +==========================
> +
> +DYNAMIC_DEBUG_CLASSMAP_DEFINE(clname,type,_base,classnames) - this maps
> +classnames (a list of strings) onto class-ids consecutively, starting
> +at _base.
> +
> +DYNAMIC_DEBUG_CLASSMAP_USE(clname) & _USE_(clname,_base) - modules
> +call this to refer to the var _DEFINEd elsewhere (and exported).
> +
> +DYNAMIC_DEBUG_CLASSMAP_PARAM(clname) - creates the sysfs/kparam,
> +maps/exposes bits 0..N as class-names.
> +
> +Classmaps are opt-in: modules invoke _DEFINE or _USE to authorize
> +dyndbg to update those classes.  "class FOO" queries are validated
> +against the classes, this finds the classid to alter; classes are not
> +directly selectable by their classid.
> +
> +NB: It is an inherent API limitation (due to int class_id defn) that
> +the following are possible:
> +
> +  // these errors should be caught in review
> +  __pr_debug_cls(0, "fake DRM_UT_CORE msg");  // this works
> +  __pr_debug_cls(62, "un-known classid msg"); // this compiles, does nothing
> +
> +There are 2 types of classmaps:
> +
> + DD_CLASS_TYPE_DISJOINT_BITS: classes are independent, like drm.debug
> + DD_CLASS_TYPE_LEVEL_NUM: classes are relative, ordered (V3 > V2)
> +
> +DYNAMIC_DEBUG_CLASSMAP_PARAM - modelled after module_param_cb, it
> +refers to a DEFINEd classmap, and associates it to the param's
> +data-store.  This state is then applied to DEFINEr and USEr modules
> +when they're modprobed.
> +
> +The PARAM interface also enforces the DD_CLASS_TYPE_LEVEL_NUM relation
> +amongst the contained classnames; all classes are independent in the
> +control parser itself.  There is no implied meaning in names like "V4"
> +or "PL_ERROR" vs "PL_WARNING".
> +
> +Modules or module-groups (drm & drivers) can define multiple
> +classmaps, as long as they (all the classmaps) share the limited 0..62
> +per-module-group _class_id range, without overlap.
> +
> +If a module encounters a conflict between 2 classmaps its _USEing or
> +_DEFINEing, it can invoke the extended _USE_(name,_base) macro to
> +de-conflict the respective ranges.
> +
> +``#define DEBUG`` will enable all pr_debugs in scope, including any
> +class'd ones.  This won't be reflected in the PARAM readback value,
> +but the class'd pr_debug callsites can be forced off by toggling the
> +classmap-kparam all-on then all-off.

Hmmm... the resulting htmldocs looks messy so I clean it up:

---- >8 ----
diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
index adac32a5cd232d..fd3dbae00cfc60 100644
--- a/Documentation/admin-guide/dynamic-debug-howto.rst
+++ b/Documentation/admin-guide/dynamic-debug-howto.rst
@@ -146,9 +146,10 @@ keywords are:::
   "1-30" is valid range but "1 - 30" is not.
 
 
-Keywords:::
+Keywords
+--------
 
-The meanings of each keyword are::
+The meanings of each keyword are:
 
 func
     The given string is compared against the function name
@@ -221,12 +222,13 @@ class
 	class JUNK		# silent non-match
 	// class TLD_*		# NOTICE: no wildcard in class names
 
-.. note ::
+.. note::
 
     Unlike other keywords, classes are "name-to-change", not
-    "omitting-constraint-allows-change".  See Dynamic Debug Classmaps
+    "omitting-constraint-allows-change".  See :ref:`dyndbg-classmaps`.
 
-Flags:::
+Flags
+-----
 
 The flags specification comprises a change operation followed
 by one or more flag characters.  The change operation is one
@@ -248,10 +250,10 @@ The flags are::
   s    Include the source file name
   l    Include line number
 
-Notes:
+.. note::
 
-To query without changing	``+_`` or ``-_``.
-To clear all flags		``=_`` or ``-fslmpt``.
+   * To query without changing:	``+_`` or ``-_``.
+   * To clear all flags:	``=_`` or ``-fslmpt``.
 
 For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only
 the ``p`` flag has meaning, other flags are ignored.
@@ -409,6 +411,8 @@ For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is
 its ``prefix_str`` argument, if it is constant string; or ``hexdump``
 in case ``prefix_str`` is built dynamically.
 
+.. _dyndbg-classmaps:
+
 Dynamic Debug Classmaps
 =======================
 
@@ -417,7 +421,7 @@ domain-oriented names.  This complements the nested-scope keywords:
 module, file, function, line.
 
 The main difference from the others: classes must be named to be
-changed.  This protects them from unintended overwrite:
+changed.  This protects them from unintended overwrite::
 
   # IOW this cannot undo any drm.debug settings
   :#> ddcmd -p
@@ -427,7 +431,7 @@ drm.debug is authoritative when dyndbg is not used, dyndbg-under-DRM
 is an implementation detail, and must not behave erratically, just
 because another admin fed >control something unrelated.
 
-So each class must be enabled individually (no wildcards):
+So each class must be enabled individually (no wildcards)::
 
   :#> ddcmd class DRM_UT_CORE +p
   :#> ddcmd class DRM_UT_KMS +p
@@ -437,7 +441,7 @@ So each class must be enabled individually (no wildcards):
 That makes direct >control wordy and annoying, but it is a secondary
 interface; it is not intended to replace the ABI, just slide in
 underneath and reimplement the guaranteed behavior.  So DRM would keep
-using the convenient way, and be able to trust it.
+using the convenient way, and be able to trust it::
 
   :#> echo 0x1ff > /sys/module/drm/parameters/debug
 
@@ -464,7 +468,7 @@ against the classes, this finds the classid to alter; classes are not
 directly selectable by their classid.
 
 NB: It is an inherent API limitation (due to int class_id defn) that
-the following are possible:
+the following are possible::
 
   // these errors should be caught in review
   __pr_debug_cls(0, "fake DRM_UT_CORE msg");  // this works
@@ -472,8 +476,8 @@ the following are possible:
 
 There are 2 types of classmaps:
 
- DD_CLASS_TYPE_DISJOINT_BITS: classes are independent, like drm.debug
- DD_CLASS_TYPE_LEVEL_NUM: classes are relative, ordered (V3 > V2)
+* DD_CLASS_TYPE_DISJOINT_BITS: classes are independent, like drm.debug
+* DD_CLASS_TYPE_LEVEL_NUM: classes are relative, ordered (V3 > V2)
 
 DYNAMIC_DEBUG_CLASSMAP_PARAM - modelled after module_param_cb, it
 refers to a DEFINEd classmap, and associates it to the param's

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]