Commit 51f52547 authored by Jason Ekstrand's avatar Jason Ekstrand Committed by Daniel Vetter
Browse files

dma-buf: Document DMA_BUF_IOCTL_SYNC (v3) 



This adds a new "DMA Buffer ioctls" section to the dma-buf docs and adds
documentation for DMA_BUF_IOCTL_SYNC.

v2 (Daniel Vetter):
 - Fix a couple typos
 - Add commentary about synchronization with other devices
 - Use item list format for describing flags

v3 (Pekka Paalanen):
 - Clarify stalling requirements.
 - Be more clear that that DMA_BUF_IOCTL_SYNC with SINC_END has to be
   called before more GPU work happens.

Signed-off-by: default avatarJason Ekstrand <jason@jlekstrand.net>
Reviewed-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: default avatarChristian König <christian.koenig@amd.com>
Acked-by: default avatarPekka Paalanen <pekka.paalanen@collabora.com>
Cc: Sumit Semwal <sumit.semwal@linaro.org>
Signed-off-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20210617194258.579011-1-jason@jlekstrand.net
parent d35c97f6

Documentation/driver-api/dma-buf.rst

+8 −0
Original line number Diff line number Diff line
@@ -88,6 +88,9 @@ consider though: 
- The DMA buffer FD is also pollable, see `Implicit Fence Poll Support`_ below for

  details.



- The DMA buffer FD also supports a few dma-buf-specific ioctls, see

  `DMA Buffer ioctls`_ below for details.



Basic Operation and Device DMA Access

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -111,6 +114,11 @@ DMA-BUF statistics 
.. kernel-doc:: drivers/dma-buf/dma-buf-sysfs-stats.c

   :doc: overview



DMA Buffer ioctls

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



.. kernel-doc:: include/uapi/linux/dma-buf.h



Kernel Functions and Structures Reference

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

include/uapi/linux/dma-buf.h

+49 −1
Original line number Diff line number Diff line
@@ -22,8 +22,56 @@ 


#include <linux/types.h>



/* begin/end dma-buf functions used for userspace mmap. */

/**

 * struct dma_buf_sync - Synchronize with CPU access.

 *

 * When a DMA buffer is accessed from the CPU via mmap, it is not always

 * possible to guarantee coherency between the CPU-visible map and underlying

 * memory.  To manage coherency, DMA_BUF_IOCTL_SYNC must be used to bracket

 * any CPU access to give the kernel the chance to shuffle memory around if

 * needed.

 *

 * Prior to accessing the map, the client must call DMA_BUF_IOCTL_SYNC

 * with DMA_BUF_SYNC_START and the appropriate read/write flags.  Once the

 * access is complete, the client should call DMA_BUF_IOCTL_SYNC with

 * DMA_BUF_SYNC_END and the same read/write flags.

 *

 * The synchronization provided via DMA_BUF_IOCTL_SYNC only provides cache

 * coherency.  It does not prevent other processes or devices from

 * accessing the memory at the same time.  If synchronization with a GPU or

 * other device driver is required, it is the client's responsibility to

 * wait for buffer to be ready for reading or writing before calling this

 * ioctl with DMA_BUF_SYNC_START.  Likewise, the client must ensure that

 * follow-up work is not submitted to GPU or other device driver until

 * after this ioctl has been called with DMA_BUF_SYNC_END?

 *

 * If the driver or API with which the client is interacting uses implicit

 * synchronization, waiting for prior work to complete can be done via

 * poll() on the DMA buffer file descriptor.  If the driver or API requires

 * explicit synchronization, the client may have to wait on a sync_file or

 * other synchronization primitive outside the scope of the DMA buffer API.

 */

struct dma_buf_sync {

	/**

	 * @flags: Set of access flags

	 *

	 * DMA_BUF_SYNC_START:

	 *     Indicates the start of a map access session.

	 *

	 * DMA_BUF_SYNC_END:

	 *     Indicates the end of a map access session.

	 *

	 * DMA_BUF_SYNC_READ:

	 *     Indicates that the mapped DMA buffer will be read by the

	 *     client via the CPU map.

	 *

	 * DMA_BUF_SYNC_WRITE:

	 *     Indicates that the mapped DMA buffer will be written by the

	 *     client via the CPU map.

	 *

	 * DMA_BUF_SYNC_RW:

	 *     An alias for DMA_BUF_SYNC_READ | DMA_BUF_SYNC_WRITE.

	 */

	__u64 flags;

};