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
This commit is contained in:
Daniel Vetter
parent
42f1b31033
commit
924fe8df7f
2 changed files with 61 additions and 18 deletions
|
|
@ -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_handle(struct drm_syncobj *syncobj)
|
|||
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)
|
||||
|
|
@ -388,6 +416,15 @@ static int drm_syncobj_alloc_file(struct drm_syncobj *syncobj)
|
|||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* 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)
|
||||
{
|
||||
int ret;
|
||||
|
|
|
|||
|
|
@ -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)(struct drm_syncobj *syncobj,
|
|||
/**
|
||||
* 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)
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue