Commit d6abed2a authored by Daniel Vetter's avatar Daniel Vetter

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
...@@ -289,30 +289,6 @@ struct dma_buf_ops { ...@@ -289,30 +289,6 @@ struct dma_buf_ops {
/** /**
* struct dma_buf - shared buffer object * 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 * This represents a shared buffer, created by calling dma_buf_export(). The
* userspace representation is a normal file descriptor, which can be created by * userspace representation is a normal file descriptor, which can be created by
...@@ -324,24 +300,100 @@ struct dma_buf_ops { ...@@ -324,24 +300,100 @@ struct dma_buf_ops {
* Device DMA access is handled by the separate &struct dma_buf_attachment. * Device DMA access is handled by the separate &struct dma_buf_attachment.
*/ */
struct dma_buf { struct dma_buf {
/**
* @size:
*
* Size of the buffer; invariant over the lifetime of the buffer.
*/
size_t size; 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; struct file *file;
/**
* @attachments:
*
* List of dma_buf_attachment that denotes all devices attached,
* protected by &dma_resv lock @resv.
*/
struct list_head attachments; struct list_head attachments;
/** @ops: dma_buf_ops associated with this buffer object. */
const struct dma_buf_ops *ops; 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; struct mutex lock;
/**
* @vmapping_counter:
*
* Used internally to refcnt the vmaps returned by dma_buf_vmap().
* Protected by @lock.
*/
unsigned vmapping_counter; unsigned vmapping_counter;
/**
* @vmap_ptr:
* The current vmap ptr if @vmapping_counter > 0. Protected by @lock.
*/
struct dma_buf_map vmap_ptr; 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; 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; const char *name;
/** @name_lock: Spinlock to protect name acces for read access. */
spinlock_t name_lock; spinlock_t name_lock;
/**
* @owner:
*
* Pointer to exporter module; used for refcounting when exporter is a
* kernel module.
*/
struct module *owner; struct module *owner;
/** @list_node: node for dma_buf accounting and debugging. */
struct list_head list_node; struct list_head list_node;
/** @priv: exporter specific private data for this buffer object. */
void *priv; void *priv;
/**
* @resv:
*
* Reservation object linked to this dma-buf.
*/
struct dma_resv *resv; struct dma_resv *resv;
/* poll support */ /** @poll: for userspace poll support */
wait_queue_head_t poll; 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_buf_poll_cb_t {
struct dma_fence_cb cb; struct dma_fence_cb cb;
wait_queue_head_t *poll; wait_queue_head_t *poll;
...@@ -349,10 +401,22 @@ struct dma_buf { ...@@ -349,10 +401,22 @@ struct dma_buf {
__poll_t active; __poll_t active;
} cb_excl, cb_shared; } cb_excl, cb_shared;
#ifdef CONFIG_DMABUF_SYSFS_STATS #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 dma_buf_sysfs_entry {
struct kobject kobj; struct kobject kobj;
struct dma_buf *dmabuf; 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; unsigned int attachment_uid;
struct kset *attach_stats_kset; struct kset *attach_stats_kset;
} *sysfs_entry; } *sysfs_entry;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment