Commit d6abed2a authored by Daniel Vetter's avatar Daniel Vetter
Browse files

dma-buf: Switch to inline kerneldoc 



Also review & update everything while we're at it.

This is prep work to smash a ton of stuff into the kerneldoc for
@resv.

v2: Move the doc for sysfs_entry.attachment_uid to the right place too
(Sam)

Reviewed-by: default avatarSam Ravnborg <sam@ravnborg.org>
Acked-by: default avatarChristian König <christian.koenig@amd.com>
Cc: Sam Ravnborg <sam@ravnborg.org>
Reviewed-by: default avatarAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@intel.com>
Cc: Sumit Semwal <sumit.semwal@linaro.org>
Cc: "Christian König" <christian.koenig@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Dave Airlie <airlied@redhat.com>
Cc: Nirmoy Das <nirmoy.das@amd.com>
Cc: Deepak R Varma <mh12gx2825@gmail.com>
Cc: Chen Li <chenli@uniontech.com>
Cc: Kevin Wang <kevin1.wang@amd.com>
Cc: linux-media@vger.kernel.org
Cc: linaro-mm-sig@lists.linaro.org
Link: https://patchwork.freedesktop.org/patch/msgid/20210623161712.3370885-1-daniel.vetter@ffwll.ch
parent d7fdae59

include/linux/dma-buf.h

+90 −26
Original line number Diff line number Diff line
@@ -289,30 +289,6 @@ struct dma_buf_ops { 


/**

 * struct dma_buf - shared buffer object

 * @size: size of the buffer; invariant over the lifetime of the buffer.

 * @file: file pointer used for sharing buffers across, and for refcounting.

 * @attachments: list of dma_buf_attachment that denotes all devices attached,

 *               protected by dma_resv lock.

 * @ops: dma_buf_ops associated with this buffer object.

 * @lock: used internally to serialize list manipulation, attach/detach and

 *        vmap/unmap

 * @vmapping_counter: used internally to refcnt the vmaps

 * @vmap_ptr: the current vmap ptr if vmapping_counter > 0

 * @exp_name: name of the exporter; useful for debugging.

 * @name: userspace-provided name; useful for accounting and debugging,

 *        protected by @resv.

 * @name_lock: spinlock to protect name access

 * @owner: pointer to exporter module; used for refcounting when exporter is a

 *         kernel module.

 * @list_node: node for dma_buf accounting and debugging.

 * @priv: exporter specific private data for this buffer object.

 * @resv: reservation object linked to this dma-buf

 * @poll: for userspace poll support

 * @cb_excl: for userspace poll support

 * @cb_shared: for userspace poll support

 * @sysfs_entry: for exposing information about this buffer in sysfs.

 * The attachment_uid member of @sysfs_entry is protected by dma_resv lock

 * and is incremented on each attach.

 *

 * This represents a shared buffer, created by calling dma_buf_export(). The

 * userspace representation is a normal file descriptor, which can be created by
@@ -324,24 +300,100 @@ struct dma_buf_ops { 
 * Device DMA access is handled by the separate &struct dma_buf_attachment.

 */

struct dma_buf {

	/**

	 * @size:

	 *

	 * Size of the buffer; invariant over the lifetime of the buffer.

	 */

	size_t size;



	/**

	 * @file:

	 *

	 * File pointer used for sharing buffers across, and for refcounting.

	 * See dma_buf_get() and dma_buf_put().

	 */

	struct file *file;



	/**

	 * @attachments:

	 *

	 * List of dma_buf_attachment that denotes all devices attached,

	 * protected by &dma_resv lock @resv.

	 */

	struct list_head attachments;



	/** @ops: dma_buf_ops associated with this buffer object. */

	const struct dma_buf_ops *ops;



	/**

	 * @lock:

	 *

	 * Used internally to serialize list manipulation, attach/detach and

	 * vmap/unmap. Note that in many cases this is superseeded by

	 * dma_resv_lock() on @resv.

	 */

	struct mutex lock;



	/**

	 * @vmapping_counter:

	 *

	 * Used internally to refcnt the vmaps returned by dma_buf_vmap().

	 * Protected by @lock.

	 */

	unsigned vmapping_counter;



	/**

	 * @vmap_ptr:

	 * The current vmap ptr if @vmapping_counter > 0. Protected by @lock.

	 */

	struct dma_buf_map vmap_ptr;



	/**

	 * @exp_name:

	 *

	 * Name of the exporter; useful for debugging. See the

	 * DMA_BUF_SET_NAME IOCTL.

	 */

	const char *exp_name;



	/**

	 * @name:

	 *

	 * Userspace-provided name; useful for accounting and debugging,

	 * protected by dma_resv_lock() on @resv and @name_lock for read access.

	 */

	const char *name;



	/** @name_lock: Spinlock to protect name acces for read access. */

	spinlock_t name_lock;



	/**

	 * @owner:

	 *

	 * Pointer to exporter module; used for refcounting when exporter is a

	 * kernel module.

	 */

	struct module *owner;



	/** @list_node: node for dma_buf accounting and debugging. */

	struct list_head list_node;



	/** @priv: exporter specific private data for this buffer object. */

	void *priv;



	/**

	 * @resv:

	 *

	 * Reservation object linked to this dma-buf.

	 */

	struct dma_resv *resv;



	/* poll support */

	/** @poll: for userspace poll support */

	wait_queue_head_t poll;



	/** @cb_excl: for userspace poll support */

	/** @cb_shared: for userspace poll support */

	struct dma_buf_poll_cb_t {

		struct dma_fence_cb cb;

		wait_queue_head_t *poll;
@@ -349,10 +401,22 @@ struct dma_buf { 
		__poll_t active;

	} cb_excl, cb_shared;

#ifdef CONFIG_DMABUF_SYSFS_STATS

	/* for sysfs stats */

	/**

	 * @sysfs_entry:

	 *

	 * For exposing information about this buffer in sysfs. See also

	 * `DMA-BUF statistics`_ for the uapi this enables.

	 */

	struct dma_buf_sysfs_entry {

		struct kobject kobj;

		struct dma_buf *dmabuf;



		/**

		 * @sysfs_entry.attachment_uid:

		 *

		 * This is protected by the dma_resv_lock() on @resv and is

		 * incremented on each attach.

		 */

		unsigned int attachment_uid;

		struct kset *attach_stats_kset;

	} *sysfs_entry;