dma-buf: Switch to inline kerneldoc

[linux-2.6-microblaze.git] / include / linux / dma-buf.h

diff --git a/include/linux/dma-buf.h b/include/linux/dma-buf.h
index 92eec38..81cebf4 100644 (file)
--- a/include/linux/dma-buf.h
+++ b/include/linux/dma-buf.h
@@ -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;