drm/syncobj: some kerneldoc polish (924fe8df) · Commits · e / devices / android_kernel_xiaomi_nabu

drivers/gpu/drm/drm_syncobj.c

+41 −4

Original line number	Diff line number	Diff line
		@@ -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;

include/drm/drm_syncobj.h

+20 −14

Original line number	Diff line number	Diff line
		@@ -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)
		{