From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from shelob.surriel.com (shelob.surriel.com [96.67.55.147]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 5EA28C3DA60 for ; Thu, 18 Jul 2024 01:36:51 +0000 (UTC) Received: from localhost ([::1] helo=shelob.surriel.com) by shelob.surriel.com with esmtp (Exim 4.97.1) (envelope-from ) id 1sTnhc-000000007xV-3tR5; Tue, 16 Jul 2024 15:19:08 -0400 Received: from mail-io1-xd32.google.com ([2607:f8b0:4864:20::d32]) by shelob.surriel.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.97.1) (envelope-from ) id 1sTnOz-000000001Ka-1OUq for kernelnewbies@kernelnewbies.org; Tue, 16 Jul 2024 14:59:53 -0400 Received: by mail-io1-xd32.google.com with SMTP id ca18e2360f4ac-8036ce660e5so6279639f.1 for ; Tue, 16 Jul 2024 11:59:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1721156373; x=1721761173; darn=kernelnewbies.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=wgAqMd3+iIWmYMpud2tAag7fU0ZRfIKBjcu44k/UC/A=; b=T3rnU4P1Tj9h1cdg1jLTBTdEuw3ZbgNaL8BXM9PdqfRK+R2upFzJPTIEK/IHiZpAcM qYy7fTQla0ley2KlAosY6u5nxHBj+sO+3cF3kWdeUzNQ2M4GRcQz2SUVKPwvOHDqZ9u8 dcnqG/LzJ/J7DvJ7hpT7r3L53biYaLIofd56YE3LumeutOudO3qxhjROr2TMhAmNB9u6 9UGXizNBG1+IqE78PtIEwOQk8Tp3T1h83sLc8LvzZ5hktDEK5qUNyuWIU/F4aLgVpBOE dZhkWWf3AyCfyDjquKIQqPJPLmL8I5JOIMh8LHid8XUwutm8Pim0tnYvIAmf/ihbORk6 DN2Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1721156373; x=1721761173; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=wgAqMd3+iIWmYMpud2tAag7fU0ZRfIKBjcu44k/UC/A=; b=oOEb6bv3VmfBGSkJfRBvdw1wF7pxVPxuWIWnyTrKYd2cCh5rmY7yD+9luu9PuWTsMc nUd9jeiMMZRgw4sHIHEmKvnplpLug1+czBWgw55g8Y/cO5zZ9WeFnVPUCXIASV//nQFN 9yvDEES4HowC9UhH+OsTRcCMXTt8nwLpPgY1CJ8bLoxAuVC5GsvZlQC6nmyrZjx90TEw LH1P1lmVSq1+D0STzOvhvWM/9AalOFDhPVtE+xH4b3PAhKwDjsE1MkxqIGHEJILhqpUX y5jWOnPxvHnHbUMI9qY3XO5xkeQIjd5Bp6J24azMWFUsUna00MFauaviYVYWPblf4RSe TQaA== X-Forwarded-Encrypted: i=1; AJvYcCVXcRiiw28b4woFqaE3GlecMHrkahkoQHl9wu/IlZ7jvK9pgApQ+mEoU4gdvGv0y1HCB113eudJqtPgFE5LdYkNGBgobSbp67aZg6/LjmLZ X-Gm-Message-State: AOJu0Yx3J+8tPUFQ0ioAO4jOaxrZSfmoJp4KWezSyDIHLcZM5kP6f8MO rIin7ZDuPcpEW9OImIYlYSMyMkYn0iBBH+NlOFsdC92RwvMqQEmh X-Google-Smtp-Source: AGHT+IFni6bIdZqwUH+Scyf8+nuvN3S+CKoCazA0MHSZb6wujlaADABqWvB5L9YjT5+rHUGh02BCbQ== X-Received: by 2002:a05:6602:2dd2:b0:7f9:c953:c754 with SMTP id ca18e2360f4ac-816c45417e8mr42533539f.3.1721156372732; Tue, 16 Jul 2024 11:59:32 -0700 (PDT) Received: from frodo.. (c-73-78-62-130.hsd1.co.comcast.net. [73.78.62.130]) by smtp.googlemail.com with ESMTPSA id 8926c6da1cb9f-4c210f23f1csm75301173.102.2024.07.16.11.59.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 16 Jul 2024 11:59:32 -0700 (PDT) From: Jim Cromie To: linux-kernel@vger.kernel.org, jbaron@akamai.com, gregkh@linuxfoundation.org, daniel.vetter@ffwll.ch, tvrtko.ursulin@linux.intel.com, jani.nikula@intel.com, ville.syrjala@linux.intel.com Subject: [PATCH v9-resend 53/54] dyndbg: tighten up kdoc about DYNDBG_CLASSMAP_* macros Date: Tue, 16 Jul 2024 12:58:05 -0600 Message-ID: <20240716185806.1572048-54-jim.cromie@gmail.com> X-Mailer: git-send-email 2.45.2 In-Reply-To: <20240716185806.1572048-1-jim.cromie@gmail.com> References: <20240716185806.1572048-1-jim.cromie@gmail.com> MIME-Version: 1.0 Cc: groeck@google.com, linux-doc@vger.kernel.org, Jim Cromie , yanivt@google.com, intel-gfx@lists.freedesktop.org, kernelnewbies@kernelnewbies.org, linux@rasmusvillemoes.dk, robdclark@gmail.com, dri-devel@lists.freedesktop.org, mcgrof@kernel.org, seanpaul@chromium.org, amd-gfx@lists.freedesktop.org, joe@perches.com, bleung@google.com, intel-gvt-dev@lists.freedesktop.org, ukaszb@chromium.org X-BeenThere: kernelnewbies@kernelnewbies.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Learn about the Linux kernel List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: kernelnewbies-bounces@kernelnewbies.org 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@linux.intel.com Signed-off-by: Jim Cromie --- 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 _______________________________________________ Kernelnewbies mailing list Kernelnewbies@kernelnewbies.org https://lists.kernelnewbies.org/mailman/listinfo/kernelnewbies