[PATCH] drm/amdgpu: add kernel DOC for ioctls in amdgpu_cs.c file

[Leo Liu]

On 05/31/2018 12:30 PM, Michel Dänzer wrote:
> On 2018-05-30 08:42 PM, Leo Liu wrote:
>> There are four ioctls in this files, and DOC gives details of
>> data structures for each of ioctls, and their functionalities.
>>
>> Signed-off-by: Leo Liu <leo.liu at amd.com>
> This isn't enough to actually make this part of the generated
> documentation. It needs to be hooked up to a *.rst file for that.
>
> I'm adding an amdgpu.rst file in
> https://patchwork.freedesktop.org/series/44035/ , where you could hook
> it up accordingly.
>
> Please check that generating the documentation (e.g. with make htmldocs)
> doesn't produce any warnings about amdgpu_cs.c, and that the result
> looks good in Documentation/output/gpu/amdgpu.html . The documentation
> format itself is documented in Documentation/output/doc-guide/index.html .
>
I will take a look this.

>> diff --git a/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c b/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c
>> index 12f0d18c6ee8..343ff115cff1 100644
>> --- a/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c
>> +++ b/drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c
>> @@ -1217,6 +1217,49 @@ static int amdgpu_cs_submit(struct amdgpu_cs_parser *p,
>>   	return 0;
>>   }
>>   
>> +/**
>> + * DOC:  amdgpu_cs_ioctl
> DOC comments shouldn't be used for functions, see
> Documentation/output/doc-guide/kernel-doc.html#function-documentation
>
This doc is not for the functions, it's like something in commit message 
about the details of in/out data, and what is the functionality for this 
ioctl.


>> @@ -1524,6 +1630,42 @@ static int amdgpu_cs_wait_any_fence(struct amdgpu_device *adev,
>>   	return r;
>>   }
>>   
>> +/**
>> + * DOC:  amdgpu_cs_wait_fences_ioctl
>> + *
>> + * This ioctl checks either all fences or any fence from multiple fences
>> + * to be signaled or waits to be signaled till timeout. So it's used to
>> + * check and wait multiple CS to be completed.
>> + *
>> + * In data structure:
>> + *
>> + * __u64 fences
>> + * Point to the multiple fences
>> + *
>> + * __u32 fence_count
>> + * number of fences
>> + *
>> + * __u32 wait_all
>> + * ways to wait either wait_all or wait_any
>> + *
>> + * __u64 timeout_ns
>> + * Absolute timeout to wait
>> + *
>> + * The function will extract user space fences based on pointer and counts,
>> + * then mapping them amdgpu fences and check if they are signaled or wait
>> + * to timeout.
>> + *
>> + * Out data:
>> + *
>> + *__u32 status
>> + * 0 CS completed
>> + * 1 CS busy
>> + *
>> + *__u32 first_signaled;
>> + * First signaled fence index
>> + *
>> + */
>> +
>>   /**
>>    * amdgpu_cs_wait_fences_ioctl - wait for multiple command submissions to finish
>>    *
> Any reason for not adding the above to the existing function
> documentation comment here?
Yes. It's used by close source Vulkan, where it might be lack of BO 
fence dependencies implementations like we do in Mesa.

Leo

>
>