| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <20240716185806.1572048-54-jim.cromie@gmail.com>
Date: Tue, 16 Jul 2024 12:58:05 -0600
From: Jim Cromie <jim.cromie@...il.com>
To: linux-kernel@...r.kernel.org,
jbaron@...mai.com,
gregkh@...uxfoundation.org,
daniel.vetter@...ll.ch,
tvrtko.ursulin@...ux.intel.com,
jani.nikula@...el.com,
ville.syrjala@...ux.intel.com
Cc: ukaszb@...omium.org,
linux@...musvillemoes.dk,
joe@...ches.com,
mcgrof@...nel.org,
seanpaul@...omium.org,
robdclark@...il.com,
groeck@...gle.com,
yanivt@...gle.com,
bleung@...gle.com,
linux-doc@...r.kernel.org,
dri-devel@...ts.freedesktop.org,
amd-gfx@...ts.freedesktop.org,
intel-gvt-dev@...ts.freedesktop.org,
intel-gfx@...ts.freedesktop.org,
kernelnewbies@...nelnewbies.org,
Jim Cromie <jim.cromie@...il.com>
Subject: [PATCH v9-resend 53/54] dyndbg: tighten up kdoc about DYNDBG_CLASSMAP_* macros
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@...ux.intel.com
Signed-off-by: Jim Cromie <jim.cromie@...il.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
Powered by blists - more mailing lists