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

[Michal Wajdeczko <michal.wajdeczko@intel.com>]

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

OTOH, if __DRM_XE_PERF_TYPE_MAX is not a real ABI definition, why did we
put this into uabi header?

see also DRM_XE_OA_PROPERTY_MAX that IMO should be either removed from
uabi or at least marked as a 'private'

+ Rodrigo

> 
> Thanks.
> --
> Ashutosh