[Intel-gfx] [PATCH 3/5] drm/syncobj: some kerneldoc polish
Alex Deucher
alexdeucher at gmail.com
Fri Dec 15 02:06:14 UTC 2017
On Thu, Dec 14, 2017 at 3:30 PM, Daniel Vetter <daniel.vetter at ffwll.ch> wrote:
> Complete a few missing bits, fix up the existing xcross-references and
> add a bunch more.
>
> Cc: Dave Airlie <airlied at gmail.com> via lists.freedesktop.org
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
> drivers/gpu/drm/drm_syncobj.c | 45 +++++++++++++++++++++++++++++++++++++++----
> include/drm/drm_syncobj.h | 32 +++++++++++++++++-------------
> 2 files changed, 60 insertions(+), 17 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_syncobj.c b/drivers/gpu/drm/drm_syncobj.c
> index 9b733c510cbf..b6d0c2c400ec 100644
> --- 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 a
> + * persistent objects, that contain an optional fence. The fence can be updated
grammer:
are persistent objects that contain an optional fence
> + * 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 mus be released by calling
typo: must
> + * 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().
grammer:
After creating, drivers probably want to make it available to userspace
> + *
> + * 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;
> diff --git a/include/drm/drm_syncobj.h b/include/drm/drm_syncobj.h
> index 9e8ba90c6784..87865774bdaa 100644
> --- 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)(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
> @@ -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,
grammer:
This acquires an additional reference
With those fixed up:
Reviewed-by: Alex Deucher <alexander.deucher at amd.com>
> + * 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)
> {
> --
> 2.15.1
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
More information about the Intel-gfx
mailing list