From: Daniel Vetter <daniel.vetter@ffwll.ch>
Date: Thu, 14 Dec 2017 21:30:52 +0100
Subject: drm/syncobj: some kerneldoc polish
Git-commit: 924fe8df7fcfa508729b5a1591df41c0bafed429
Patch-mainline: v4.16-rc1
References: FATE#326289 FATE#326079 FATE#326049 FATE#322398 FATE#326166
Complete a few missing bits, fix up the existing xcross-references and
add a bunch more.
v2: Fix typos (Alex).
Cc: Dave Airlie <airlied@gmail.com> via lists.freedesktop.org
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20171214203054.20141-4-daniel.vetter@ffwll.ch
Acked-by: Petr Tesarik <ptesarik@suse.com>
---
drivers/gpu/drm/drm_syncobj.c | 45 ++++++++++++++++++++++++++++++++++++++----
include/drm/drm_syncobj.h | 34 ++++++++++++++++++-------------
2 files changed, 61 insertions(+), 18 deletions(-)
--- a/drivers/gpu/drm/drm_syncobj.c
+++ b/drivers/gpu/drm/drm_syncobj.c
@@ -29,9 +29,9 @@
/**
* DOC: Overview
*
- * DRM synchronisation objects (syncobj) are a persistent objects,
- * that contain an optional fence. The fence can be updated with a new
- * fence, or be NULL.
+ * DRM synchronisation objects (syncobj, see struct &drm_syncobj) are
+ * persistent objects that contain an optional fence. The fence can be updated
+ * with a new fence, or be NULL.
*
* syncobj's can be waited upon, where it will wait for the underlying
* fence.
@@ -61,7 +61,8 @@
* @file_private: drm file private pointer
* @handle: sync object handle to lookup.
*
- * Returns a reference to the syncobj pointed to by handle or NULL.
+ * Returns a reference to the syncobj pointed to by handle or NULL. The
+ * reference must be released by calling drm_syncobj_put().
*/
struct drm_syncobj *drm_syncobj_find(struct drm_file *file_private,
u32 handle)
@@ -229,6 +230,19 @@ static int drm_syncobj_assign_null_handl
return 0;
}
+/**
+ * drm_syncobj_find_fence - lookup and reference the fence in a sync object
+ * @file_private: drm file private pointer
+ * @handle: sync object handle to lookup.
+ * @fence: out parameter for the fence
+ *
+ * This is just a convenience function that combines drm_syncobj_find() and
+ * drm_syncobj_fence_get().
+ *
+ * Returns 0 on success or a negative error value on failure. On success @fence
+ * contains a reference to the fence, which must be released by calling
+ * dma_fence_put().
+ */
int drm_syncobj_find_fence(struct drm_file *file_private,
u32 handle,
struct dma_fence **fence)
@@ -269,6 +283,12 @@ EXPORT_SYMBOL(drm_syncobj_free);
* @out_syncobj: returned syncobj
* @flags: DRM_SYNCOBJ_* flags
* @fence: if non-NULL, the syncobj will represent this fence
+ *
+ * This is the first function to create a sync object. After creating, drivers
+ * probably want to make it available to userspace, either through
+ * drm_syncobj_get_handle() or drm_syncobj_get_fd().
+ *
+ * Returns 0 on success or a negative error value on failure.
*/
int drm_syncobj_create(struct drm_syncobj **out_syncobj, uint32_t flags,
struct dma_fence *fence)
@@ -302,6 +322,14 @@ EXPORT_SYMBOL(drm_syncobj_create);
/**
* drm_syncobj_get_handle - get a handle from a syncobj
+ * @file_private: drm file private pointer
+ * @syncobj: Sync object to export
+ * @handle: out parameter with the new handle
+ *
+ * Exports a sync object created with drm_syncobj_create() as a handle on
+ * @file_private to userspace.
+ *
+ * Returns 0 on success or a negative error value on failure.
*/
int drm_syncobj_get_handle(struct drm_file *file_private,
struct drm_syncobj *syncobj, u32 *handle)
@@ -371,6 +399,15 @@ static const struct file_operations drm_
.release = drm_syncobj_file_release,
};
+/**
+ * drm_syncobj_get_fd - get a file descriptor from a syncobj
+ * @syncobj: Sync object to export
+ * @p_fd: out parameter with the new file descriptor
+ *
+ * Exports a sync object created with drm_syncobj_create() as a file descriptor.
+ *
+ * Returns 0 on success or a negative error value on failure.
+ */
int drm_syncobj_get_fd(struct drm_syncobj *syncobj, int *p_fd)
{
struct file *file;
--- a/include/drm/drm_syncobj.h
+++ b/include/drm/drm_syncobj.h
@@ -33,36 +33,31 @@ struct drm_syncobj_cb;
/**
* struct drm_syncobj - sync object.
*
- * This structure defines a generic sync object which wraps a dma fence.
+ * This structure defines a generic sync object which wraps a &dma_fence.
*/
struct drm_syncobj {
/**
- * @refcount:
- *
- * Reference count of this object.
+ * @refcount: Reference count of this object.
*/
struct kref refcount;
/**
* @fence:
* NULL or a pointer to the fence bound to this object.
*
- * This field should not be used directly. Use drm_syncobj_fence_get
- * and drm_syncobj_replace_fence instead.
+ * This field should not be used directly. Use drm_syncobj_fence_get()
+ * and drm_syncobj_replace_fence() instead.
*/
struct dma_fence __rcu *fence;
/**
- * @cb_list:
- * List of callbacks to call when the fence gets replaced
+ * @cb_list: List of callbacks to call when the &fence gets replaced.
*/
struct list_head cb_list;
/**
- * @lock:
- * locks cb_list and write-locks fence.
+ * @lock: Protects &cb_list and write-locks &fence.
*/
spinlock_t lock;
/**
- * @file:
- * a file backing for this syncobj.
+ * @file: A file backing for this syncobj.
*/
struct file *file;
};
@@ -73,7 +68,7 @@ typedef void (*drm_syncobj_func_t)(struc
/**
* struct drm_syncobj_cb - callback for drm_syncobj_add_callback
* @node: used by drm_syncob_add_callback to append this struct to
- * syncobj::cb_list
+ * &drm_syncobj.cb_list
* @func: drm_syncobj_func_t to call
*
* This struct will be initialized by drm_syncobj_add_callback, additional
@@ -92,7 +87,7 @@ void drm_syncobj_free(struct kref *kref)
* drm_syncobj_get - acquire a syncobj reference
* @obj: sync object
*
- * This acquires additional reference to @obj. It is illegal to call this
+ * This acquires an additional reference to @obj. It is illegal to call this
* without already holding a reference. No locks required.
*/
static inline void
@@ -111,6 +106,17 @@ drm_syncobj_put(struct drm_syncobj *obj)
kref_put(&obj->refcount, drm_syncobj_free);
}
+/**
+ * drm_syncobj_fence_get - get a reference to a fence in a sync object
+ * @syncobj: sync object.
+ *
+ * This acquires additional reference to &drm_syncobj.fence contained in @obj,
+ * if not NULL. It is illegal to call this without already holding a reference.
+ * No locks required.
+ *
+ * Returns:
+ * Either the fence of @obj or NULL if there's none.
+ */
static inline struct dma_fence *
drm_syncobj_fence_get(struct drm_syncobj *syncobj)
{