diff options
author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2016-12-09 22:50:55 +0100 |
---|---|---|
committer | Sumit Semwal <sumit.semwal@linaro.org> | 2016-12-13 17:54:28 +0530 |
commit | e7e21c72b178e963f3c990cb839d86f568999916 (patch) | |
tree | 80698d8bc3a5c3952e498ca0ef3e764c6ccff3c9 /Documentation/driver-api | |
parent | 0959a1683d78270bab6381d498707fb8655ae11c (diff) | |
download | linux-e7e21c72b178e963f3c990cb839d86f568999916.tar.gz linux-e7e21c72b178e963f3c990cb839d86f568999916.tar.bz2 linux-e7e21c72b178e963f3c990cb839d86f568999916.zip |
dma-buf: Final bits of doc polish
- 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@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Sumit Semwal <sumit.semwal@linaro.org>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
Link: http://patchwork.freedesktop.org/patch/msgid/20161209215055.3492-1-daniel.vetter@ffwll.ch
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r-- | Documentation/driver-api/dma-buf.rst | 48 |
1 files changed, 48 insertions, 0 deletions
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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |