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

[Louis Chauvet]

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
> DYNDBG_CLASSMAP_USE    - refer to exported map
> DYNDBG_CLASSMAP_PARAM  - bind control param to the classmap
> DYNDBG_CLASSMAP_PARAM_REF + use module's storage - __drm_debug
> 
> TBD: some of this might be over-specification, or just over-talked.
> 
> NB: The _DEFINE & _USE model makes the user dependent on the definer,
> just like EXPORT_SYMBOL(__drm_debug) already does.
> 
> cc: linux-doc at vger.kernel.org
> Signed-off-by: Jim Cromie <jim.cromie at gmail.com>
> ---
> v5 adjustments per Randy Dunlap
> v7 checkpatch fixes
> v8 more
> v9 rewords
> ---
>   .../admin-guide/dynamic-debug-howto.rst       | 80 ++++++++++++++++++-
>   1 file changed, 79 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
> index d2928884c92b..9422dc4917d0 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst
> @@ -243,7 +243,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
>   ==================================
>   
> @@ -393,3 +392,82 @@ 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
> +=======================
> +
> +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?

> +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?

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