Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <76995421-a529-ac25-c306-2e4ac2844602@infradead.org>
Date:   Thu, 13 Jul 2023 12:13:45 -0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.12.0
Subject: Re: [PATCH v4 21/21] dyndbg-doc: add classmap info to howto
Content-Language: en-US
To:     Jim Cromie <jim.cromie@gmail.com>, jbaron@akamai.com,
        daniel.vetter@ffwll.ch, linux-kernel@vger.kernel.org,
        dri-devel@lists.freedesktop.org, amd-gfx@lists.freedesktop.org,
        intel-gvt-dev@lists.freedesktop.org,
        intel-gfx@lists.freedesktop.org
Cc:     jani.nikula@intel.com, ville.syrjala@linux.intel.com,
        seanpaul@chromium.org, robdclark@gmail.com,
        gregkh@linuxfoundation.org
References: <20230713163626.31338-1-jim.cromie@gmail.com>
 <20230713163626.31338-22-jim.cromie@gmail.com>
From:   Randy Dunlap <rdunlap@infradead.org>
In-Reply-To: <20230713163626.31338-22-jim.cromie@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk


On 7/13/23 09:36, Jim Cromie wrote:
> Add some basic info on classmap usage and api
> 
> Signed-off-by: Jim Cromie <jim.cromie@gmail.com>
> ---
>  .../admin-guide/dynamic-debug-howto.rst       | 64 ++++++++++++++++++-
>  1 file changed, 63 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
> index 8dc668cc1216..878750ce8c1d 100644
> --- a/Documentation/admin-guide/dynamic-debug-howto.rst
> +++ b/Documentation/admin-guide/dynamic-debug-howto.rst

> @@ -374,3 +373,66 @@ 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
> +=======================
> +
> +Dyndbg generally selects *prdbg* callsites using structural info:
> +module, file, function, line.  Using classmaps, user modules can
> +organize/select pr_debug()s as they like.
> +
> +- classes coordinates/spans multiple modules
> +- complements the mod,file,func attrs
> +- keeps pr_debug's 0-off-cost JUMP_LABEL goodness
> +- isolates from other class'd and un-class'd pr_debugs() 
> +  (one doesnt mix 2 clients bank accounts)

          doesn't

> +
> +  # IOW this doesn't change DRM.debug settings
> +  #> echo -p > /proc/dynamic_debug/control
> +
> +  # change the classes by naming them explicitly (no wildcard here)
> +  #> echo class DRM_UT_CORE +p > /proc/dynamic_debug/control
> +
> +To support DRM.debug (/sys/module/drm/parameters/debug), dyndbg
> +provides DYNDBG_CLASSMAP_PARAM*.  It maps the categories/classes:
> +DRM_UT_CORE.. to bits 0..N, allowing to set all classes at once.
> +
> +Dynamic Debug Classmap API
> +==========================
> +
> +DYNDBG_CLASSMAP_DEFINE - modules create CLASSMAPs, naming the classes
> +and type, and mapping the class-names to consecutive _class_ids.  By
> +doing so, they tell dyndbg that they are using those class_ids, and
> +authorize dyndbg to manipulate the callsites by their class-names.
> +
> +Its expected that client modules will follow the DRM.debug model:
> +1. define their debug-classes using an enum type, where the enum
> +symbol and its integer value define both the classnames and class-ids.
> +2. use or macro-wrap __pr_debug_cls(ENUM_VAL, "hello world\n")
> +   
> +There are 2 types of classmaps:
> +
> + DD_CLASS_TYPE_DISJOINT_BITS: classes are independent, ala DRM.debug

                                                          a la
or just                                                   like

> + DD_CLASS_TYPE_LEVEL_NUM: classes are relative (Verbose3 > Verbose2)
> +
> +Both these classmap-types use the class-names/ENUM_VALs to validate
> +commands into >control.
> +
> +DYNDBG_CLASSMAP_PARAM - refs a DEFINEd classmap, exposing the set of

Is this:                   refers to a
?

> +defined classes to manipulation as a group.  This interface enforces
> +the relatedness of classes of DD_CLASS_TYPE_LEVEL_NUM typed classmaps;
> +all classes are independent in the >control parser itself.
> +
> +DYNDBG_CLASSMAP_USE - drm drivers use the CLASSMAP that drm DEFINEs.
> +This shares the classmap defn, and authorizes coordinated changes

                            definition,

> +amongst the CLASSMAP DEFINEr and multiple USErs.
> +
> +Modules or module-groups (drm & drivers) can define multiple
> +classmaps, as long as they share the limited 0..62 per-module-group
> +_class_id range, without overlap.
> +
> +``#define DEBUG`` will enable all pr_debugs in scope, including any
> +class'd ones (__pr_debug_cls(id,fmt..)).  This won't be reflected in
> +the PARAM readback value, but the pr_debug callsites can be toggled
> +into agreement with the param.
> +

thanks.
-- 
~Randy