[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 dri-devel mailing list