Re: [PATCH] drm/xe/oa: Fix 'enum drm_xe_perf_type' kernel doc warnings

["Dixit, Ashutosh" <ashutosh.dixit@intel.com>]

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 <michal.wajdeczko@intel.com>
> > >>> Signed-off-by: Ashutosh Dixit <ashutosh.dixit@intel.com>
> > >>> ---
> > >>>  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