[PATCH v2 33/59] docs/dyndbg: add classmap info to howto (TBD)

[jim.cromie at gmail.com]

On Mon, Mar 24, 2025 at 9:23 AM Louis Chauvet <louis.chauvet at bootlin.com> wrote:
>
>
>
> Le 20/03/2025 à 19:52, Jim Cromie a écrit :
> > Describe the 3 API macros providing dynamic_debug's classmaps
> >
> > DYNDBG_CLASSMAP_DEFINE - create & export a classmap
...
> > +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: class'd prdbgs must be named to
> > +be changed.  This protects them from generic overwrite:
> > +
> > +  # IOW this cannot undo any DRM.debug settings
> > +  :#> ddcmd -p
>
> Patch 30/59 just dropped this behavior no?

Yes, that chunk is obsolete, given my capitulation :-/


>
> > +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
> > +
> > +Or the legacy/normal (more convenient) way:
> > +
> > +  :#> echo 0x1ff > /sys/module/drm/parameters/debug
> > +
> > +Dynamic Debug Classmap API
> > +==========================
> > +
> > +DRM.debug is built upon:
> > +  ~23 macros, all passing a DRM_UT_* constant as arg-1.
> > +  ~5000 calls to them, across drivers/gpu/drm/*
> > +  bits in /sys/module/drm/parameters/debug control all DRM_UT_* together
> > +
> > +The const short ints are good for optimizing compilers; a classmaps
> > +design goal was to keep that.  So basically .classid === category.
> > +
> > +And since prdbgs are cataloged with just a DRM_UT_* to identify them,
> > +the "class" keyword maps known classnames to those reserved IDs, and
> > +by explicitly requiring "class FOO" in queries, we protect FOO class'd
> > +debugs from overwrite by generic queries.
> > +
> > +Its expected that other classmap users will also provide debug-macros
> > +using an enum-defined categorization scheme like DRM's, and dyndbg can
> > +be adapted under them similarly.
> > +
> > +DYNAMIC_DEBUG_CLASSMAP_DEFINE(var,type,_base,classnames) - this maps
> > +classnames 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.
> > +
> > +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 share the limited 0..62 per-module-group
> > +_class_id range, without overlap.
>
> Maybe clarify that a driver using _USE macro should take care that he
> only use distinct non-overlaping classmaps?

ack

>
> > +``#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
>
>