Re: [PATCH] dma-buf: Document DMA_BUF_IOCTL_SYNC (v3)

On Thu, Jun 17, 2021 at 02:42:58PM -0500, Jason Ekstrand 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

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: Jason Ekstrand jason@jlekstrand.net Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch Acked-by: Christian König christian.koenig@amd.com Acked-by: Pekka Paalanen pekka.paalanen@collabora.com Cc: Sumit Semwal sumit.semwal@linaro.org

Merged to drm-misc-next, thanks. -Daniel

---

Documentation/driver-api/dma-buf.rst | 8 +++++ include/uapi/linux/dma-buf.h | 50 +++++++++++++++++++++++++++- 2 files changed, 57 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..8e4a2ca0bcbf7 100644 --- a/include/uapi/linux/dma-buf.h +++ b/include/uapi/linux/dma-buf.h @@ -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;

};

-- 2.31.1