[PATCH 29/63] dyndbg-doc: add classmap info to howto

[jim.cromie at gmail.com]

hi Sanjaya,

thanks for reading this. Let me back up and ask a bigger question,

How much of this is excessive explanation?

most devs would look for a test-*, or a sample/* or an existing use,
And the new macros already have their kdoc where it belongs,
so this mostly restates api, and might not belong in admin-guide ??

I now know enough to look for test-*s

On Thu, Oct 31, 2024 at 11:02 PM Bagas Sanjaya <bagasdotme at gmail.com> wrote:

> On Thu, Oct 31, 2024 at 02:44:03AM -0600, Jim Cromie wrote:
> > +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
> > +
> > +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
>
> Format command sequences as literal code blocks (like in the rest of docs):
>

I dont know what this means (yet), will do.



>
> ---- >8 ----
> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst
> b/Documentation/admin-guide/dynamic-debug-howto.rst
> index 3068d134fcc6d9..a826b972461fe5 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst
> @@ -388,19 +388,19 @@ 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:
> +be changed.  This protects them from generic overwrite::
>
>    # IOW this cannot undo any DRM.debug settings
>    :#> ddcmd -p
>
> -So each class must be enabled individually (no wildcards):
> +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:
> +Or the legacy/normal (more convenient) way::
>
>    :#> echo 0x1ff > /sys/module/drm/parameters/debug
>
> > +DYNDBG_CLASSMAP_DEFINE(var,type,_base,classnames) - this maps
> > +classnames onto class-ids starting at _base, it also maps the
> > +names onto CLASSMAP_PARAM bits 0..N.
> > +
> > +DYNDBG_CLASSMAP_USE(var) - modules call this to refer to the var
> > +_DEFINEd elsewhere (and exported).
>
> Shouldn't these DYNDBG_CLASSMAP_* descriptions be list?
>


I dont know what you mean here.



>
> > +
> > +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)
>
> For lists, format them as such otherwise these will be outputted as long
> paragraphs:
>
> ---- >8 ----
> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst
> b/Documentation/admin-guide/dynamic-debug-howto.rst
> index a826b972461fe5..c70e34f01822a2 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst
> @@ -408,9 +408,10 @@ 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
> +
> +- 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.
> @@ -438,8 +439,8 @@ 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)
> +- ``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
>
> Thanks.
>
> --
> An old man doll... just what I always wanted! - Clara
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/intel-gfx-trybot/attachments/20241103/e794a982/attachment.htm>