[PATCH 22/64] docs-dyndbg: improve howto classmaps api section

[Jim Cromie]

reword the classmaps-api section to better explain how it is modelled
on DRM, and (a little bit) to steer clear of designated-inits in the
_DEFINE description.

probably just squash this back in

Signed-off-by: Jim Cromie <jim.cromie at gmail.com>
---
 .../admin-guide/dynamic-debug-howto.rst       | 66 ++++++++++++-------
 include/linux/dynamic_debug.h                 | 14 ++--
 2 files changed, 49 insertions(+), 31 deletions(-)

diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
index 89d94aab41ec..391e40a510c9 100644
--- a/Documentation/admin-guide/dynamic-debug-howto.rst
+++ b/Documentation/admin-guide/dynamic-debug-howto.rst
@@ -383,42 +383,58 @@ 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.
+The "class" keyword selects prdbgs based on author supplied,
+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:
+
+  # IOW this cannot undo any DRM.debug settings
+  :#> ddcmd -p
+
+So each class must be enabled individually (no wildcards):
 
-  # 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
+Or the legacy/normal (more convenient) way:
 
-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.
+  :#> echo 0x1ff > /sys/module/drm/parameters/debug
 
 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.
+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
+
+The const short ints are good for optimizing compilers; a classmaps
+design goal was to keep that.  So basically .classid === category.
+
+And since prdbgs are cataloged with just a DRM_UT_* to identify them,
+the "class" keyword maps known classnames to those reserved IDs, and
+by explicitly requiring "class FOO" in queries, we protect FOO class'd
+debugs from overwrite by generic queries.
+
+Its expected that other classmap users will also provide debug-macros
+using an enum-defined categorization scheme like DRM's, and dyndbg can
+be adapted under them similarly.
+
+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.
 
-By doing so, modules tell dyndbg that they have prdbgs with those
-class_ids, and they authorize dyndbg to accept "class FOO" for the
-module defining the classmap, and its contained classnames.
+DYNDBG_CLASSMAP_USE(var) - modules call this to refer to the var
+_DEFINEd elsewhere (and exported).
 
-DYNDBG_CLASSMAP_USE - drm drivers invoke this to ref the CLASSMAP that
-drm DEFINEs.  This shares the classmap definition, and authorizes
-dyndbg to apply changes to the user module's class'd pr_debugs.  It
-also tells dyndbg how to initialize the user's prdbgs at modprobe,
-based upon the current setting of the parent's controlling param.
+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:
 
@@ -429,9 +445,9 @@ DYNDBG_CLASSMAP_PARAM - modelled after module_param_cb, it refers to a
 DEFINEd classmap, and associates it to the param's data-store.  This
 state is then applied to DEFINEr and USEr modules when they're modprobed.
 
-This interface also enforces the DD_CLASS_TYPE_LEVEL_NUM relation
+The PARAM interface also enforces the DD_CLASS_TYPE_LEVEL_NUM relation
 amongst the contained classnames; all classes are independent in the
-control parser itself.
+control parser itself; there is no implied meaning in names like "V4".
 
 Modules or module-groups (drm & drivers) can define multiple
 classmaps, as long as they share the limited 0..62 per-module-group
diff --git a/include/linux/dynamic_debug.h b/include/linux/dynamic_debug.h
index 707abe58f1f7..8090d95b68e0 100644
--- a/include/linux/dynamic_debug.h
+++ b/include/linux/dynamic_debug.h
@@ -82,15 +82,17 @@ struct ddebug_class_map {
 
 /*
  * dyndbg-classmaps is closely modelled on DRM.debug, which has:
- *   ~23 macros, each passing DRM_UT_* as 1st arg
+ *    10 debug categories: DRM_UT_*
+ *   ~23 categorized debug macros, each passing DRM_UT_* as 1st arg
  *   ~5000 calls to them, across all of drivers/gpu/drm/
- *   Optimizing compilers handle this well.
  *
- * So dyndbg maps known classnames to limited (0..62) .classids, and
- * insists classes are selected by name for adjustment.
+ * Optimizing compilers handle this well, so dyndbg preserves it,
+ * keeping the DRM_UT_* values in each site's _ddebug.class_id.
  *
- * modules either DEFINE classnames, or USE names defined elsewhere
- * (in another module).  This supports classnames defined over subsystems.
+ * Dyndbg protects (DRM's) class'd prdbgs from generic alteration by
+ * requiring "class DRM_UT_*" in >control commands; so modules
+ * deploying classmaps must either _DEFINE a map & classnames, or
+ * reference/_USE one defined elsewhere (in the subsystem).
  */
 /**
  * DYNDBG_CLASSMAP_DEFINE - define debug classes used by a module.
-- 
2.46.2