From: Jim Cromie <jim.cromie@gmail.com>
To: linux-kernel@vger.kernel.org, jbaron@akamai.com,
gregkh@linuxfoundation.org, dri-devel@lists.freedesktop.org,
amd-gfx@lists.freedesktop.org,
intel-gvt-dev@lists.freedesktop.org,
intel-gfx@lists.freedesktop.org
Cc: daniel.vetter@ffwll.ch, jani.nikula@intel.com,
ville.syrjala@linux.intel.com, seanpaul@chromium.org,
robdclark@gmail.com, groeck@google.com, yanivt@google.com,
bleung@google.com, linux-doc@vger.kernel.org,
Jim Cromie <jim.cromie@gmail.com>
Subject: [PATCH v7 18/25] dyndbg-doc: add classmap info to howto
Date: Thu, 12 Oct 2023 11:21:29 -0600 [thread overview]
Message-ID: <20231012172137.3286566-19-jim.cromie@gmail.com> (raw)
In-Reply-To: <20231012172137.3286566-1-jim.cromie@gmail.com>
Add some basic info on classmap usage and api
Signed-off-by: Jim Cromie <jim.cromie@gmail.com>
---
v5- adjustments per Randy Dunlap, me
---
.../admin-guide/dynamic-debug-howto.rst | 59 ++++++++++++++++++-
1 file changed, 58 insertions(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
index 0b3d39c610d9..d8813dcc394a 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,61 @@ 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.
+
+ # 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 are have prdbgs with those
+class_ids, and they authorize dyndbg to accept "class FOO" for module
+defining that classname.
+
+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 - refers to 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 invoke this to ref the the CLASSMAP
+that drm DEFINEs. This shares the classmap definition, and authorizes
+dyndbg to apply changes to the using modules class'd pr_debugs. It
+also tells dyndbg how to initialize the user's prdbgs at modprobe.
+
+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 pr_debug callsites can be toggled into agreement with the
+param.
--
2.41.0
next prev parent reply other threads:[~2023-10-12 17:23 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-10-12 17:21 [PATCH v7 00/25] fix DRM_USE_DYNAMIC_DEBUG=y regression Jim Cromie
2023-10-12 17:21 ` [PATCH v7 01/25] test-dyndbg: fixup CLASSMAP usage error Jim Cromie
2023-10-12 17:21 ` [PATCH v7 02/25] dyndbg: reword "class unknown," to "class:_UNKNOWN_" Jim Cromie
2023-10-12 17:21 ` [PATCH v7 03/25] dyndbg: make ddebug_class_param union members same size Jim Cromie
2023-10-12 17:21 ` [PATCH v7 04/25] dyndbg: replace classmap list with a vector Jim Cromie
2023-10-12 17:21 ` [PATCH v7 05/25] dyndbg: ddebug_apply_class_bitmap - add module arg, select on it Jim Cromie
2023-10-12 17:21 ` [PATCH v7 06/25] dyndbg: split param_set_dyndbg_classes to module/wrapper fns Jim Cromie
2023-10-12 17:21 ` [PATCH v7 07/25] dyndbg: drop NUM_TYPE_ARRAY Jim Cromie
2023-10-12 17:21 ` [PATCH v7 08/25] dyndbg: reduce verbose/debug clutter Jim Cromie
2023-10-12 17:21 ` [PATCH v7 09/25] dyndbg: silence debugs with no-change updates Jim Cromie
2023-10-12 17:21 ` [PATCH v7 10/25] dyndbg: tighten ddebug_class_name() 1st arg type Jim Cromie
2023-10-12 17:21 ` [PATCH v7 11/25] dyndbg: tighten fn-sig of ddebug_apply_class_bitmap Jim Cromie
2023-10-12 17:21 ` [PATCH v7 12/25] dyndbg: reduce verbose=3 messages in ddebug_add_module Jim Cromie
2023-10-12 17:21 ` [PATCH v7 13/25] dyndbg-API: remove DD_CLASS_TYPE_(DISJOINT|LEVEL)_NAMES and code Jim Cromie
2023-10-12 17:21 ` [PATCH v7 14/25] dyndbg-API: fix CONFIG_DRM_USE_DYNAMIC_DEBUG regression Jim Cromie
2023-10-12 17:21 ` [PATCH v7 15/25] dyndbg: add for_each_boxed_vector Jim Cromie
2023-10-12 17:21 ` [PATCH v7 16/25] dyndbg: refactor ddebug_classparam_clamp_input Jim Cromie
2023-10-12 17:21 ` [PATCH v7 17/25] dyndbg-API: promote DYNDBG_CLASSMAP_PARAM to API Jim Cromie
2023-10-12 17:21 ` Jim Cromie [this message]
2023-10-12 17:21 ` [PATCH v7 19/25] dyndbg: reserve flag bit _DPRINTK_FLAGS_PREFIX_CACHED Jim Cromie
2023-10-12 17:21 ` [PATCH v7 20/25] dyndbg: add _DPRINTK_FLAGS_INCL_LOOKUP Jim Cromie
2023-10-12 17:21 ` [PATCH v7 21/25] dyndbg: refactor *dynamic_emit_prefix Jim Cromie
2023-10-12 17:21 ` [PATCH v7 22/25] dyndbg: improve err report in attach_user_module_classes Jim Cromie
2023-10-12 17:21 ` [PATCH v7 23/25] drm: use correct ccflags-y spelling Jim Cromie
2023-10-12 17:21 ` [PATCH v7 24/25] drm-drivers: DRM_CLASSMAP_USE in 2nd batch of drivers, helpers Jim Cromie
2023-10-12 17:21 ` [PATCH v7 25/25] drm: restore CONFIG_DRM_USE_DYNAMIC_DEBUG un-BROKEN Jim Cromie
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20231012172137.3286566-19-jim.cromie@gmail.com \
--to=jim.cromie@gmail.com \
--cc=amd-gfx@lists.freedesktop.org \
--cc=bleung@google.com \
--cc=daniel.vetter@ffwll.ch \
--cc=dri-devel@lists.freedesktop.org \
--cc=gregkh@linuxfoundation.org \
--cc=groeck@google.com \
--cc=intel-gfx@lists.freedesktop.org \
--cc=intel-gvt-dev@lists.freedesktop.org \
--cc=jani.nikula@intel.com \
--cc=jbaron@akamai.com \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=robdclark@gmail.com \
--cc=seanpaul@chromium.org \
--cc=ville.syrjala@linux.intel.com \
--cc=yanivt@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).