Re: [PATCH 3/6] dma-buf: Document DMA_BUF_IOCTL_SYNC (v2)

On Thu, 10 Jun 2021 16:14:42 -0500 Jason Ekstrand jason@jlekstrand.net wrote:

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

Signed-off-by: Jason Ekstrand jason@jlekstrand.net Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch Cc: Christian König christian.koenig@amd.com Cc: Sumit Semwal sumit.semwal@linaro.org

---

Documentation/driver-api/dma-buf.rst | 8 +++++ include/uapi/linux/dma-buf.h | 46 +++++++++++++++++++++++++++- 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 7f21425d9435a..0d4c13ec1a800 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -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

@@ -106,6 +109,11 @@ Implicit Fence Poll Support
.. kernel-doc:: drivers/dma-buf/dma-buf.c
   :doc: implicit fence polling

+DMA Buffer ioctls
+~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: include/uapi/linux/dma-buf.h
+
Kernel Functions and Structures Reference

diff --git a/include/uapi/linux/dma-buf.h b/include/uapi/linux/dma-buf.h index 7f30393b92c3b..1c131002fe1ee 100644 --- a/include/uapi/linux/dma-buf.h +++ b/include/uapi/linux/dma-buf.h @@ -22,8 +22,52 @@

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

Maybe that would be worthwhile to add?

Likewise, submit follow-up work to GPU et al. only after calling this ioctl with SYNC_END?

Anyway, looks nice to me.

Acked-by: Pekka Paalanen pekka.paalanen@collabora.com

Thanks, pq

If the driver or

• • API with which the client is interacting uses implicit synchronization,
• • this 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;

};