hi Louis, thx for the nudge. On Mon, Sep 8, 2025 at 8:38 AM Louis Chauvet <louis.chau...@bootlin.com> wrote:
> \ > > Le 03/08/2025 à 05:57, Jim Cromie a écrit : > > Describe the 3 API macros providing dynamic_debug's classmaps > > > > DYNDBG_CLASSMAP_DEFINE - create & export a classmap > > DYNDBG_CLASSMAP_USE - refer to exported map > > DYNDBG_CLASSMAP_PARAM - bind control param to the classmap > > DYNDBG_CLASSMAP_PARAM_REF + use module's storage - __drm_debug > > I should note: classmaps-v1 made some bad-taste naming choices, 1st was the shortening: DYNDBG_ These are invoked once per module, so we can afford full names. So series drops DYNDBG_ prefix, replaces it with DYNAMIC_DEBUG_, and this commit-msg is now corrected > > TBD: some of this might be over-specification, or just over-talked. > > > > NB: The _DEFINE & _USE model makes the user dependent on the definer, > > just like EXPORT_SYMBOL(__drm_debug) already does. > > > > cc: linux-...@vger.kernel.org > > Signed-off-by: Jim Cromie <jim.cro...@gmail.com> > > Reviewed-by: Louis Chauvet <louis.chau...@bootlin.com> > > > --- > > v3- rework protection around PARAM > > > > v0.5 adjustments per Randy Dunlap > > v0.7 checkpatch fixes > > v0.8 more > > v0.9 rewords > > > > fixup-howto > > --- > > .../admin-guide/dynamic-debug-howto.rst | 137 ++++++++++++++++-- > > 1 file changed, 126 insertions(+), 11 deletions(-) > > > > diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst > b/Documentation/admin-guide/dynamic-debug-howto.rst > > index 1ceadf4f28f9f..556e00299ed35 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:: > > @@ -394,3 +404,108 @@ 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 generic 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's PARAM > > +cannot undermine that guarantee just because its optional for DRM to > > +use it. > > + > > + :#> echo 0x1ff > /sys/module/drm/parameters/debug > > + > > +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 it. > > + > > +However, since the sysfs/kparam is the ABI, if a classmap DEFINEr > > +doesn't also add a _CLASSMAP_PARAM, there is no ABI, and no protection > > +is needed. In that case, class'd prdbgs would be enabled/disabled by > > +legacy (class-less) queries, as a convenience, and because there's no > > +need to enforce irrelevant rules. > > + > > + > > +Dynamic Debug Classmap API > > +========================== > > + > > +DRM.debug is built upon: > > + > > +- enum drm_debug_category: DRM_UT_<*> - <T> for short > > +- 23 categorized api macros: drm_dbg_<T>(), DRM_DEBUG_<T>() > > +- 5000 calls to them > > +- all calling to __pr_debug_cls(<T>, ...) > > + > > +Those compile-time const short ints are good for optimizing compilers; > > +a primary classmaps design goal was to keep that property. > > +So basically .class_id === category. > > + > > +Then we use the drm_categories DRM_UT_* enum for both the classnames > > +(stringified enum symbols) and their numeric values. > > + > > +Its expected that future users will also use categorized macros and an > > +enum-defined categorization scheme like DRM's, with dyndbg inserted in > > +similarly. > > + > > +DYNAMIC_DEBUG_CLASSMAP_DEFINE(var,type,_base,classnames) - this maps > > +classnames (a list of strings) onto class-ids consecutively, starting > > +at _base, it also maps the names onto CLASSMAP_PARAM bits 0..N. > > + > > +DYNAMIC_DEBUG_CLASSMAP_USE(var) - modules call this to refer to the > > +var _DEFINEd elsewhere (and exported). > > + > > +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 that the following are possible: > > + > > + // these would 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". > > + > > +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, we > > +can extend the _USE macro with an offset to allow de-conflicting the > > +respective ranges. Or they use the DEFINErs macro-api, but with new > > +enum symbols. > > + > > +``#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. > > -- > Louis Chauvet, Bootlin > Embedded Linux and Kernel engineering > https://bootlin.com > >
