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
This commit is contained in:
Daniel Vetter
Sumit Semwal
parent
0959a1683d
commit
e7e21c72b1
@ -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/
|
||||
@ -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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user