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@xxxxxxxxxxxxxxx
Signed-off-by: Jim Cromie <jim.cromie@xxxxxxxxx>
---
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
