docs/dyndbg: explain flags parse 1st
Subsystems (5)
A message that is not in the archive (sent off-list or not yet received): [email protected]
Jim Cromie
maintainerPATCH v4 2/56 docs/dyndbg: explain flags parse 1st
When writing queries to >control, flags are parsed 1st, since they are the only required field, and they require specific compositions. So if the flags draw an error (on those specifics), then keyword errors aren't reported. This can be mildly confusing/annoying, so explain it instead.
--- Documentation/admin-guide/dynamic-debug-howto.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-)
Documentation/admin-guide/dynamic-debug-howto.rst +12 -3
@@ -109,9 +109,18 @@ The match-spec's select *prdbgs* from the catalog, upon which to apply the flags-spec, all constraints are ANDed together. An absent keyword is the same as keyword "*". - -A match specification is a keyword, which selects the attribute of -the callsite to be compared, and a value to compare against. Possible +Note: because the match-spec can be empty, the flags are checked 1st, +then the pairs of keyword values. Flag errs will hide keyword errs: + + bash-5.2# ddcmd mod bar +foo + dyndbg: read 13 bytes from userspace + dyndbg: query 0: "mod bar +foo" mod:* + dyndbg: unknown flag 'o' + dyndbg: flags parse failed + dyndbg: processed 1 queries, with 0 matches, 1 errs + +So a match-spec is a keyword, which selects the attribute of the +callsite to be compared, and a value to compare against. Possible keywords are::: match-spec ::= 'func' string |
Signature · 1 line
2.50.1
Jim Cromie
maintainerPATCH v4 19/56 dyndbg-API: replace DECLARE_DYNDBG_CLASSMAP
In reply to a message not in the archiveDECLARE_DYNDBG_CLASSMAP() has a design error; its usage fails a basic K&R rule: "define once, refer many times".
When DRM_USE_DYNAMIC_DEBUG=y, it is used across DRM core & drivers; each invocation allocates/inits the classmap understood by that module. All must match for the modules to respond together when DRM.debug categories are enabled. This is brittle; a maintenance foot-gun.
Further, its culpable in the CONFIG_DRM_USE_DYNAMIC_DEBUG=Y regression; its use in both core & drivers obfuscates the 2 roles, resulting in incomplete initialization when modprobing drivers:
1st drm.ko loads, and dyndbg initializes its DRM.debug callsites, then a drm-driver loads, but too late for the DRM.debug enablement.
So retire it, replace with 2 macros:
DYNAMIC_DEBUG_CLASSMAP_DEFINE - invoked once from core - drm.ko
DYNAMIC_DEBUG_CLASSMAP_USE - from all drm drivers and helpers.
DYNAMIC_DEBUG_CLASSMAP_DEFINE: this reworks DECLARE_DYNDBG_CLASSMAP, by dropping the static qualifier on the classmap, and exporting it instead.
DYNAMIC_DEBUG_CLASSMAP_USE: then refers to the exported var by name:
used from drivers, helper-mods
lets us drop the repetitive "classname" declarations
fixes 2nd-defn problem
creates a ddebug_class_user record in new __dyndbg_class_users section new section is scanned "differently"
DECLARE_DYNDBG_CLASSMAP is preserved temporarily, to decouple DRM adaptation work and avoid compile-errs before its done. IOW, DRM gets these fixes when they commit the adopt-new-api patches.
The DEFINE,USE distinction, and the separate classmap-use record, allows dyndbg to initialize the driver's & helper's DRM.debug callsites separately after each is modprobed.
Basically, the classmap init-scan is repeated for classmap-users.
To review, dyndbg's existing __dyndbg_classes[] section does:
. catalogs the module's classmaps
. tells dyndbg about them, allowing >control
. DYNAMIC_DEBUG_CLASSMAP_DEFINE creates section records. . we rename it to: __dyndbg_class_maps[]
Then this patch adds __dyndbg_class_users[] section:
. catalogs users of classmap definitions from elsewhere . authorizes dyndbg to >control user's class'd prdbgs . DYNAMIC_DEBUG_CLASSMAP_USE() creates section records.
Now ddebug_add_module(etal) can handle classmap-uses similar to (and after) classmaps; when a dependent module is loaded, if it has classmap-uses (to a classmap-def in another module), that module's kernel params are scanned to find if it has a kparam that is wired to dyndbg's param-ops, and whose classmap is the one being ref'd.
To support this, theres a few data/header changes:
new struct ddebug_class_user
contains: user-module-name, &classmap-defn
it records drm-driver's use of a classmap in the section, allowing lookup
struct ddebug_info gets 2 new fields for the new sections:
class_users, num_class_users.
set by dynamic_debug_init() for builtins.
or by kernel/module/main:load_info() for loadable modules.
vmlinux.lds.h: new BOUNDED_SECTION for __dyndbg_class_users. this creates start,len C symbol-names for the section.
dynamic_debug.c has 2 changes in ddebug_add_module(), ddebug_change():
ddebug_add_module()
called ddebug_attach_module_classes()
now calls ddebug_apply_class_maps() & ddebug_apply_class_users()
these both call ddebug_apply_params().
ddebug_apply_params(new fn):
It scans module's/builtin kernel-params, calls ddebug_match_apply_kparam for each to find any params/sysfs-nodes which may be wired to a classmap.
ddebug_match_apply_kparam(new fn):
1st, it tests the kernel-param.ops is dyndbg's; this guarantees that the attached arg is a struct ddebug_class_param, which has a ref to the param's state, and to the classmap defining the param's handling.
2nd, it requires that the classmap ref'd by the kparam is the one we've been called for; modules can use many separate classmaps (as test_dynamic_debug does).
Then apply the "parent" kparam's setting to the dependent module, using ddebug_apply_class_bitmap().
ddebug_change(and callees) also gets adjustments:
ddebug_find_valid_class(): This does a search over the module's classmaps, looking for the class FOO echo'd to >control. So now it searches over __dyndbg_class_users[] after __dyndbg_classes[].
ddebug_class_name(): return class-names for defined OR used classes.
test_dynamic_debug.c, test_dynamic_debug_submod.c:
This demonstrates the 2 types of classmaps & sysfs-params, following the 4-part recipe:
0. define an enum for the classmap:
DRM.debug provides DRM_UT_<*> (aka <T>)
multiple classmaps in a module(s) must share 0-62 classid space.
1. DYNAMIC_DEBUG_CLASSMAP_DEFINE(classmap_name, .. "<T>") drm.ko does this
2. DYNAMIC_DEBUG_CLASSMAP_PARAM* (classmap_name)
if module wants a sysfs PARAM
3. DYNAMIC_DEBUG_CLASSMAP_USE(classmap_name)
for subsystem/group/drivers use
Move all the enum declarations together, to better explain how they share the 0..62 class-id space available to a module (non-overlapping subranges).
reorg macros 2,3 by name. This gives a tabular format, making it easy to see the pattern of repetition, and the points of change.
And extend the test to replicate the 2-module (parent & dependent) scenario which caused the CONFIG_DRM_USE_DYNAMIC_DEBUG=y regression seen in drm & drivers.
The _submod.c is a 2-line file: #define _SUBMOD, #include parent.
This gives identical complements of prdbgs in parent & _submod, and thus identical print behavior when all of: >control, >params, and parent->_submod propagation are working correctly.
It also puts all the parent/_submod declarations together in the same source, with the new ifdef _SUBMOD block invoking DYNAMIC_DEBUG_CLASSMAP_USE for the 2 test-interfaces. I think this is clearer.
These 2 modules are both tristate, allowing 3 super/sub combos: Y/Y, Y/M, M/M (not N/Y, since this is disallowed by dependence).
Y/Y testing exposed a missing __align(8) in the _METADATA macro, which M/M didn't see because the module-loader memory placement constrains it instead.
---
v3-
undo 1.9 simplification of ddebug_find_valid_class() ddebug_change needs map to see its controlling param change internal callchains to pass di, not dt
v2 a. building 2 .ko's from 1 source file is weird; add a clear
comment at the top to justify it (basically cloning) ln 138+ in commit-msg is insufficient.
b. retire "DYNDBG_" name shortening b4 adding _CLASSMAP_* macros. c. s/dd_class/_ddebug_class/
d. s/\bddebug\b/_$1/g in header: chgs 1 struct and UNIQUE_ID bases
v1.9 - commit-msg tweaks
DRM:CHECK warnings on macros: add parens
extern DEFINEd _var, static classnames
change ddebug_class_user.user_mod_name to .mod_name simplify ddebug_find_valid_class return val
improve vpr_cm_info msg format
wrap (base) in macro body
move __DYNDBG_CLASSMAP_CHECK above kdoc for DYNDBG_CLASSMAP_DEFINE
v1.8 - split drm parts to separate commits.
preserve DECLARE_DYNDBG_CLASSMAP to decouple DRM, no flag day. fixup block comment
v1.7 - previous submission-blocking bug:
missing __align(8) in DYNAMIC_DEBUG_DECLARE_METADATA on ddebug_class_user caused corrupt records, but only for builtin modules; module loader code probably pinned allocations to the right alignment naturally, hiding the bug for typical builds.
v6- get rid of WARN_ON_ONCE
v?- fix _var expanded 2x in macro
dyndbg:
This fn formerly returned the map which contained the class (thus validating it), and as a side-effect set the class-id in an outvar.
But the caller didn't use the map (after checking its not null), only the valid class-id. So simplify the fn to return the class-id of the validated classname, or -ENOENT when the queried classname is not found.
Convey more useful info in the debug-msg: print class-names[0,last], and [base,+len] instead of the class-type printout, which is almost always "type:DISJOINT_BITS". And drop ddebug_classmap_typenames, which is now unused.
[root@v6 b0-dd]# modprobe test_dynamic_debug_submod
[ 18.864962] dyndbg: loaded classmap: test_dynamic_debug [16..24] V0..V7 [ 18.865046] dyndbg: found kp:p_level_num =0x0 [ 18.865048] dyndbg: mapped to: test_dynamic_debug [16..24] V0..V7 [ 18.865164] dyndbg: p_level_num: lvl:0 bits:0x0 [ 18.865217] dyndbg: loaded classmap: test_dynamic_debug [0..10] D2_CORE..D2_DRMRES [ 18.865297] dyndbg: found kp:p_disjoint_bits =0x0 [ 18.865298] dyndbg: mapped to: test_dynamic_debug [0..10] D2_CORE..D2_DRMRES [ 18.865424] dyndbg: p_disjoint_bits: classbits: 0x0 [ 18.865472] dyndbg: module:test_dynamic_debug attached 2 classmaps [ 18.865533] dyndbg: 23 debug prints in module test_dynamic_debug [ 18.866558] dyndbg: loaded classmap: test_dynamic_debug_submod [16..24] V0..V7 [ 18.866698] dyndbg: found kp:p_level_num =0x0 [ 18.866699] dyndbg: mapped to: test_dynamic_debug_submod [16..24] V0..V7 [ 18.866865] dyndbg: p_level_num: lvl:0 bits:0x0 [ 18.866926] dyndbg: loaded classmap: test_dynamic_debug_submod [0..10] D2_CORE..D2_DRMRES [ 18.867026] dyndbg: found kp:p_disjoint_bits =0x0 [ 18.867027] dyndbg: mapped to: test_dynamic_debug_submod [0..10] D2_CORE..D2_DRMRES [ 18.867193] dyndbg: p_disjoint_bits: classbits: 0x0 [ 18.867255] dyndbg: module:test_dynamic_debug_submod attached 2 classmap uses [ 18.867351] dyndbg: 23 debug prints in module test_dynamic_debug_submod
fixup-test-submod
fixup-test
fixup-h-decl
tweak-hdr-cmts-cls
--- MAINTAINERS | 2 +- include/asm-generic/vmlinux.lds.h | 1 + include/linux/dynamic_debug.h | 118 ++++++++++++++++++++++--- kernel/module/main.c | 3 + lib/Kconfig.debug | 24 ++++-- lib/Makefile | 5 ++ lib/dynamic_debug.c | 137 +++++++++++++++++++++++++++--- lib/test_dynamic_debug.c | 132 ++++++++++++++++++++-------- lib/test_dynamic_debug_submod.c | 14 +++ 9 files changed, 366 insertions(+), 70 deletions(-) create mode 100644 lib/test_dynamic_debug_submod.c
MAINTAINERS +1 -1
@@ -8454,7 +8454,7 @@ M: Jim Cromie <[email protected]> S: Maintained F: include/linux/dynamic_debug.h F: lib/dynamic_debug.c -F: lib/test_dynamic_debug.c +F: lib/test_dynamic_debug*.c F: tools/testing/selftests/dynamic_debug/* DYNAMIC INTERRUPT MODERATION
include/asm-generic/vmlinux.lds.h +1 -0
@@ -366,6 +366,7 @@ defined(CONFIG_AUTOFDO_CLANG) || defined(CONFIG_PROPELLER_CLANG)/* implement dynamic printk debug */ \ . = ALIGN(8); \ BOUNDED_SECTION_BY(__dyndbg_class_maps, ___dyndbg_class_maps) \ + BOUNDED_SECTION_BY(__dyndbg_class_users, ___dyndbg_class_users) \ BOUNDED_SECTION_BY(__dyndbg_descriptors, ___dyndbg_descs) \ CODETAG_SECTIONS() \LIKELY_PROFILE () \
include/linux/dynamic_debug.h +104 -14
164 lines not on this page · raw message
kernel/module/main.c +3 -0
@@ -2695,6 +2695,9 @@ static int find_module_sections(struct module *mod, struct load_info *info) mod->dyndbg_info.maps.start =section_objs (info,"__dyndbg_class_maps" ,sizeof (*mod->dyndbg_info.maps.start), &mod->dyndbg_info.maps.len); + mod->dyndbg_info.users.start =section_objs (info,"__dyndbg_class_users" , +sizeof (*mod->dyndbg_info.users.start), + &mod->dyndbg_info.users.len);#endif return 0 ;
lib/Kconfig.debug +19 -5
@@ -2970,12 +2970,26 @@ config TEST_STATIC_KEYS If unsure, say N. config TEST_DYNAMIC_DEBUG - tristate "Test DYNAMIC_DEBUG" - depends on DYNAMIC_DEBUG + tristate "Build test-dynamic-debug module" + depends on DYNAMIC_DEBUG || DYNAMIC_DEBUG_CORE help - This module registers a tracer callback to count enabled - pr_debugs in a 'do_debugging' function, then alters their - enablements, calls the function, and compares counts. + This module exercises/demonstrates dyndbg's classmap API, by + creating 2 classes: a DISJOINT classmap (supporting DRM.debug) + and a LEVELS/VERBOSE classmap (like verbose2 > verbose1). + + If unsure, say N. + +config TEST_DYNAMIC_DEBUG_SUBMOD + tristate "Build test-dynamic-debug submodule" + default m + depends on DYNAMIC_DEBUG || DYNAMIC_DEBUG_CORE + depends on TEST_DYNAMIC_DEBUG + help + This sub-module uses a classmap defined and exported by the + parent module, recapitulating drm & driver's shared use of + drm.debug to control enabled debug-categories. + It is tristate, independent of parent, to allow testing all + proper combinations of parent=y/m submod=y/m. If unsure, say N.
lib/Makefile +5 -0
@@ -81,6 +81,9 @@ obj-$(CONFIG_TEST_RHASHTABLE) += test_rhashtable.o obj-$(CONFIG_TEST_STATIC_KEYS) += test_static_keys.o obj-$(CONFIG_TEST_STATIC_KEYS) += test_static_key_base.o obj-$(CONFIG_TEST_DYNAMIC_DEBUG) += test_dynamic_debug.o +obj-$(CONFIG_TEST_DYNAMIC_DEBUG_SUBMOD) += test_dynamic_debug_submod.o +obj-$(CONFIG_TEST_PRINTF) += test_printf.o +obj-$(CONFIG_TEST_SCANF) += test_scanf.o obj-$(CONFIG_TEST_BITMAP) += test_bitmap.o ifeq ($(CONFIG_CC_IS_CLANG)$(CONFIG_KASAN),yy)
@@ -215,6 +218,8 @@ obj-$(CONFIG_ARCH_NEED_CMPXCHG_1_EMU) += cmpxchg-emu.o obj-$(CONFIG_DYNAMIC_DEBUG_CORE) += dynamic_debug.o #ensure exported functions have prototypes CFLAGS_dynamic_debug.o := -DDYNAMIC_DEBUG_MODULE +CFLAGS_test_dynamic_debug.o := -DDYNAMIC_DEBUG_MODULE +CFLAGS_test_dynamic_debug_submod.o := -DDYNAMIC_DEBUG_MODULE obj-$(CONFIG_SYMBOLIC_ERRNAME) += errname.o
lib/dynamic_debug.c +123 -14
239 lines not on this page · raw message
lib/test_dynamic_debug.c +96 -36
163 lines not on this page · raw message
lib/test_dynamic_debug_submod.c new file +14 -0
@@ -0,0 +1,14 @@ +// SPDX-License-Identifier: GPL-2.0 +/* +* Kernel module for testing dynamic_debug +* +* Authors: +* Jim Cromie <[email protected]> +*/ + +/* +* clone the parent, inherit all the properties, for consistency and +* simpler accounting in test expectations. +*/ +#define TEST_DYNAMIC_DEBUG_SUBMOD +#include "test_dynamic_debug.c"
Signature · 1 line
2.50.1
Jim Cromie
maintainerPATCH v4 23/56 dyndbg-API: promote DYNAMIC_DEBUG_CLASSMAP_PARAM to API
In reply to a message not in the archivemove the DYNAMIC_DEBUG_CLASSMAP_PARAM macro from test-dynamic-debug.c into the header, and refine it, by distinguishing the 2 use cases:
1.DYNAMIC_DEBUG_CLASSMAP_PARAM_REF
for DRM, to pass in extern __drm_debug by name. dyndbg keeps bits in it, so drm can still use it as before
2.DYNAMIC_DEBUG_CLASSMAP_PARAM
new user (test_dynamic_debug) doesn't need to share state, decls a static long unsigned int to store the bitvec.
__DYNAMIC_DEBUG_CLASSMAP_PARAM
bottom layer - allocate,init a ddebug-class-param, module-param-cb.
Modify ddebug_sync_classbits() argtype deref inside the fn, to give access to all kp members.
Also clean up and improve comments in test-code, and add MODULE_DESCRIPTIONs.
---
-v9
- fixup drm-print.h add PARAM_REF forwarding macros
with DYNAMIC_DEBUG_CLASSMAP_PARAM_REF in the API, add DRM_ variant
--- include/linux/dynamic_debug.h | 38 +++++++++++++++++++++ lib/dynamic_debug.c | 60 ++++++++++++++++++++++----------- lib/test_dynamic_debug.c | 47 ++++++++++---------------- lib/test_dynamic_debug_submod.c | 9 ++++- 4 files changed, 104 insertions(+), 50 deletions(-)
include/linux/dynamic_debug.h +38 -0
@@ -223,6 +223,44 @@ struct _ddebug_class_param {const struct _ddebug_class_map *map; }; +/** +* DYNAMIC_DEBUG_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 +* exported classmap, with bits 0..N-1 mapped to the classes named. +* This version keeps class-state in a private long int. +*/ +#define DYNAMIC_DEBUG_CLASSMAP_PARAM (_name, _var, _flags) \ + static unsigned long _name##_bvec; \ + __DYNAMIC_DEBUG_CLASSMAP_PARAM(_name, _name##_bvec, _var, _flags) + +/** +* DYNAMIC_DEBUG_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 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 DYNAMIC_DEBUG_CLASSMAP_PARAM_REF (_name, _bits, _var, _flags) \ + __DYNAMIC_DEBUG_CLASSMAP_PARAM(_name, _bits, _var, _flags) + +#define __DYNAMIC_DEBUG_CLASSMAP_PARAM (_name, _bits, _var, _flags) \ + static struct _ddebug_class_param _name##_##_flags = { \ + .bits = &(_bits), \ + .flags = #_flags, \ + .map = &(_var), \ + }; \ + module_param_cb(_name, ¶m_ops_dyndbg_classes, \ + &_name##_##_flags, 0600) +/* * pr_debug() and friends are globally enabled or modules have selectively * enabled them.
lib/dynamic_debug.c +41 -19
88 lines not on this page · raw message
lib/test_dynamic_debug.c +17 -30
88 lines not on this page · raw message
lib/test_dynamic_debug_submod.c +8 -1
@@ -1,6 +1,9 @@// SPDX-License-Identifier: GPL-2.0 /* -* Kernel module for testing dynamic_debug +* Kernel module to test/demonstrate dynamic_debug features, +* particularly classmaps and their support for subsystems, like DRM, +* which defines its drm_debug classmap in drm module, and uses it in +* helpers & drivers. * * Authors: * Jim Cromie <[email protected]>
@@ -12,3 +15,7 @@*/ #define TEST_DYNAMIC_DEBUG_SUBMOD #include "test_dynamic_debug.c" + +MODULE_DESCRIPTION ("test/demonstrate dynamic-debug subsystem support" ); +MODULE_AUTHOR ("Jim Cromie <[email protected]>" ); +MODULE_LICENSE ("GPL" );
Signature · 1 line
2.50.1
Jim Cromie
maintainerPATCH v4 29/56 docs/dyndbg: add classmap info to howto
In reply to a message not in the archiveDescribe the 3 API macros providing dynamic_debug's classmaps
DYNDBG_CLASSMAP_DEFINE - create & export a classmapDYNDBG_CLASSMAP_USE - refer to exported mapDYNDBG_CLASSMAP_PARAM - bind control param to the classmap DYNDBG_CLASSMAP_PARAM_REF + use module's storage - __drm_debug
TBD: some of this might be over-specification, or just over-talked.
NB: The _DEFINE & _USE model makes the user dependent on the definer, just like EXPORT_SYMBOL(__drm_debug) already does.
---
v3- rework protection around PARAM
v0.5 adjustments per Randy Dunlap
v0.7 checkpatch fixes
v0.8 more
v0.9 rewords
fixup-howto
--- .../admin-guide/dynamic-debug-howto.rst | 137 ++++++++++++++++-- 1 file changed, 126 insertions(+), 11 deletions(-)
Documentation/admin-guide/dynamic-debug-howto.rst +126 -11
@@ -146,7 +146,9 @@ keywords are::: "1-30" is valid range but "1 - 30" is not. -The meanings of each keyword are: +Keywords::: + +The meanings of each keyword are:: func The given string is compared against the function name
@@ -194,16 +196,6 @@ format format "nfsd: SETATTR" // a neater way to match a format with whitespace format 'nfsd: SETATTR' // yet another way to match a format with whitespace -class - The given class_name is validated against each module, which may - have declared a list of known class_names. If the class_name is - found for a module, callsite & class matching and adjustment - proceeds. Examples:: - - class DRM_UT_KMS # a DRM.debug category - class JUNK # silent non-match - // class TLD_* # NOTICE: no wildcard in class names - line The given line number or range of line numbers is compared against the line number of each ``pr_debug()`` callsite. A single
@@ -218,6 +210,24 @@ line line -1605 // the 1605 lines from line 1 to line 1605 line 1600- // all lines from line 1600 to the end of the file +class + + The given class_name is validated against each module, which may + have declared a list of class_names it accepts. If the class_name + accepted by a module, callsite & class matching and adjustment + proceeds. Examples:: + + class DRM_UT_KMS # a DRM.debug category + class JUNK # silent non-match + // class TLD_* # NOTICE: no wildcard in class names + +.. note :: + + Unlike other keywords, classes are "name-to-change", not + "omitting-constraint-allows-change". See Dynamic Debug Classmaps + +Flags::: + The flags specification comprises a change operation followed by one or more flag characters. The change operation is one of the characters::
@@ -394,3 +404,108 @@ 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 +======================= + +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: classes must be named to be +changed. This protects them from generic overwrite: + + # IOW this cannot undo any DRM.debug settings + :#> ddcmd -p + +This protection is needed; /sys/module/drm/parameters/debug is ABI. +DRM.debug is authoritative when dyndbg is not used, dyndbg's PARAM +cannot undermine that guarantee just because its optional for DRM to +use it. + + :#> echo 0x1ff > /sys/module/drm/parameters/debug + +So each class must be enabled individually (no wildcards): + + :#> ddcmd class DRM_UT_CORE +p + :#> ddcmd class DRM_UT_KMS +p + # or more selectively + :#> ddcmd class DRM_UT_CORE module drm +p + +That makes direct >control wordy and annoying, but it is a secondary +interface; it is not intended to replace the ABI, just slide in +underneath and reimplement it. + +However, since the sysfs/kparam is the ABI, if a classmap DEFINEr +doesn't also add a _CLASSMAP_PARAM, there is no ABI, and no protection +is needed. In that case, class'd prdbgs would be enabled/disabled by +legacy (class-less) queries, as a convenience, and because there's no +need to enforce irrelevant rules. + + +Dynamic Debug Classmap API +========================== + +DRM.debug is built upon: + +- enum drm_debug_category: DRM_UT_<*> - <T> for short +- 23 categorized api macros: drm_dbg_<T>(), DRM_DEBUG_<T>() +- 5000 calls to them +- all calling to __pr_debug_cls(<T>, ...) + +Those compile-time const short ints are good for optimizing compilers; +a primary classmaps design goal was to keep that property. +So basically .class_id === category. + +Then we use the drm_categories DRM_UT_* enum for both the classnames +(stringified enum symbols) and their numeric values. + +Its expected that future users will also use categorized macros and an +enum-defined categorization scheme like DRM's, with dyndbg inserted in +similarly. + +DYNAMIC_DEBUG_CLASSMAP_DEFINE(var,type,_base,classnames) - this maps +classnames (a list of strings) onto class-ids consecutively, starting +at _base, it also maps the names onto CLASSMAP_PARAM bits 0..N. + +DYNAMIC_DEBUG_CLASSMAP_USE(var) - modules call this to refer to the +var _DEFINEd elsewhere (and exported). + +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. + +NB: It is an inherent API limitation that the following are possible: + + // these would be caught in review + __pr_debug_cls(0, "fake DRM_UT_CORE msg"); // this works + __pr_debug_cls(62, "un-known classid msg"); // this compiles, does nothing + +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) + +DYNAMIC_DEBUG_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. + +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; there is no implied meaning in names like "V4". + +Modules or module-groups (drm & drivers) can define multiple +classmaps, as long as they (all the classmaps) share the limited 0..62 +per-module-group _class_id range, without overlap. + +If a module encounters a conflict between 2 classmaps its USEing, we +can extend the _USE macro with an offset to allow de-conflicting the +respective ranges. Or they use the DEFINErs macro-api, but with new +enum symbols. + +``#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 class'd pr_debug callsites can be forced off by toggling the +classmap-kparam all-on then all-off.
Signature · 1 line
2.50.1