[Intel-gfx] [PATCH] dma-buf: Final bits of doc polish
Daniel Vetter
daniel.vetter at ffwll.ch
Fri Dec 9 21:50:55 UTC 2016
- Put all the remaing bits of the old doc into suitable places in the
new sphinx world.
- Also document the poll support, we forgot to do that.
- Delete dma-buf-sharing.txt.
v2: Don't forget to update MAINTAINERS.
Cc: linux-doc at vger.kernel.org
Cc: Jonathan Corbet <corbet at lwn.net>
Cc: Sumit Semwal <sumit.semwal at linaro.org>
Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
---
Documentation/dma-buf-sharing.txt | 47 -----------------------------------
Documentation/driver-api/dma-buf.rst | 48 ++++++++++++++++++++++++++++++++++++
MAINTAINERS | 2 +-
drivers/dma-buf/dma-buf.c | 22 +++++++++++++++++
4 files changed, 71 insertions(+), 48 deletions(-)
delete mode 100644 Documentation/dma-buf-sharing.txt
diff --git a/Documentation/dma-buf-sharing.txt b/Documentation/dma-buf-sharing.txt
deleted file mode 100644
index 74c99edb7976..000000000000
--- a/Documentation/dma-buf-sharing.txt
+++ /dev/null
@@ -1,47 +0,0 @@
- DMA Buffer Sharing API Guide
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- Sumit Semwal
- <sumit dot semwal at linaro dot org>
- <sumit dot semwal at ti dot com>
-
-
-Other Interfaces Exposed to Userspace on the dma-buf FD
-------------------------------------------------------
-
-- Since kernel 3.12 the dma-buf FD supports the llseek system call, but only
- with offset=0 and whence=SEEK_END|SEEK_SET. SEEK_SET is supported to allow
- the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other
- llseek operation will report -EINVAL.
-
- If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all
- cases. Userspace can use this to detect support for discovering the dma-buf
- size using llseek.
-
-Miscellaneous notes
--------------------
-
-- Any exporters or users of the dma-buf buffer sharing framework must have
- a 'select DMA_SHARED_BUFFER' in their respective Kconfigs.
-
-- In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set
- on the file descriptor. This is not just a resource leak, but a
- potential security hole. It could give the newly exec'd application
- access to buffers, via the leaked fd, to which it should otherwise
- not be permitted access.
-
- The problem with doing this via a separate fcntl() call, versus doing it
- atomically when the fd is created, is that this is inherently racy in a
- multi-threaded app[3]. The issue is made worse when it is library code
- opening/creating the file descriptor, as the application may not even be
- aware of the fd's.
-
- To avoid this problem, userspace must have a way to request O_CLOEXEC
- flag be set when the dma-buf fd is created. So any API provided by
- the exporting driver to create a dmabuf fd must provide a way to let
- userspace control setting of O_CLOEXEC flag passed in to dma_buf_fd().
-
-References:
-[1] struct dma_buf_ops in include/linux/dma-buf.h
-[2] All interfaces mentioned above defined in include/linux/dma-buf.h
-[3] https://lwn.net/Articles/236486/
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
index 92e417035e16..31671b469627 100644
--- a/Documentation/driver-api/dma-buf.rst
+++ b/Documentation/driver-api/dma-buf.rst
@@ -46,6 +46,48 @@ The buffer-user
same area of memory. This interface is provided by :c:type:`struct
dma_buf_attachment <dma_buf_attachment>`.
+Any exporters or users of the dma-buf buffer sharing framework must have a
+'select DMA_SHARED_BUFFER' in their respective Kconfigs.
+
+Userspace Interface Notes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mostly a DMA buffer file descriptor is simply an opaque object for userspace,
+and hence the generic interface exposed is very minimal. There's a few things to
+consider though:
+
+- Since kernel 3.12 the dma-buf FD supports the llseek system call, but only
+ with offset=0 and whence=SEEK_END|SEEK_SET. SEEK_SET is supported to allow
+ the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other
+ llseek operation will report -EINVAL.
+
+ If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all
+ cases. Userspace can use this to detect support for discovering the dma-buf
+ size using llseek.
+
+- In order to avoid fd leaks on exec, the FD_CLOEXEC flag must be set
+ on the file descriptor. This is not just a resource leak, but a
+ potential security hole. It could give the newly exec'd application
+ access to buffers, via the leaked fd, to which it should otherwise
+ not be permitted access.
+
+ The problem with doing this via a separate fcntl() call, versus doing it
+ atomically when the fd is created, is that this is inherently racy in a
+ multi-threaded app[3]. The issue is made worse when it is library code
+ opening/creating the file descriptor, as the application may not even be
+ aware of the fd's.
+
+ To avoid this problem, userspace must have a way to request O_CLOEXEC
+ flag be set when the dma-buf fd is created. So any API provided by
+ the exporting driver to create a dmabuf fd must provide a way to let
+ userspace control setting of O_CLOEXEC flag passed in to dma_buf_fd().
+
+- Memory mapping the contents of the DMA buffer is also supported. See the
+ discussion below on `CPU Access to DMA Buffer Objects`_ for the full details.
+
+- The DMA buffer FD is also pollable, see `Fence Poll Support`_ below for
+ details.
+
Basic Operation and Device DMA Access
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -58,6 +100,12 @@ CPU Access to DMA Buffer Objects
.. kernel-doc:: drivers/dma-buf/dma-buf.c
:doc: cpu access
+Fence Poll Support
+~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/dma-buf.c
+ :doc: fence polling
+
Kernel Functions and Structures Reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/MAINTAINERS b/MAINTAINERS
index 1a7a773114aa..d19872eed4de 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3917,7 +3917,7 @@ F: drivers/dma-buf/
F: include/linux/dma-buf*
F: include/linux/reservation.h
F: include/linux/*fence.h
-F: Documentation/dma-buf-sharing.txt
+F: Documentation/driver-api/dma-buf.rst
T: git git://anongit.freedesktop.org/drm/drm-misc
SYNC FILE FRAMEWORK
diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c
index 0933c01e6d8c..0775fc947d73 100644
--- a/drivers/dma-buf/dma-buf.c
+++ b/drivers/dma-buf/dma-buf.c
@@ -124,6 +124,28 @@ static loff_t dma_buf_llseek(struct file *file, loff_t offset, int whence)
return base + offset;
}
+/**
+ * DOC: fence polling
+ *
+ * To support cross-device and cross-driver synchronization of buffer access
+ * implicit fences (represented internally in the kernel with struct &fence) can
+ * be attached to a &dma_buf. The glue for that and a few related things are
+ * provided in the &reservation_object structure.
+ *
+ * Userspace can query the state of these implicitly tracked fences using poll()
+ * and related system calls:
+ *
+ * - Checking for POLLIN, i.e. read access, can be use to query the state of the
+ * most recent write or exclusive fence.
+ *
+ * - Checking for POLLOUT, i.e. write access, can be used to query the state of
+ * all attached fences, shared and exclusive ones.
+ *
+ * Note that this only signals the completion of the respective fences, i.e. the
+ * DMA transfers are complete. Cache flushing and any other necessary
+ * preparations before CPU access can begin still need to happen.
+ */
+
static void dma_buf_poll_cb(struct dma_fence *fence, struct dma_fence_cb *cb)
{
struct dma_buf_poll_cb_t *dcb = (struct dma_buf_poll_cb_t *)cb;
--
2.10.2
More information about the Intel-gfx
mailing list