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 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.

>
> + Rodrigo

Thanks.
--
Ashutosh