Date: Wed, 22 May 2024 16:01:44 +0200
From: Łukasz Bartosik <ukaszb@...omium.org>
To: jim.cromie@...il.com
Cc: jbaron@...mai.com, gregkh@...uxfoundation.org, 
	linux-kernel@...r.kernel.org, linux@...musvillemoes.dk, joe@...ches.com, 
	mcgrof@...nel.org, daniel.vetter@...ll.ch, tvrtko.ursulin@...ux.intel.com, 
	jani.nikula@...el.com, ville.syrjala@...ux.intel.com, seanpaul@...omium.org, 
	robdclark@...il.com, groeck@...gle.com, yanivt@...gle.com, bleung@...gle.com, 
	linux-doc@...r.kernel.org
Subject: Re: [PATCH v8-RESEND 19/33] dyndbg-doc: add classmap info to howto

On Tue, May 21, 2024 at 4:58 PM <jim.cromie@...il.com> wrote:
>
> On Tue, May 21, 2024 at 5:57 AM Łukasz Bartosik <ukaszb@...omium.org> wrote:
> >
> > On Thu, May 16, 2024 at 7:45 PM Jim Cromie <jim.cromie@...il.com> 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)
>

Makes sense, thanks for the explanation

> 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@...r.kernel.org
> > > Signed-off-by: Jim Cromie <jim.cromie@...il.com>
> > > ---
> > > 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
> > >

Powered by blists - more mailing lists