[v4,21/21] dyndbg-doc: add classmap info to howto
Commit Message
Add some basic info on classmap usage and api
Signed-off-by: Jim Cromie <jim.cromie@gmail.com>
---
.../admin-guide/dynamic-debug-howto.rst | 64 ++++++++++++++++++-
1 file changed, 63 insertions(+), 1 deletion(-)
Comments
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@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.
On Thu, Jul 13, 2023 at 1:13 PM Randy Dunlap <rdunlap@infradead.org> wrote:
>
>
>
> 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@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
>
thanks Randy,
got this, and the rest.
@@ -224,7 +224,6 @@ the ``p`` flag has meaning, other flags are ignored.
Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification.
To clear all flags at once, use ``=_`` or ``-flmpt``.
-
Debug messages during Boot Process
==================================
@@ -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)
+
+ # 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
+ 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
+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
+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.
+