[PATCH v9-resend 53/54] dyndbg: tighten up kdoc about DYNDBG_CLASSMAP_* macros

[Jim Cromie]

The DYNDBG_CLASSMAP_DEFINE expects a list of classnames, and
maps them to consecutive classids starting at _base.  That
1- list-of-classnames can be syntactically replaced by a
2- designated-initializers-list/map.

But this creates ambiguity. The 1st thing the macro does:

   static const char *_var##_classnames[] = { __VA_ARGS__ };

This construct accepts either list form, cannot distinguish between
them, and they place data differently.

1. puts the string values into array[0..N-1]
2. puts them into array[_base..N+_base-1]

2 wastes 0.._base-1 indices, and more importantly, also spec's _base
twice: as a parameter, and then in the designated-initializers-list/map.

Further, the code is written for a contiguous range of classnames and
classids, and passing a map allows casual violation of this reasonable
design choice.

In particular, DRM_UT_* is a contiguous range, and each maps to a bit
in drm.debug.  The macro interface shouldn't suggest a sparse map is
possible.

So reword DYNDBG_CLASSMAP_* macro kdoc to more actively guide reader
away from designated initializers here.

TBD probably squash this back into the patchset.

CC: ville.syrjala at linux.intel.com
Signed-off-by: Jim Cromie <jim.cromie at gmail.com>
---
 include/linux/dynamic_debug.h | 52 +++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 21 deletions(-)

diff --git a/include/linux/dynamic_debug.h b/include/linux/dynamic_debug.h
index c958085e0df4..d75a5d3ae388 100644
--- a/include/linux/dynamic_debug.h
+++ b/include/linux/dynamic_debug.h
@@ -80,15 +80,22 @@ struct ddebug_class_map {
 	enum ddebug_class_map_type map_type;
 };
 
+/*
+ * modules using dyndbg-classmaps must invoke either
+ */
 /**
- * DYNDBG_CLASSMAP_DEFINE - define a set of debug-classes used by a module.
+ * DYNDBG_CLASSMAP_DEFINE - define debug classes used by a module.
  * @_var:   name of the classmap, exported for other modules coordinated use.
- * @_type:  enum ddebug_class_map_type, chooses bits/verbose, numeric/names.
- * @_base:  offset of 1st class-name, used to share 0..62 classid space
- * @classes: vals are stringified enum-vals, like DRM_UT_*
+ * @_type:  enum ddebug_class_map_type: DISJOINT - independent, LEVEL - v2>v1
+ * @_base:  reserve N classids starting at _base, to split 0..62 classid space
+ * @classes: names of the N classes.
  *
- * Defines and exports a struct ddebug_class_map whose @classes are
- * used to validate a "class FOO .." >control command on the module
+ * This tells dyndbg what classids the module is using, by mapping
+ * names onto them.  This qualifies "class NAME" >controls on the
+ * defining module, ignoring unknown names.
+ *
+ * The @classes also name the bits 0.. in any CLASSMAP_PARAM referring
+ * to the classmap.
  */
 #define __DYNDBG_CLASSMAP_DEFINE(_var, _maptype, _base, ...)		\
 	static const char *_var##_classnames[] = { __VA_ARGS__ };	\
@@ -131,9 +138,9 @@ struct ddebug_class_user {
  * DYNDBG_CLASSMAP_USE - refer to a classmap, DEFINEd elsewhere.
  * @_var: name of the exported classmap var
  *
- * This registers a module's use of another module's classmap defn, so
- * dyndbg can authorize "class DRM_CORE ..." >control commands upon
- * this module.
+ * This tells dyndbg that the module has prdbgs with classids defined
+ * in the named classmap.  This qualifies "class NAME" >controls on
+ * the user module, ignoring unknown names.
  */
 #define DYNDBG_CLASSMAP_USE(_var)					\
 	DYNDBG_CLASSMAP_USE_(_var, __UNIQUE_ID(ddebug_class_user))
@@ -165,27 +172,30 @@ struct ddebug_class_param {
 };
 
 /**
- * DYNDBG_CLASSMAP_PARAM - wrap a dyndbg-classmap with a controlling sys-param
- * @_name  sysfs node name
- * @_var   name of the struct classmap var defining the controlled classes
- * @_flags flags to be toggled, typically just 'p'
+ * DYNDBG_CLASSMAP_PARAM - control a ddebug-classmap from a sys-param
+ * @_name:  sysfs node name
+ * @_var:   name of the classmap var defining the controlled classes/bits
+ * @_flags: flags to be toggled, typically just 'p'
  *
  * Creates a sysfs-param to control the classes defined by the
- * classmap.  Keeps bits in a private/static
+ * exported classmap, with bits 0..N-1 mapped to the classes named.
+ * This version keeps class-state in a private long int.
  */
 #define DYNDBG_CLASSMAP_PARAM(_name, _var, _flags)			\
 	static unsigned long _name##_bvec;				\
 	__DYNDBG_CLASSMAP_PARAM(_name, _name##_bvec, _var, _flags)
 
 /**
- * DYNDBG_CLASSMAP_PARAM_REF - wrap a dyndbg-classmap with a controlling sys-param
- * @_name  sysfs node name
- * @_bits  name of the module's unsigned long bit-vector, ex: __drm_debug
- * @_var   name of the struct classmap var defining the controlled classes
- * @_flags flags to be toggled, typically just 'p'
+ * DYNDBG_CLASSMAP_PARAM_REF - wrap a classmap with a controlling sys-param
+ * @_name:  sysfs node name
+ * @_bits:  name of the module's unsigned long bit-vector, ex: __drm_debug
+ * @_var:   name of the (exported) classmap var defining the classes/bits
+ * @_flags: flags to be toggled, typically just 'p'
  *
- * Creates a sysfs-param to control the classmap, keeping bitvec in user @_bits.
- * This lets drm use __drm_debug elsewhere too.
+ * Creates a sysfs-param to control the classes defined by the
+ * exported clasmap, with bits 0..N-1 mapped to the classes named.
+ * This version keeps class-state in user @_bits.  This lets drm check
+ * __drm_debug elsewhere too.
  */
 #define DYNDBG_CLASSMAP_PARAM_REF(_name, _bits, _var, _flags)		\
 	__DYNDBG_CLASSMAP_PARAM(_name, _bits, _var, _flags)
-- 
2.45.2