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

[Leo Liu]

On 05/31/2018 12:39 PM, Leo Liu wrote:
>
>
> 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?
The existing is the function document, I am adding kernel doc for this 
ioctl.

Leo

> Yes. It's used by close source Vulkan, where it might be lack of BO 
> fence dependencies implementations like we do in Mesa.
>
> Leo
>
>>
>>
>
> _______________________________________________
> amd-gfx mailing list
> amd-gfx at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/amd-gfx