aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel Vetter <daniel.vetter@ffwll.ch>2017-12-14 15:30:52 -0500
committerDaniel Vetter <daniel.vetter@ffwll.ch>2017-12-15 05:26:52 -0500
commit924fe8df7fcfa508729b5a1591df41c0bafed429 (patch)
treece7f963ac80ac92f4266287a8734769b44b520c3
parent42f1b310332916d130455f300504b72f80c2a66c (diff)
drm/syncobj: some kerneldoc polish
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
-rw-r--r--drivers/gpu/drm/drm_syncobj.c45
-rw-r--r--include/drm/drm_syncobj.h34
2 files changed, 61 insertions, 18 deletions
diff --git a/drivers/gpu/drm/drm_syncobj.c b/drivers/gpu/drm/drm_syncobj.c
index 9b733c510cbf..131695915acd 100644
--- a/drivers/gpu/drm/drm_syncobj.c
+++ b/drivers/gpu/drm/drm_syncobj.c
@@ -29,9 +29,9 @@
29/** 29/**
30 * DOC: Overview 30 * DOC: Overview
31 * 31 *
32 * DRM synchronisation objects (syncobj) are a persistent objects, 32 * DRM synchronisation objects (syncobj, see struct &drm_syncobj) are
33 * that contain an optional fence. The fence can be updated with a new 33 * persistent objects that contain an optional fence. The fence can be updated
34 * fence, or be NULL. 34 * with a new fence, or be NULL.
35 * 35 *
36 * syncobj's can be waited upon, where it will wait for the underlying 36 * syncobj's can be waited upon, where it will wait for the underlying
37 * fence. 37 * fence.
@@ -61,7 +61,8 @@
61 * @file_private: drm file private pointer 61 * @file_private: drm file private pointer
62 * @handle: sync object handle to lookup. 62 * @handle: sync object handle to lookup.
63 * 63 *
64 * Returns a reference to the syncobj pointed to by handle or NULL. 64 * Returns a reference to the syncobj pointed to by handle or NULL. The
65 * reference must be released by calling drm_syncobj_put().
65 */ 66 */
66struct drm_syncobj *drm_syncobj_find(struct drm_file *file_private, 67struct drm_syncobj *drm_syncobj_find(struct drm_file *file_private,
67 u32 handle) 68 u32 handle)
@@ -229,6 +230,19 @@ static int drm_syncobj_assign_null_handle(struct drm_syncobj *syncobj)
229 return 0; 230 return 0;
230} 231}
231 232
233/**
234 * drm_syncobj_find_fence - lookup and reference the fence in a sync object
235 * @file_private: drm file private pointer
236 * @handle: sync object handle to lookup.
237 * @fence: out parameter for the fence
238 *
239 * This is just a convenience function that combines drm_syncobj_find() and
240 * drm_syncobj_fence_get().
241 *
242 * Returns 0 on success or a negative error value on failure. On success @fence
243 * contains a reference to the fence, which must be released by calling
244 * dma_fence_put().
245 */
232int drm_syncobj_find_fence(struct drm_file *file_private, 246int drm_syncobj_find_fence(struct drm_file *file_private,
233 u32 handle, 247 u32 handle,
234 struct dma_fence **fence) 248 struct dma_fence **fence)
@@ -269,6 +283,12 @@ EXPORT_SYMBOL(drm_syncobj_free);
269 * @out_syncobj: returned syncobj 283 * @out_syncobj: returned syncobj
270 * @flags: DRM_SYNCOBJ_* flags 284 * @flags: DRM_SYNCOBJ_* flags
271 * @fence: if non-NULL, the syncobj will represent this fence 285 * @fence: if non-NULL, the syncobj will represent this fence
286 *
287 * This is the first function to create a sync object. After creating, drivers
288 * probably want to make it available to userspace, either through
289 * drm_syncobj_get_handle() or drm_syncobj_get_fd().
290 *
291 * Returns 0 on success or a negative error value on failure.
272 */ 292 */
273int drm_syncobj_create(struct drm_syncobj **out_syncobj, uint32_t flags, 293int drm_syncobj_create(struct drm_syncobj **out_syncobj, uint32_t flags,
274 struct dma_fence *fence) 294 struct dma_fence *fence)
@@ -302,6 +322,14 @@ EXPORT_SYMBOL(drm_syncobj_create);
302 322
303/** 323/**
304 * drm_syncobj_get_handle - get a handle from a syncobj 324 * drm_syncobj_get_handle - get a handle from a syncobj
325 * @file_private: drm file private pointer
326 * @syncobj: Sync object to export
327 * @handle: out parameter with the new handle
328 *
329 * Exports a sync object created with drm_syncobj_create() as a handle on
330 * @file_private to userspace.
331 *
332 * Returns 0 on success or a negative error value on failure.
305 */ 333 */
306int drm_syncobj_get_handle(struct drm_file *file_private, 334int drm_syncobj_get_handle(struct drm_file *file_private,
307 struct drm_syncobj *syncobj, u32 *handle) 335 struct drm_syncobj *syncobj, u32 *handle)
@@ -388,6 +416,15 @@ static int drm_syncobj_alloc_file(struct drm_syncobj *syncobj)
388 return 0; 416 return 0;
389} 417}
390 418
419/**
420 * drm_syncobj_get_fd - get a file descriptor from a syncobj
421 * @syncobj: Sync object to export
422 * @p_fd: out parameter with the new file descriptor
423 *
424 * Exports a sync object created with drm_syncobj_create() as a file descriptor.
425 *
426 * Returns 0 on success or a negative error value on failure.
427 */
391int drm_syncobj_get_fd(struct drm_syncobj *syncobj, int *p_fd) 428int drm_syncobj_get_fd(struct drm_syncobj *syncobj, int *p_fd)
392{ 429{
393 int ret; 430 int ret;
diff --git a/include/drm/drm_syncobj.h b/include/drm/drm_syncobj.h
index 9e8ba90c6784..3980602472c0 100644
--- a/include/drm/drm_syncobj.h
+++ b/include/drm/drm_syncobj.h
@@ -33,36 +33,31 @@ struct drm_syncobj_cb;
33/** 33/**
34 * struct drm_syncobj - sync object. 34 * struct drm_syncobj - sync object.
35 * 35 *
36 * This structure defines a generic sync object which wraps a dma fence. 36 * This structure defines a generic sync object which wraps a &dma_fence.
37 */ 37 */
38struct drm_syncobj { 38struct drm_syncobj {
39 /** 39 /**
40 * @refcount: 40 * @refcount: Reference count of this object.
41 *
42 * Reference count of this object.
43 */ 41 */
44 struct kref refcount; 42 struct kref refcount;
45 /** 43 /**
46 * @fence: 44 * @fence:
47 * NULL or a pointer to the fence bound to this object. 45 * NULL or a pointer to the fence bound to this object.
48 * 46 *
49 * This field should not be used directly. Use drm_syncobj_fence_get 47 * This field should not be used directly. Use drm_syncobj_fence_get()
50 * and drm_syncobj_replace_fence instead. 48 * and drm_syncobj_replace_fence() instead.
51 */ 49 */
52 struct dma_fence __rcu *fence; 50 struct dma_fence __rcu *fence;
53 /** 51 /**
54 * @cb_list: 52 * @cb_list: List of callbacks to call when the &fence gets replaced.
55 * List of callbacks to call when the fence gets replaced
56 */ 53 */
57 struct list_head cb_list; 54 struct list_head cb_list;
58 /** 55 /**
59 * @lock: 56 * @lock: Protects &cb_list and write-locks &fence.
60 * locks cb_list and write-locks fence.
61 */ 57 */
62 spinlock_t lock; 58 spinlock_t lock;
63 /** 59 /**
64 * @file: 60 * @file: A file backing for this syncobj.
65 * a file backing for this syncobj.
66 */ 61 */
67 struct file *file; 62 struct file *file;
68}; 63};
@@ -73,7 +68,7 @@ typedef void (*drm_syncobj_func_t)(struct drm_syncobj *syncobj,
73/** 68/**
74 * struct drm_syncobj_cb - callback for drm_syncobj_add_callback 69 * struct drm_syncobj_cb - callback for drm_syncobj_add_callback
75 * @node: used by drm_syncob_add_callback to append this struct to 70 * @node: used by drm_syncob_add_callback to append this struct to
76 * syncobj::cb_list 71 * &drm_syncobj.cb_list
77 * @func: drm_syncobj_func_t to call 72 * @func: drm_syncobj_func_t to call
78 * 73 *
79 * This struct will be initialized by drm_syncobj_add_callback, additional 74 * This struct will be initialized by drm_syncobj_add_callback, additional
@@ -92,7 +87,7 @@ void drm_syncobj_free(struct kref *kref);
92 * drm_syncobj_get - acquire a syncobj reference 87 * drm_syncobj_get - acquire a syncobj reference
93 * @obj: sync object 88 * @obj: sync object
94 * 89 *
95 * This acquires additional reference to @obj. It is illegal to call this 90 * This acquires an additional reference to @obj. It is illegal to call this
96 * without already holding a reference. No locks required. 91 * without already holding a reference. No locks required.
97 */ 92 */
98static inline void 93static inline void
@@ -111,6 +106,17 @@ drm_syncobj_put(struct drm_syncobj *obj)
111 kref_put(&obj->refcount, drm_syncobj_free); 106 kref_put(&obj->refcount, drm_syncobj_free);
112} 107}
113 108
109/**
110 * drm_syncobj_fence_get - get a reference to a fence in a sync object
111 * @syncobj: sync object.
112 *
113 * This acquires additional reference to &drm_syncobj.fence contained in @obj,
114 * if not NULL. It is illegal to call this without already holding a reference.
115 * No locks required.
116 *
117 * Returns:
118 * Either the fence of @obj or NULL if there's none.
119 */
114static inline struct dma_fence * 120static inline struct dma_fence *
115drm_syncobj_fence_get(struct drm_syncobj *syncobj) 121drm_syncobj_fence_get(struct drm_syncobj *syncobj)
116{ 122{