On Thu, May 16, 2024 at 7:45 PM Jim Cromie <jim.cromie@xxxxxxxxx> wrote: > > Describe the 3 API macros providing dynamic_debug's classmaps > > DYNDBG_CLASSMAP_DEFINE - create, exports a module's classmap create, exports a module's classmap - > creates and exports a module's classmap > DYNDBG_CLASSMAP_USE - refer to exported map DYNDBG_CLASSMAP_USE - refers to exported map > DYNDBG_CLASSMAP_PARAM - bind control param to the classmap bind -> binds > DYNDBG_CLASSMAP_PARAM_REF + use module's storage - __drm_debug > + use module's storage - __drm_debug -> - uses module's storage (for example __drm_debug) > cc: linux-doc@xxxxxxxxxxxxxxx > Signed-off-by: Jim Cromie <jim.cromie@xxxxxxxxx> > --- > v5 adjustments per Randy Dunlap > v7 checkpatch fixes > v8 more > --- > .../admin-guide/dynamic-debug-howto.rst | 63 ++++++++++++++++++- > 1 file changed, 62 insertions(+), 1 deletion(-) > > diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst > index 6a8ce5a34382..742eb4230c6e 100644 > --- a/Documentation/admin-guide/dynamic-debug-howto.rst > +++ b/Documentation/admin-guide/dynamic-debug-howto.rst > @@ -225,7 +225,6 @@ 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``. > > - > Debug messages during Boot Process > ================================== > > @@ -375,3 +374,65 @@ 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 > +======================= > + > +Dyndbg allows selection/grouping of *prdbg* callsites using structural > +info: module, file, function, line. Classmaps allow authors to add > +their own domain-oriented groupings using class-names. Classmaps are > +exported, so they referencable from other modules. Typo referencable -> are referenceable > + > + # enable classes individually > + :#> ddcmd class DRM_UT_CORE +p > + :#> ddcmd class DRM_UT_KMS +p > + # or more selectively > + :#> ddcmd class DRM_UT_CORE module drm +p > + > +The "class FOO" syntax protects class'd prdbgs from generic overwrite:: > + > + # IOW this doesn't wipe any DRM.debug settings > + :#> ddcmd -p > + > +To support the DRM.debug parameter, DYNDBG_CLASSMAP_PARAM* updates all > +classes in a classmap, mapping param-bits 0..N onto the classes: > +DRM_UT_<*> for the DRM use-case. > + > +Dynamic Debug Classmap API > +========================== > + > +DYNDBG_CLASSMAP_DEFINE - modules use this to create classmaps, naming > +each of the classes (stringified enum-symbols: "DRM_UT_<*>"), and > +type, and mapping the class-names to consecutive _class_ids. > + > +By doing so, modules tell dyndbg that they have prdbgs with those > +class_ids, and they authorize dyndbg to accept "class FOO" for the > +module defining the classmap, and its contained classnames. > + > +DYNDBG_CLASSMAP_USE - drm drivers invoke this to ref the CLASSMAP that > +drm DEFINEs. This shares the classmap definition, and authorizes > +dyndbg to apply changes to the user module's class'd pr_debugs. It > +also tells dyndbg how to initialize the user's prdbgs at modprobe, > +based upon the current setting of the parent's controlling param. > + > +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) > + > +DYNDBG_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. > + > +This interface also enforces the DD_CLASS_TYPE_LEVEL_NUM relation > +amongst the contained classnames; all classes are independent in the > +control parser itself. > + > +Modules or module-groups (drm & drivers) can define multiple > +classmaps, as long as they share the limited 0..62 per-module-group > +_class_id range, without overlap. > + > +``#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. > -- > 2.45.0 >
