Re: [PATCH v8-RESEND 19/33] dyndbg-doc: add classmap info to howto

[Łukasz Bartosik]

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

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