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

[Leo Liu]

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>
---
 drivers/gpu/drm/amd/amdgpu/amdgpu_cs.c | 142 +++++++++++++++++++++++++
 1 file changed, 142 insertions(+)

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
+ *
+ * This ioctl processes user space command submission chunks,
+ * return a fence sequence number associated to a amdgpu fence.
+ *
+ * In data structure:
+ *
+ * __u32 ctx_id:
+ * Integer ID, created via DRM_AMDGPU_CTX ioctl call when user space
+ * command submission context created. It will be used as ID for later
+ * command submission context.
+ *
+ * __u32 bo_list_handle:
+ * Handle of resources list associated with this CS, created via
+ * DRM_AMDGPU_BO_LIST ioctl call before command submission, and
+ * the BOs in the list will be validated.
+ *
+ * __u32 num_chunks:
+ * Number of chunks, their types include:
+ * AMDGPU_CHUNK_ID_IB
+ * The data will be filled into IB buffer, and mappped to a HW ring.
+ *
+ * AMDGPU_CHUNK_ID_FENCE
+ * The data will be used to find user fence BO and its offset.
+ *
+ * AMDGPU_CHUNK_ID_DEPENDENCIES
+ * AMDGPU_CHUNK_ID_SYNCOBJ_IN
+ * AMDGPU_CHUNK_ID_SYNCOBJ_OUT
+ * These will be parsed as fence dependencies in given requirement,
+ * and will be remembered and to be synced later.
+ *
+ * __u32 _pad:
+ *
+ * __u64 chunks:
+ * Point to the CS chunks.
+ *
+ * amdgpu_cs_submit() function will be called to initialize a scheduler
+ * job, and associate it to a HW ring, add a new fence to the context,
+ * and then push the job to the queue for scheduler to process,
+ * it will return fence sequence number to user space.
+ *
+ */
 int amdgpu_cs_ioctl(struct drm_device *dev, void *data, struct drm_file *filp)
 {
 	struct amdgpu_device *adev = dev->dev_private;
@@ -1272,6 +1315,38 @@ int amdgpu_cs_ioctl(struct drm_device *dev, void *data, struct drm_file *filp)
 	return r;
 }
 
+/**
+ * DOC:  amdgpu_cs_wait_ioctl
+ *
+ * This ioctl checks a user space fence associated to a amdgpu fence whether
+ * it's signaled or waits to be signaled till timeout with kernel dma fence.
+ * Once signaled, the associated CS is completed.
+ *
+ * In data structure:
+ *
+ * __u64 handle:
+ * The fence sequence number from amdgpu_cs_ioctl returned.
+ *
+ * __u64 timeout:
+ * Absolute timeout to wait.
+ *
+ * __u32 ip_type:
+ * __u32 ip_instance:
+ * __u32 ring:
+ * Map user space ring to a kernel HW ring, then use the seq(handle) to
+ * find the amdgpu fence, that will be checked and waited.
+ *
+ * __u32 ctx_id:
+ * ID for command submission context
+ *
+ * Out data:
+ *
+ * __u64 status:
+ * 0 CS completed
+ * 1 CS busy
+ *
+ */
+
 /**
  * amdgpu_cs_wait_ioctl - wait for a command submission to finish
  *
@@ -1358,6 +1433,37 @@ static struct dma_fence *amdgpu_cs_get_fence(struct amdgpu_device *adev,
 	return fence;
 }
 
+/**
+ * DOC: amdgpu_cs_fence_to_handle_ioctl
+ *
+ * This ioctl converts a user space fence into a fence object handle or fd,
+ * or file fd based on the purpose in “what”, since using handles or fd will
+ * be more efficient than ioctl call from user space to check signaled.
+ *
+ * In data structure:
+ *
+ * struct drm_amdgpu_fence fence:
+ * User space fence structured with ctx_id, ip_type, ip_instance, ring, seq_no
+ *
+ * __u32 what:
+ * Types of handle to convert include:
+ *
+ * AMDGPU_FENCE_TO_HANDLE_GET_SYNCOBJ
+ * It is required to return a process-dependent handle for a sync object
+ *
+ * AMDGPU_FENCE_TO_HANDLE_GET_SYNCOBJ_FD
+ * It is  required to return a process-independent fd for a sync object
+ *
+ * AMDGPU_FENCE_TO_HANDLE_GET_SYNC_FILE_FD
+ * It is required to return a process-independent fd to a sync file
+ *
+ * __u32 pad
+ *
+ * Out data:
+ * __u32 handle:
+ * Handle to be returned to user space
+ *
+ */
 int amdgpu_cs_fence_to_handle_ioctl(struct drm_device *dev, void *data,
 				    struct drm_file *filp)
 {
@@ -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
  *
-- 
2.17.0