[PATCH v4 21/21] dyndbg-doc: add classmap info to howto

[Randy Dunlap]

On 7/13/23 09:36, Jim Cromie wrote:
> Add some basic info on classmap usage and api
> 
> Signed-off-by: Jim Cromie <jim.cromie at gmail.com>
> ---
>  .../admin-guide/dynamic-debug-howto.rst       | 64 ++++++++++++++++++-
>  1 file changed, 63 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
> index 8dc668cc1216..878750ce8c1d 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst

> @@ -374,3 +373,66 @@ 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 generally selects *prdbg* callsites using structural info:
> +module, file, function, line.  Using classmaps, user modules can
> +organize/select pr_debug()s as they like.
> +
> +- classes coordinates/spans multiple modules
> +- complements the mod,file,func attrs
> +- keeps pr_debug's 0-off-cost JUMP_LABEL goodness
> +- isolates from other class'd and un-class'd pr_debugs() 
> +  (one doesnt mix 2 clients bank accounts)

          doesn't

> +
> +  # IOW this doesn't change DRM.debug settings
> +  #> echo -p > /proc/dynamic_debug/control
> +
> +  # change the classes by naming them explicitly (no wildcard here)
> +  #> echo class DRM_UT_CORE +p > /proc/dynamic_debug/control
> +
> +To support DRM.debug (/sys/module/drm/parameters/debug), dyndbg
> +provides DYNDBG_CLASSMAP_PARAM*.  It maps the categories/classes:
> +DRM_UT_CORE.. to bits 0..N, allowing to set all classes at once.
> +
> +Dynamic Debug Classmap API
> +==========================
> +
> +DYNDBG_CLASSMAP_DEFINE - modules create CLASSMAPs, naming the classes
> +and type, and mapping the class-names to consecutive _class_ids.  By
> +doing so, they tell dyndbg that they are using those class_ids, and
> +authorize dyndbg to manipulate the callsites by their class-names.
> +
> +Its expected that client modules will follow the DRM.debug model:
> +1. define their debug-classes using an enum type, where the enum
> +symbol and its integer value define both the classnames and class-ids.
> +2. use or macro-wrap __pr_debug_cls(ENUM_VAL, "hello world\n")
> +   
> +There are 2 types of classmaps:
> +
> + DD_CLASS_TYPE_DISJOINT_BITS: classes are independent, ala DRM.debug

                                                          a la
or just                                                   like

> + DD_CLASS_TYPE_LEVEL_NUM: classes are relative (Verbose3 > Verbose2)
> +
> +Both these classmap-types use the class-names/ENUM_VALs to validate
> +commands into >control.
> +
> +DYNDBG_CLASSMAP_PARAM - refs a DEFINEd classmap, exposing the set of

Is this:                   refers to a
?

> +defined classes to manipulation as a group.  This interface enforces
> +the relatedness of classes of DD_CLASS_TYPE_LEVEL_NUM typed classmaps;
> +all classes are independent in the >control parser itself.
> +
> +DYNDBG_CLASSMAP_USE - drm drivers use the CLASSMAP that drm DEFINEs.
> +This shares the classmap defn, and authorizes coordinated changes

                            definition,

> +amongst the CLASSMAP DEFINEr and multiple USErs.
> +
> +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 (__pr_debug_cls(id,fmt..)).  This won't be reflected in
> +the PARAM readback value, but the pr_debug callsites can be toggled
> +into agreement with the param.
> +

thanks.
-- 
~Randy