Document drm_bo_do_validate. Remove spurious 'do_wait' parameter.

Add comments about the parameters to drm_bo_do_validate, along
with comments for the DRM_BO_HINT options. Remove the 'do_wait'
parameter as it is duplicated by DRM_BO_HINT_DONT_BLOCK.

3 files changed, 47 insertions, 7 deletions

diff --git a/linux-core/drm_bo.c b/linux-core/drm_bo.c
index 4845f442..d7a507ab 100644
--- a/linux-core/drm_bo.c
+++ b/linux-core/drm_bo.c
@@ -1502,13 +1502,36 @@ static int drm_buffer_object_validate(struct drm_buffer_object *bo,
 	return 0;
 }
 
+/*
+ * drm_bo_do_validate
+ *
+ * 'validate' a buffer object. This changes where the buffer is
+ * located, along with changing access modes.
+ *
+ * flags	access rights, mapping parameters and cacheability. See
+ *		the DRM_BO_FLAG_* values in drm.h
+ *
+ * mask		which flag values to change; this allows callers to modify
+ *		things without knowing the current state of other flags.
+ *
+ * hint		changes the proceedure for this operation, see the DRM_BO_HINT_*
+ *		values in drm.h.
+ *
+ * fence_class	a driver-specific way of doing fences. Presumably, this
+ *		would be used if the driver had more than one submission and
+ *		fencing mechanism. At this point, there isn't any use of this
+ *		from the user mode code.
+ *
+ * rep		will be stuffed with the reply from validation
+ */
+
 int drm_bo_do_validate(struct drm_buffer_object *bo,
 		       uint64_t flags, uint64_t mask, uint32_t hint,
 		       uint32_t fence_class,
-		       int no_wait,
 		       struct drm_bo_info_rep *rep)
 {
 	int ret;
+	int no_wait = (hint & DRM_BO_HINT_DONT_BLOCK) != 0;
 
 	mutex_lock(&bo->mutex);
 	ret = drm_bo_wait_unfenced(bo, no_wait, 0);
@@ -1547,7 +1570,6 @@ int drm_bo_handle_validate(struct drm_file *file_priv, uint32_t handle,
 	struct drm_device *dev = file_priv->head->dev;
 	struct drm_buffer_object *bo;
 	int ret;
-	int no_wait = hint & DRM_BO_HINT_DONT_BLOCK;
 
 	mutex_lock(&dev->struct_mutex);
 	bo = drm_lookup_buffer_object(file_priv, handle, 1);
@@ -1567,8 +1589,7 @@ int drm_bo_handle_validate(struct drm_file *file_priv, uint32_t handle,
 		mask &= ~(DRM_BO_FLAG_NO_EVICT | DRM_BO_FLAG_NO_MOVE);
 
 
-	ret = drm_bo_do_validate(bo, flags, mask, hint, fence_class,
-				 no_wait, rep);
+	ret = drm_bo_do_validate(bo, flags, mask, hint, fence_class, rep);
 
 	if (!ret && bo_rep)
 		*bo_rep = bo;
diff --git a/linux-core/drm_objects.h b/linux-core/drm_objects.h
index 66611f6d..1c6ca795 100644
--- a/linux-core/drm_objects.h
+++ b/linux-core/drm_objects.h
@@ -546,7 +546,6 @@ extern struct drm_buffer_object *drm_lookup_buffer_object(struct drm_file *file_
 extern int drm_bo_do_validate(struct drm_buffer_object *bo,
 			      uint64_t flags, uint64_t mask, uint32_t hint,
 			      uint32_t fence_class,
-			      int no_wait,
 			      struct drm_bo_info_rep *rep);
 
 /*
diff --git a/shared-core/drm.h b/shared-core/drm.h
index 70a25b24..6f6f2386 100644
--- a/shared-core/drm.h
+++ b/shared-core/drm.h
@@ -748,11 +748,31 @@ struct drm_fence_arg {
 /* Driver-private flags */
 #define DRM_BO_MASK_DRIVER      0xFFFF000000000000ULL
 
-/* Don't block on validate and map */
+/*
+ * Don't block on validate and map. Instead, return EBUSY.
+ */
 #define DRM_BO_HINT_DONT_BLOCK  0x00000002
-/* Don't place this buffer on the unfenced list.*/
+/*
+ * Don't place this buffer on the unfenced list. This means
+ * that the buffer will not end up having a fence associated
+ * with it as a result of this operation
+ */
 #define DRM_BO_HINT_DONT_FENCE  0x00000004
+/*
+ * Sleep while waiting for the operation to complete.
+ * Without this flag, the kernel will, instead, spin
+ * until this operation has completed. I'm not sure
+ * why you would ever want this, so please always
+ * provide DRM_BO_HINT_WAIT_LAZY to any operation
+ * which may block
+ */
 #define DRM_BO_HINT_WAIT_LAZY   0x00000008
+/*
+ * The client has compute relocations refering to this buffer using the
+ * offset in the presumed_offset field. If that offset ends up matching
+ * where this buffer lands, the kernel is free to skip executing those
+ * relocations
+ */
 #define DRM_BO_HINT_PRESUMED_OFFSET 0x00000010
 
 #define DRM_BO_INIT_MAGIC 0xfe769812