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

[Michel Dänzer]

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 .


> 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


> @@ -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?


-- 
Earthling Michel Dänzer               |               http://www.amd.com
Libre software enthusiast             |             Mesa and X developer