[PATCH] Add/update function level documentation and add reference to amdgpu_vm.c in amdgpu.rst

[Michel Dänzer]

On 2018-06-11 05:14 PM, Andrey Grodzovsky wrote:
> Signed-off-by: Andrey Grodzovsky <andrey.grodzovsky at amd.com>
> ---
>  Documentation/gpu/amdgpu.rst           |   9 ++
>  drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c | 193 ++++++++++++++++++++++++++++-----
>  2 files changed, 177 insertions(+), 25 deletions(-)
> 
> diff --git a/Documentation/gpu/amdgpu.rst b/Documentation/gpu/amdgpu.rst
> index a4852f9..7a4e9c1 100644
> --- a/Documentation/gpu/amdgpu.rst
> +++ b/Documentation/gpu/amdgpu.rst
> @@ -44,3 +44,12 @@ MMU Notifier
>  
>  .. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c
>     :internal:
> +
> +AMDGPU Virtual Memory
> +---------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c
> +   :doc: MMU Notifier

This must say

   :doc: GPUVM

otherwise you should get a warning like

./drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1: warning: no structured
comments found

and the DOC comment body below is missing from the generated documentation.


> @@ -94,6 +96,15 @@ struct amdgpu_prt_cb {
>  	struct dma_fence_cb cb;
>  };
>  
> +/**
> + * amdgpu_vm_bo_base_init - Adds bo to the list of bos associated with the vm
> + * @base: base structure for tracking BO usage in a VM
> + * @vm: vm to which bo is to be added
> + * @bo: amdgpu buffer object

Most function comments seem to have an empty line between the function
name and the first parameter. Either works, and I don't particularly cre
which one we go for, but we should probably try to be consistent either way.


> - * Returns the number of bits the pfn needs to be right shifted for a level.
> + * Returns:
> + * The number of bits the pfn needs to be right shifted for a level.
>   */

Thanks for using the correct return value documentation format! :)


Other than that, looks good to me, but Christian et al should probably
check that the function comments make sense.


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