lkml.org 
[lkml]   [2024]   [Apr]   [29]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v8 20/35] dyndbg-doc: add classmap info to howto
    Date
    Describe the 3 API macros providing dynamic_debug's classmaps

    DYNDBG_CLASSMAP_DEFINE - create, exports a module's classmap
    DYNDBG_CLASSMAP_USE - refer to exported map
    DYNDBG_CLASSMAP_PARAM - bind control param to the classmap
    DYNDBG_CLASSMAP_PARAM_REF + use module's storage - __drm_debug

    cc: linux-doc@vger.kernel.org
    Signed-off-by: Jim Cromie <jim.cromie@gmail.com>
    ---
    v5 adjustments per Randy Dunlap
    v7 checkpatch fixes
    v8 more
    ---
    .../admin-guide/dynamic-debug-howto.rst | 63 ++++++++++++++++++-
    1 file changed, 62 insertions(+), 1 deletion(-)

    diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
    index 6a8ce5a34382..742eb4230c6e 100644
    --- a/Documentation/admin-guide/dynamic-debug-howto.rst
    +++ b/Documentation/admin-guide/dynamic-debug-howto.rst
    @@ -225,7 +225,6 @@ the ``p`` flag has meaning, other flags are ignored.
    Note the regexp ``^[-+=][fslmpt_]+$`` matches a flags specification.
    To clear all flags at once, use ``=_`` or ``-fslmpt``.

    -
    Debug messages during Boot Process
    ==================================

    @@ -375,3 +374,65 @@ 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 allows selection/grouping of *prdbg* callsites using structural
    +info: module, file, function, line. Classmaps allow authors to add
    +their own domain-oriented groupings using class-names. Classmaps are
    +exported, so they referencable from other modules.
    +
    + # enable classes individually
    + :#> ddcmd class DRM_UT_CORE +p
    + :#> ddcmd class DRM_UT_KMS +p
    + # or more selectively
    + :#> ddcmd class DRM_UT_CORE module drm +p
    +
    +The "class FOO" syntax protects class'd prdbgs from generic overwrite::
    +
    + # IOW this doesn't wipe any DRM.debug settings
    + :#> ddcmd -p
    +
    +To support the DRM.debug parameter, DYNDBG_CLASSMAP_PARAM* updates all
    +classes in a classmap, mapping param-bits 0..N onto the classes:
    +DRM_UT_<*> for the DRM use-case.
    +
    +Dynamic Debug Classmap API
    +==========================
    +
    +DYNDBG_CLASSMAP_DEFINE - modules use this to create classmaps, naming
    +each of the classes (stringified enum-symbols: "DRM_UT_<*>"), and
    +type, and mapping the class-names to consecutive _class_ids.
    +
    +By doing so, modules tell dyndbg that they have prdbgs with those
    +class_ids, and they authorize dyndbg to accept "class FOO" for the
    +module defining the classmap, and its contained classnames.
    +
    +DYNDBG_CLASSMAP_USE - drm drivers invoke this to ref the CLASSMAP that
    +drm DEFINEs. This shares the classmap definition, and authorizes
    +dyndbg to apply changes to the user module's class'd pr_debugs. It
    +also tells dyndbg how to initialize the user's prdbgs at modprobe,
    +based upon the current setting of the parent's controlling param.
    +
    +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)
    +
    +DYNDBG_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.
    +
    +This interface also enforces the DD_CLASS_TYPE_LEVEL_NUM relation
    +amongst the contained classnames; all classes are independent in the
    +control parser itself.
    +
    +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. 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.
    --
    2.44.0

    \
     
     \ /
      Last update: 2024-05-27 18:08    [W:3.351 / U:0.116 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site