diff options
author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2017-12-14 15:30:52 -0500 |
---|---|---|
committer | Daniel Vetter <daniel.vetter@ffwll.ch> | 2017-12-15 05:26:52 -0500 |
commit | 924fe8df7fcfa508729b5a1591df41c0bafed429 (patch) | |
tree | ce7f963ac80ac92f4266287a8734769b44b520c3 | |
parent | 42f1b310332916d130455f300504b72f80c2a66c (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.c | 45 | ||||
-rw-r--r-- | include/drm/drm_syncobj.h | 34 |
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 | */ |
66 | struct drm_syncobj *drm_syncobj_find(struct drm_file *file_private, | 67 | struct 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 | */ | ||
232 | int drm_syncobj_find_fence(struct drm_file *file_private, | 246 | int 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 | */ |
273 | int drm_syncobj_create(struct drm_syncobj **out_syncobj, uint32_t flags, | 293 | int 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 | */ |
306 | int drm_syncobj_get_handle(struct drm_file *file_private, | 334 | int 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 | */ | ||
391 | int drm_syncobj_get_fd(struct drm_syncobj *syncobj, int *p_fd) | 428 | int 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 | */ |
38 | struct drm_syncobj { | 38 | struct 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 | */ |
98 | static inline void | 93 | static 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 | */ | ||
114 | static inline struct dma_fence * | 120 | static inline struct dma_fence * |
115 | drm_syncobj_fence_get(struct drm_syncobj *syncobj) | 121 | drm_syncobj_fence_get(struct drm_syncobj *syncobj) |
116 | { | 122 | { |