[Intel-xe] [PATCH 1/2] drm/xe/uapi: silence kernel-doc errors

[Matthew Auld]

On 23/06/2023 13:21, Francois Dugast wrote:
> On Fri, Jun 23, 2023 at 12:29:21PM +0100, Matthew Auld wrote:
>> ./include/uapi/drm/xe_drm.h:263: warning: Function parameter or member
>> 'gts' not described in 'drm_xe_query_gts'
>>
>> ./include/uapi/drm/xe_drm.h:854: WARNING: Inline emphasis start-string
>> without end-string.
>>
>> With the idea to include the uapi file in the pre-merge CI hooks when
>> building the kernel-doc, so first make sure it's clean.
>>
>> Signed-off-by: Matthew Auld <matthew.auld at intel.com>
>> Cc: Francois Dugast <francois.dugast at intel.com>
>> Cc: Lucas De Marchi <lucas.demarchi at intel.com>
>> ---
>>   include/uapi/drm/xe_drm.h | 9 +++++----
>>   1 file changed, 5 insertions(+), 4 deletions(-)
>>
>> diff --git a/include/uapi/drm/xe_drm.h b/include/uapi/drm/xe_drm.h
>> index 432bd87ca401..5da6a04bb478 100644
>> --- a/include/uapi/drm/xe_drm.h
>> +++ b/include/uapi/drm/xe_drm.h
>> @@ -228,7 +228,7 @@ struct drm_xe_query_config {
>>   	__u64 info[];
>>   };
>>   
>> -/**
>> +/*
> 
> There are multiple occurrences of this in this file, which seems ok to
> me. Is this one particular somehow? If it needs to be fixed why not the
> others?
> 
> The commit message refers to a missing description line 263, that is
> attribute gts of struct drm_xe_query_gts. Is that not the real issue?

Yes, that sounds better. Will fix.

> 
>      	} gts[];
> 
> Francois
> 
>>    * struct drm_xe_query_gts - describe GTs
>>    *
>>    * If a query is made with a struct drm_xe_device_query where .query
>> @@ -242,7 +242,7 @@ struct drm_xe_query_gts {
>>   	/** @pad: MBZ */
>>   	__u32 pad;
>>   
>> -	/*
>> +	/* TODO: convert to proper kernel-doc.
>>   	 * TODO: Perhaps info about every mem region relative to this GT? e.g.
>>   	 * bandwidth between this GT and remote region?
>>   	 */
>> @@ -852,8 +852,9 @@ struct drm_xe_mmio {
>>    * struct drm_xe_wait_user_fence - wait user fence
>>    *
>>    * Wait on user fence, XE will wakeup on every HW engine interrupt in the
>> - * instances list and check if user fence is complete:
>> - * (*addr & MASK) OP (VALUE & MASK)
>> + * instances list and check if user fence is complete::
>> + *
>> + *	(*addr & MASK) OP (VALUE & MASK)
>>    *
>>    * Returns to user on user fence completion or timeout.
>>    */
>> -- 
>> 2.41.0
>>