From 5f23519b14e54823c94f5db5ad81e6bd5ffd3877 Mon Sep 17 00:00:00 2001
From: Keith Packard <keithp@keithp.com>
Date: Fri, 14 Dec 2007 12:45:55 -0800
Subject: Document drm_bo_handle_validate. Match drm_bo_do_validate parameter
 order.

Document parameters and usage for drm_bo_handle_validate. Change parameter
order to match drm_bo_do_validate (fence_class has been moved to after
flags, hint and mask values). Existing users of this function have been
changed, but out-of-tree users must be modified separately.
---
 linux-core/drm_bo.c      | 67 ++++++++++++++++++++++++++++++++++++------------
 linux-core/drm_objects.h |  5 ++--
 2 files changed, 52 insertions(+), 20 deletions(-)

(limited to 'linux-core')

diff --git a/linux-core/drm_bo.c b/linux-core/drm_bo.c
index d7a507ab..aa613d7a 100644
--- a/linux-core/drm_bo.c
+++ b/linux-core/drm_bo.c
@@ -1502,27 +1502,29 @@ 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.
+ * @bo:	the buffer object
  *
- * flags	access rights, mapping parameters and cacheability. See
- *		the DRM_BO_FLAG_* values in drm.h
+ * @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.
+ * @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.
+ * @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.
+ * @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
+ * @rep: To be stuffed with the reply from validation
+ * 
+ * 'validate' a buffer object. This changes where the buffer is
+ * located, along with changing access modes.
  */
 
 int drm_bo_do_validate(struct drm_buffer_object *bo,
@@ -1558,11 +1560,42 @@ out:
 }
 EXPORT_SYMBOL(drm_bo_do_validate);
 
+/**
+ * drm_bo_handle_validate
+ *
+ * @file_priv: the drm file private, used to get a handle to the user context
+ *
+ * @handle: the buffer object handle
+ *
+ * @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.
+ *
+ * @use_old_fence_class: don't change fence class, pull it from the buffer object
+ *
+ * @rep: To be stuffed with the reply from validation
+ * 
+ * @bp_rep: To be stuffed with the buffer object pointer
+ *
+ * Perform drm_bo_do_validate on a buffer referenced by a user-space handle.
+ * Some permissions checking is done on the parameters, otherwise this
+ * is a thin wrapper.
+ */
 
 int drm_bo_handle_validate(struct drm_file *file_priv, uint32_t handle,
-			   uint32_t fence_class,
 			   uint64_t flags, uint64_t mask,
 			   uint32_t hint,
+			   uint32_t fence_class,
 			   int use_old_fence_class,
 			   struct drm_bo_info_rep *rep,
 			   struct drm_buffer_object **bo_rep)
@@ -1818,11 +1851,11 @@ int drm_bo_setstatus_ioctl(struct drm_device *dev,
 	if (ret)
 		return ret;
 
-	ret = drm_bo_handle_validate(file_priv, req->handle, req->fence_class,
+	ret = drm_bo_handle_validate(file_priv, req->handle,
 				     req->flags,
 				     req->mask,
 				     req->hint | DRM_BO_HINT_DONT_FENCE,
-				     1,
+				     req->fence_class, 1,
 				     rep, NULL);
 
 	(void) drm_bo_read_unlock(&dev->bm.bm_lock);
diff --git a/linux-core/drm_objects.h b/linux-core/drm_objects.h
index 1c6ca795..0926b47b 100644
--- a/linux-core/drm_objects.h
+++ b/linux-core/drm_objects.h
@@ -535,9 +535,8 @@ extern int drm_bo_clean_mm(struct drm_device *dev, unsigned mem_type);
 extern int drm_bo_init_mm(struct drm_device *dev, unsigned type,
 			  unsigned long p_offset, unsigned long p_size);
 extern int drm_bo_handle_validate(struct drm_file *file_priv, uint32_t handle,
-				  uint32_t fence_class, uint64_t flags,
-				  uint64_t mask, uint32_t hint,
-				  int use_old_fence_class,
+				  uint64_t flags, uint64_t mask, uint32_t hint,
+				  uint32_t fence_class, int use_old_fence_class,
 				  struct drm_bo_info_rep *rep,
 				  struct drm_buffer_object **bo_rep);
 extern struct drm_buffer_object *drm_lookup_buffer_object(struct drm_file *file_priv,
-- 
cgit v1.2.3