On Tue, May 21, 2024 at 5:57 AM Łukasz Bartosik <ukaszb@xxxxxxxxxxxx> wrote: > > 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 I was going for an imperative "thou shalt" voice, rather than a descriptive/passive voice since its an API, and thou shalt use it "this way" ( s/creates/create/ if so) Do we / linux-doc have a preference in this regard ? > > > 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 > >
