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
signature.asc
Description: PGP signature
