dma-buf: Final bits of doc polish

                    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/

   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

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. 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

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

	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;