On Tue, Jun 22, 2021 at 12:55 PM Daniel Vetter <daniel.vetter@xxxxxxxx> wrote:
>
> Also review & update everything while we're at it.
>
> This is prep work to smash a ton of stuff into the kerneldoc for
> @resv.
>
> Signed-off-by: Daniel Vetter <daniel.vetter@xxxxxxxxx>
> Cc: Sumit Semwal <sumit.semwal@xxxxxxxxxx>
> Cc: "Christian König" <christian.koenig@xxxxxxx>
> Cc: Alex Deucher <alexander.deucher@xxxxxxx>
> Cc: Daniel Vetter <daniel.vetter@xxxxxxxx>
> Cc: Dave Airlie <airlied@xxxxxxxxxx>
> Cc: Nirmoy Das <nirmoy.das@xxxxxxx>
> Cc: Deepak R Varma <mh12gx2825@xxxxxxxxx>
> Cc: Chen Li <chenli@xxxxxxxxxxxxx>
> Cc: Kevin Wang <kevin1.wang@xxxxxxx>
> Cc: linux-media@xxxxxxxxxxxxxxx
> Cc: linaro-mm-sig@xxxxxxxxxxxxxxxx
> ---
> include/linux/dma-buf.h | 107 +++++++++++++++++++++++++++++++---------
> 1 file changed, 83 insertions(+), 24 deletions(-)
>
> diff --git a/include/linux/dma-buf.h b/include/linux/dma-buf.h
> index 92eec38a03aa..6d18b9e448b9 100644
> --- a/include/linux/dma-buf.h
> +++ b/include/linux/dma-buf.h
> @@ -289,28 +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.
> *
> @@ -324,24 +302,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. */
For consistency you may want to format this like:
/**
* @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.
> + */
Same comment as above.
> 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. */
and here.
> struct list_head list_node;
> +
> + /** @priv: exporter specific private data for this buffer object. */
and here.
> void *priv;
> +
> + /**
> + * @resv:
> + *
> + * Reservation object linked to this dma-buf.
> + */
> struct dma_resv *resv;
>
> - /* poll support */
> + /** @poll: for userspace poll support */
here.
> wait_queue_head_t poll;
>
> + /** @cb_excl: for userspace poll support */
> + /** @cb_shared: for userspace poll support */
Here.
Either way,
Reviewed-by: Alex Deucher <alexander.deucher@xxxxxxx>
> struct dma_buf_poll_cb_t {
> struct dma_fence_cb cb;
> wait_queue_head_t *poll;
> @@ -349,7 +403,12 @@ 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;
> --
> 2.32.0.rc2
>
