Re: [PATCH v8 38/43] docs/dyndbg: add classmap info to howto

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Low] The commit message explicitly lists `DYNAMIC_DEBUG_CLASSMAP_PARAM_REF` as one of the API macros being described, but its description is completely missing from the updated documentation.
- [Low] A grammatical error was introduced when rewording the 'class' keyword description: 'If the class_name accepted by a module' is missing the word 'is'.
--

commit 7c3648089dc5012711c87c21ef5abd2076484f7b
Author: Jim Cromie <jim.cromie@gmail.com>

docs/dyndbg: add classmap info to howto

Describe the 3 API macros providing dynamic_debug's classmaps

DYNAMIC_DEBUG_CLASSMAP_DEFINE - create & export a classmap
DYNAMIC_DEBUG_CLASSMAP_USE    - refer to exported map
DYNAMIC_DEBUG_CLASSMAP_PARAM  - bind control param to the classmap
DYNAMIC_DEBUG_CLASSMAP_PARAM_REF + use module's storage - __drm_debug

NB: The _DEFINE & _USE model makes the user dependent on the definer,
just like EXPORT_SYMBOL(__drm_debug) already does.

> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
> index 6b934fab695b1..aa3a74deb68f9 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst
[ ... ]
> @@ -221,6 +214,25 @@ 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

[Severity: Low]
Does this sentence have a missing word? It seems like it should read "If the 
class_name is accepted by a module".

> +    proceeds.  Examples::
> +
> +	class DRM_UT_KMS	# a drm.debug category
[ ... ]
> @@ -398,3 +415,108 @@ just a shortcut for ``print_hex_dump(KERN_DEBUG)``.
[ ... ]
> +Dynamic Debug Classmap API
> +==========================
> +
> +DYNAMIC_DEBUG_CLASSMAP_DEFINE(clname,type,_base,classnames) - this maps
> +classnames (a list of strings) onto class-ids consecutively, starting
> +at _base.
> +
> +DYNAMIC_DEBUG_CLASSMAP_USE(clname) & _USE_(clname,_base) - modules
> +call this to refer to the var _DEFINEd elsewhere (and exported).
> +
> +DYNAMIC_DEBUG_CLASSMAP_PARAM(clname) - creates the sysfs/kparam,
> +maps/exposes bits 0..N as class-names.

[Severity: Low]
The commit message lists DYNAMIC_DEBUG_CLASSMAP_PARAM_REF as one of the API 
macros being described, but its description appears to be missing from this 
section.

Should an explanation for DYNAMIC_DEBUG_CLASSMAP_PARAM_REF be included here 
alongside the others?

> +
> +Classmaps are opt-in: modules invoke _DEFINE or _USE to authorize

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260905-dd-cmap-part2-clean-v8-0-a4cc0674f6fd@gmail.com?part=38