| Message ID | 20230713163626.31338-22-jim.cromie@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | fix DRM_USE_DYNAMIC_DEBUG regression | expand |
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.
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 @@ -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. +
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(-)