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 gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (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 4170BC2BA18 for ; Sun, 23 Jun 2024 20:33:07 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id D55E210E1C6; Sun, 23 Jun 2024 20:33:06 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (2048-bit key; unprotected) header.d=intel.com header.i=@intel.com header.b="fFD0ejmg"; dkim-atps=neutral Received: from mgamail.intel.com (mgamail.intel.com [198.175.65.20]) by gabe.freedesktop.org (Postfix) with ESMTPS id 5234610E1C6 for ; Sun, 23 Jun 2024 20:33:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1719174784; x=1750710784; h=date:message-id:from:to:cc:subject:in-reply-to: references:mime-version; bh=VaK4EUeNaocPNwJzIBW5/tzKKD3coVjtX459LBNpl7w=; b=fFD0ejmgZPebPLLLAsS1ftfc6GvGF56sRZ0wA47pGVUrNqhe55ia+/TM DKWd10WC0nuYYrgmcH1sQsFCfaM/PvuvA6DyaytwAW/HwO5ys9jjbWt/b bxSxTFQ6QlS3ywMVyi/7GkwvSfxGVHnP83SvcWLFO4xSHypDejhZPB7P1 pbXJGfOvivI3KgL1q8F4lSbCDlAXChEAdhPsWsZaIGVFwMJgYigu0Yqfa dVV6TFxEQzC+VvZ9So+cTnw02u7t8FIYw8UgiFaMnyM4L89rCxiFiXL/L 3OonQiPeB6vFo/j5ii26FzINuJWxZVgnGITElt9f4y6rUab5/8wxvpVb+ g==; X-CSE-ConnectionGUID: uIXkRyIBRGGwT0uoLruxlw== X-CSE-MsgGUID: sM0Epl2uQ7yT0tEUTHl1+A== X-IronPort-AV: E=McAfee;i="6700,10204,11112"; a="15965482" X-IronPort-AV: E=Sophos;i="6.08,260,1712646000"; d="scan'208";a="15965482" Received: from orviesa002.jf.intel.com ([10.64.159.142]) by orvoesa112.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 23 Jun 2024 13:33:02 -0700 X-CSE-ConnectionGUID: nYkrFnRzTqGEJcbpOyoI2Q== X-CSE-MsgGUID: tVbhFEyTQmOP9GZkQ89e+w== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.08,260,1712646000"; d="scan'208";a="73851758" Received: from vishrutm-mobl11.amr.corp.intel.com (HELO adixit-arch.intel.com) ([10.125.97.201]) by orviesa002-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 23 Jun 2024 13:33:02 -0700 Date: Sun, 23 Jun 2024 13:14:53 -0700 Message-ID: <87bk3rfmbm.wl-ashutosh.dixit@intel.com> From: "Dixit, Ashutosh" To: Michal Wajdeczko Cc: Rodrigo Vivi , Subject: Re: [PATCH] drm/xe/oa: Fix 'enum drm_xe_perf_type' kernel doc warnings In-Reply-To: <8534p5q81z.wl-ashutosh.dixit@intel.com> References: <20240621190903.3593781-1-ashutosh.dixit@intel.com> <508be309-17c8-419a-92b4-91cd06d2cb6b@intel.com> <87wmmihtbw.wl-ashutosh.dixit@intel.com> <8534p5q81z.wl-ashutosh.dixit@intel.com> User-Agent: Wanderlust/2.15.9 (Almost Unreal) SEMI-EPG/1.14.7 (Harue) FLIM-LB/1.14.9 (=?ISO-8859-4?Q?Goj=F2?=) APEL-LB/10.8 EasyPG/1.0.0 Emacs/29.3 (x86_64-pc-linux-gnu) MULE/6.0 (HANACHIRUSATO) MIME-Version: 1.0 (generated by SEMI-EPG 1.14.7 - "Harue") Content-Type: text/plain; charset=US-ASCII X-BeenThere: intel-xe@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Intel Xe graphics driver List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-xe-bounces@lists.freedesktop.org Sender: "Intel-xe" On Sat, 22 Jun 2024 09:03:04 -0700, Dixit, Ashutosh wrote: > > On Sat, 22 Jun 2024 02:17:11 -0700, Michal Wajdeczko wrote: > > > > Hi Michal, > > > > > > > On 21.06.2024 23:36, Dixit, Ashutosh wrote: > > > On Fri, 21 Jun 2024 12:45:43 -0700, Michal Wajdeczko wrote: > > >> > > > > > > Hi Michal, > > > > > >> > > >> On 21.06.2024 21:09, Ashutosh Dixit wrote: > > >>> Include kernel doc's for 'enum drm_xe_perf_type' to fix kernel doc > > >>> warnings. > > >>> > > >>> Reported-by: Michal Wajdeczko > > >>> Signed-off-by: Ashutosh Dixit > > >>> --- > > >>> include/uapi/drm/xe_drm.h | 5 ++++- > > >>> 1 file changed, 4 insertions(+), 1 deletion(-) > > >>> > > >>> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h > > >>> index 93e00be44b2d..d831f277f186 100644 > > >>> --- a/include/uapi/drm/xe_drm.h > > >>> +++ b/include/uapi/drm/xe_drm.h > > >>> @@ -1379,8 +1379,11 @@ struct drm_xe_wait_user_fence { > > >>> * enum drm_xe_perf_type - Perf stream types > > >>> */ > > >>> enum drm_xe_perf_type { > > >>> + /** @DRM_XE_PERF_TYPE_OA: OA perf stream type */ > > >>> DRM_XE_PERF_TYPE_OA, > > >>> - __DRM_XE_PERF_TYPE_MAX, /* non-ABI */ > > >>> + > > >>> + /** @__DRM_XE_PERF_TYPE_MAX: Non-ABI */ > > >> > > >> hmm, I would rather not document it at all, by marking it as: > > >> > > >> /* private: */ > > >> > > >> see https://www.kernel.org/doc/html/next/doc-guide/kernel-doc.html#members > > >> > > >>> + __DRM_XE_PERF_TYPE_MAX, > > >>> }; > > >>> > > >>> /** > > > > > > Unfortunately, not documenting it doesn't seem to work and will result in > > > kernel-doc error below: > > > > > > $ ./scripts/kernel-doc -Werror -none include/uapi/drm/xe_drm.h > > > include/uapi/drm/xe_drm.h:1388: warning: Enum value '__DRM_XE_PERF_TYPE_MAX' not described in enum 'drm_xe_perf_type' > > > 1 warnings as Errors > > > > hmm, but below diff works for me: > > > > diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h > > index 93e00be44b2d..081e584240e6 100644 > > --- a/include/uapi/drm/xe_drm.h > > +++ b/include/uapi/drm/xe_drm.h > > @@ -1379,7 +1379,9 @@ struct drm_xe_wait_user_fence { > > * enum drm_xe_perf_type - Perf stream types > > */ > > enum drm_xe_perf_type { > > + /** @DRM_XE_PERF_TYPE_OA: OA perf stream type */ > > DRM_XE_PERF_TYPE_OA, > > + /* private: */ > > __DRM_XE_PERF_TYPE_MAX, /* non-ABI */ > > }; > > > > > > make sure you don't use /** private: */ as this might be not recognized > > Yup that was the issue. > > > > > OTOH, if __DRM_XE_PERF_TYPE_MAX is not a real ABI definition, why did we > > put this into uabi header? > > I have now removed it. > > > > > see also DRM_XE_OA_PROPERTY_MAX that IMO should be either removed from > > uabi or at least marked as a 'private' > > I have fixed this up in v2 here: > > https://patchwork.freedesktop.org/series/135225/ > > It is used internally so can't remove it, but have named it > __DRM_XE_OA_PROPERTY_MAX and marked it as private. I went ahead and eliminated this too in v3, since eliminating it was possible. > > > > > + Rodrigo > > Thanks. > -- > Ashutosh