Received-SPF: pass (google.com: domain of linux-kernel+bounces-185128-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Precedence: bulk
MIME-Version: 1.0
References: <20240516174357.26755-1-jim.cromie@gmail.com> <20240516174357.26755-20-jim.cromie@gmail.com>
 <CALwA+NYNPfpyM8ZH3L-fbrqSpzKw61gZU+u_uxP6tjnFe7UJ-w@mail.gmail.com>
In-Reply-To: <CALwA+NYNPfpyM8ZH3L-fbrqSpzKw61gZU+u_uxP6tjnFe7UJ-w@mail.gmail.com>
From: jim.cromie@gmail.com
Date: Tue, 21 May 2024 08:57:57 -0600
Message-ID: <CAJfuBxyMBh-1BQMqgXj1GBZ=pwbFK3PuBhRDzM7DNd4ML2hSzw@mail.gmail.com>
Subject: Re: [PATCH v8-RESEND 19/33] dyndbg-doc: add classmap info to howto
To: =?UTF-8?Q?=C5=81ukasz_Bartosik?= <ukaszb@chromium.org>
Cc: jbaron@akamai.com, gregkh@linuxfoundation.org, 
	linux-kernel@vger.kernel.org, linux@rasmusvillemoes.dk, joe@perches.com, 
	mcgrof@kernel.org, daniel.vetter@ffwll.ch, tvrtko.ursulin@linux.intel.com, 
	jani.nikula@intel.com, ville.syrjala@linux.intel.com, seanpaul@chromium.org, 
	robdclark@gmail.com, groeck@google.com, yanivt@google.com, bleung@google.com, 
	linux-doc@vger.kernel.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Tue, May 21, 2024 at 5:57=E2=80=AFAM =C5=81ukasz Bartosik <ukaszb@chromi=
um.org> wrote:
>
> On Thu, May 16, 2024 at 7:45=E2=80=AFPM Jim Cromie <jim.cromie@gmail.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 cl=
assmap

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@vger.kernel.org
> > Signed-off-by: Jim Cromie <jim.cromie@gmail.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/Docume=
ntation/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 ``^[-+=3D][fslmpt_]+$`` matches a flags specification.
> >  To clear all flags at once, use ``=3D_`` or ``-fslmpt``.
> >
> > -
> >  Debug messages during Boot Process
> >  =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> >
> > @@ -375,3 +374,65 @@ just a shortcut for ``print_hex_dump(KERN_DEBUG)``=
.
> >  For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format stri=
ng is
> >  its ``prefix_str`` argument, if it is constant string; or ``hexdump``
> >  in case ``prefix_str`` is built dynamically.
> > +
> > +Dynamic Debug classmaps
> > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> > +
> > +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
> > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D
> > +
> > +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 modprob=
ed.
> > +
> > +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
> >