linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Gerd Hoffmann <kraxel@redhat.com>
To: dri-devel@lists.freedesktop.org
Cc: laurent.pinchart@ideasonboard.com, daniel@ffwll.ch,
	Gerd Hoffmann <kraxel@redhat.com>,
	Sumit Semwal <sumit.semwal@linaro.org>,
	Jonathan Corbet <corbet@lwn.net>,
	linux-media@vger.kernel.org (open list:DMA BUFFER SHARING
	FRAMEWORK),
	linaro-mm-sig@lists.linaro.org (moderated list:DMA BUFFER
	SHARING FRAMEWORK),
	linux-doc@vger.kernel.org (open list:DOCUMENTATION),
	linux-kernel@vger.kernel.org (open list)
Subject: [PATCH v2 13/13] udmabuf: add documentation
Date: Tue, 11 Sep 2018 15:42:16 +0200	[thread overview]
Message-ID: <20180911134216.9760-14-kraxel@redhat.com> (raw)
In-Reply-To: <20180911134216.9760-1-kraxel@redhat.com>

Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 include/uapi/linux/udmabuf.h         | 50 +++++++++++++++++++++++++++++++++---
 Documentation/driver-api/dma-buf.rst |  8 ++++++
 2 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/include/uapi/linux/udmabuf.h b/include/uapi/linux/udmabuf.h
index 46b6532ed8..f30b37cb5c 100644
--- a/include/uapi/linux/udmabuf.h
+++ b/include/uapi/linux/udmabuf.h
@@ -5,8 +5,38 @@
 #include <linux/types.h>
 #include <linux/ioctl.h>
 
+/**
+ * DOC: udmabuf
+ *
+ * udmabuf is a device driver which allows userspace create dmabufs.
+ * The memory used for these dmabufs must be backed by memfd.  The
+ * memfd must have F_SEAL_SHRINK and it must not have F_SEAL_WRITE.
+ *
+ * The driver has two ioctls, one to create a dmabuf from a single
+ * memory block and one to create a dmabuf from a list of memory
+ * blocks.
+ *
+ * UDMABUF_CREATE - _IOW('u', 0x42, udmabuf_create)
+ *
+ * UDMABUF_CREATE_LIST - _IOW('u', 0x43, udmabuf_create_list)
+ */
+
+#define UDMABUF_CREATE       _IOW('u', 0x42, struct udmabuf_create)
+#define UDMABUF_CREATE_LIST  _IOW('u', 0x43, struct udmabuf_create_list)
+
 #define UDMABUF_FLAGS_CLOEXEC	0x01
 
+/**
+ * struct udmabuf_create - create a dmabuf from a single memory block.
+ *
+ * @memfd: The file handle.
+ * @offset: Start of the buffer (from memfd start).
+ * Must be page aligned.
+ * @size: Size of the buffer.  Must be rounded to page size.
+ *
+ * flags:
+ * UDMABUF_FLAGS_CLOEXEC: set CLOEXEC flag for the dmabuf.
+ */
 struct udmabuf_create {
 	__u32 memfd;
 	__u32 flags;
@@ -14,6 +44,14 @@ struct udmabuf_create {
 	__u64 size;
 };
 
+/**
+ * struct udmabuf_create_item - one memory block list item.
+ *
+ * @memfd: The file handle.
+ * @offset: Start of the buffer (from memfd start).
+ * Must be page aligned.
+ * @size: Size of the buffer.  Must be rounded to page size.
+ */
 struct udmabuf_create_item {
 	__u32 memfd;
 	__u32 __pad;
@@ -21,13 +59,19 @@ struct udmabuf_create_item {
 	__u64 size;
 };
 
+/**
+ * struct udmabuf_create_list - create a dmabuf from a memory block list.
+ *
+ * @count: The number of list elements.
+ * @list: The memory block list
+ *
+ * flags:
+ * UDMABUF_FLAGS_CLOEXEC: set CLOEXEC flag for the dmabuf.
+ */
 struct udmabuf_create_list {
 	__u32 flags;
 	__u32 count;
 	struct udmabuf_create_item list[];
 };
 
-#define UDMABUF_CREATE       _IOW('u', 0x42, struct udmabuf_create)
-#define UDMABUF_CREATE_LIST  _IOW('u', 0x43, struct udmabuf_create_list)
-
 #endif /* _UAPI_LINUX_UDMABUF_H */
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
index b541e97c7a..1f62c30a14 100644
--- a/Documentation/driver-api/dma-buf.rst
+++ b/Documentation/driver-api/dma-buf.rst
@@ -166,3 +166,11 @@ DMA Fence uABI/Sync File
 .. kernel-doc:: include/linux/sync_file.h
    :internal:
 
+Userspace DMA Buffer driver
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: include/uapi/linux/udmabuf.h
+   :doc: udmabuf
+
+.. kernel-doc:: include/uapi/linux/udmabuf.h
+   :internal:
-- 
2.9.3


  parent reply	other threads:[~2018-09-11 13:42 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <20180911134216.9760-1-kraxel@redhat.com>
2018-09-11 13:42 ` [PATCH v2 01/13] udmabuf: sort headers, drop uapi/ path prefix Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 02/13] udmabuf: improve map_udmabuf error handling Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 03/13] udmabuf: use pgoff_t for pagecount Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 04/13] udmabuf: constify udmabuf_ops Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 05/13] udmabuf: constify udmabuf_create args Gerd Hoffmann
2018-09-11 14:53   ` Laurent Pinchart
2018-09-11 13:42 ` [PATCH v2 06/13] udmabuf: add MEMFD_CREATE dependency Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 07/13] udmabuf: rework limits Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 08/13] udmabuf: improve udmabuf_create error handling Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 09/13] udmabuf: use EBADFD in case we didn't got a memfd Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 10/13] udmabuf: use ENOTTY for invalid ioctls Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 11/13] udmabuf: drop WARN_ON() check Gerd Hoffmann
2018-09-11 15:07   ` Laurent Pinchart
2018-09-12  6:10     ` Gerd Hoffmann
2018-09-11 13:42 ` [PATCH v2 12/13] udmabuf: use sizeof(variable) instead of sizeof(type) Gerd Hoffmann
2018-09-11 15:07   ` Laurent Pinchart
2018-09-11 13:42 ` Gerd Hoffmann [this message]
2018-09-11 15:40   ` [PATCH v2 13/13] udmabuf: add documentation Randy Dunlap

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20180911134216.9760-14-kraxel@redhat.com \
    --to=kraxel@redhat.com \
    --cc=corbet@lwn.net \
    --cc=daniel@ffwll.ch \
    --cc=dri-devel@lists.freedesktop.org \
    --cc=laurent.pinchart@ideasonboard.com \
    --cc=linaro-mm-sig@lists.linaro.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-media@vger.kernel.org \
    --cc=sumit.semwal@linaro.org \
    --subject='Re: [PATCH v2 13/13] udmabuf: add documentation' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).