From: Jason Ekstrand <jason@jlekstrand.net> To: dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org Cc: "Daniel Vetter" <daniel.vetter@ffwll.ch>, "Christian König" <christian.koenig@amd.com>, "Jason Ekstrand" <jason@jlekstrand.net> Subject: [PATCH 3/6] dma-buf: Document DMA_BUF_IOCTL_SYNC (v2) Date: Thu, 10 Jun 2021 16:14:42 -0500 [thread overview] Message-ID: <20210610211442.643307-1-jason@jlekstrand.net> (raw) In-Reply-To: <20210610210925.642582-4-jason@jlekstrand.net> 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. 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; }; -- 2.31.1
WARNING: multiple messages have this Message-ID (diff)
From: Jason Ekstrand <jason@jlekstrand.net> To: dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org Cc: "Daniel Vetter" <daniel.vetter@ffwll.ch>, "Christian König" <christian.koenig@amd.com>, "Sumit Semwal" <sumit.semwal@linaro.org> Subject: [Intel-gfx] [PATCH 3/6] dma-buf: Document DMA_BUF_IOCTL_SYNC (v2) Date: Thu, 10 Jun 2021 16:14:42 -0500 [thread overview] Message-ID: <20210610211442.643307-1-jason@jlekstrand.net> (raw) In-Reply-To: <20210610210925.642582-4-jason@jlekstrand.net> 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. 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; }; -- 2.31.1 _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
next prev parent reply other threads:[~2021-06-10 21:14 UTC|newest] Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-06-10 21:09 [PATCH 0/6] dma-buf: Add an API for exporting sync files (v12) Jason Ekstrand 2021-06-10 21:09 ` [PATCH 1/6] dma-buf: Add dma_fence_array_for_each (v2) Jason Ekstrand 2021-06-10 21:09 ` [PATCH 2/6] dma-buf: Add dma_resv_get_singleton (v6) Jason Ekstrand 2021-06-11 7:11 ` Christian König 2021-06-10 21:09 ` [PATCH 3/6] dma-buf: Document DMA_BUF_IOCTL_SYNC (v2) Jason Ekstrand 2021-06-10 21:14 ` Jason Ekstrand [this message] 2021-06-10 21:14 ` [Intel-gfx] " Jason Ekstrand 2021-06-15 7:10 ` Pekka Paalanen 2021-06-15 7:10 ` [Intel-gfx] " Pekka Paalanen 2021-06-11 7:24 ` Christian König 2021-06-10 21:09 ` [PATCH 4/6] dma-buf: Add an API for exporting sync files (v12) Jason Ekstrand 2021-06-13 18:26 ` Jason Ekstrand 2021-10-20 20:31 ` Simon Ser 2021-06-10 21:09 ` [PATCH 5/6] RFC: dma-buf: Add an extra fence to dma_resv_get_singleton_unlocked Jason Ekstrand 2021-06-11 7:44 ` Christian König 2021-06-10 21:09 ` [PATCH 6/6] RFC: dma-buf: Add an API for importing sync files (v7) Jason Ekstrand 2022-03-22 15:02 ` msizanoen 2021-06-15 8:41 ` [Mesa-dev] [PATCH 0/6] dma-buf: Add an API for exporting sync files (v12) Christian König 2021-06-16 18:30 ` Jason Ekstrand 2021-06-17 7:37 ` Christian König 2021-06-17 19:58 ` Daniel Vetter 2021-06-18 9:15 ` Christian König 2021-06-18 13:54 ` Jason Ekstrand 2021-06-18 14:31 ` Daniel Vetter 2021-06-18 14:42 ` Christian König 2021-06-18 15:17 ` Daniel Vetter 2021-06-18 16:42 ` Christian König 2021-06-18 17:20 ` Daniel Vetter 2021-06-18 18:01 ` Christian König 2021-06-18 18:45 ` Daniel Vetter 2021-06-21 10:16 ` Christian König 2021-06-21 13:57 ` Daniel Vetter 2021-06-18 18:20 ` Daniel Stone 2021-06-18 18:44 ` Christian König
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20210610211442.643307-1-jason@jlekstrand.net \ --to=jason@jlekstrand.net \ --cc=christian.koenig@amd.com \ --cc=daniel.vetter@ffwll.ch \ --cc=dri-devel@lists.freedesktop.org \ --cc=intel-gfx@lists.freedesktop.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.