From: Paul Cercueil <paul@crapouillou.net> To: "Jonathan Cameron" <jic23@kernel.org>, "Jonathan Corbet" <corbet@lwn.net>, "Lars-Peter Clausen" <lars@metafoo.de>, "Vinod Koul" <vkoul@kernel.org>, "Sumit Semwal" <sumit.semwal@linaro.org>, "Christian König" <christian.koenig@amd.com> Cc: Daniel Vetter <daniel@ffwll.ch>, Nuno Sa <nuno.sa@analog.com>, Michael Hennerich <Michael.Hennerich@analog.com>, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, dmaengine@vger.kernel.org, linux-iio@vger.kernel.org, linux-media@vger.kernel.org, dri-devel@lists.freedesktop.org, linaro-mm-sig@lists.linaro.org, Paul Cercueil <paul@crapouillou.net> Subject: [PATCH v6 6/6] Documentation: iio: Document high-speed DMABUF based API Date: Mon, 29 Jan 2024 18:02:01 +0100 [thread overview] Message-ID: <20240129170201.133785-7-paul@crapouillou.net> (raw) In-Reply-To: <20240129170201.133785-1-paul@crapouillou.net> Document the new DMABUF based API. Signed-off-by: Paul Cercueil <paul@crapouillou.net> --- v2: - Explicitly state that the new interface is optional and is not implemented by all drivers. - The IOCTLs can now only be called on the buffer FD returned by IIO_BUFFER_GET_FD_IOCTL. - Move the page up a bit in the index since it is core stuff and not driver-specific. v3: Update the documentation to reflect the new API. v5: Use description lists for the documentation of the three new IOCTLs instead of abusing subsections. --- Documentation/iio/dmabuf_api.rst | 54 ++++++++++++++++++++++++++++++++ Documentation/iio/index.rst | 2 ++ 2 files changed, 56 insertions(+) create mode 100644 Documentation/iio/dmabuf_api.rst diff --git a/Documentation/iio/dmabuf_api.rst b/Documentation/iio/dmabuf_api.rst new file mode 100644 index 000000000000..1cd6cd51a582 --- /dev/null +++ b/Documentation/iio/dmabuf_api.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +High-speed DMABUF interface for IIO +=================================== + +1. Overview +=========== + +The Industrial I/O subsystem supports access to buffers through a +file-based interface, with read() and write() access calls through the +IIO device's dev node. + +It additionally supports a DMABUF based interface, where the userspace +can attach DMABUF objects (externally created) to a IIO buffer, and +subsequently use them for data transfers. + +A userspace application can then use this interface to share DMABUF +objects between several interfaces, allowing it to transfer data in a +zero-copy fashion, for instance between IIO and the USB stack. + +The userspace application can also memory-map the DMABUF objects, and +access the sample data directly. The advantage of doing this vs. the +read() interface is that it avoids an extra copy of the data between the +kernel and userspace. This is particularly useful for high-speed devices +which produce several megabytes or even gigabytes of data per second. +It does however increase the userspace-kernelspace synchronization +overhead, as the DMA_BUF_SYNC_START and DMA_BUF_SYNC_END IOCTLs have to +be used for data integrity. + +2. User API +=========== + +As part of this interface, three new IOCTLs have been added. These three +IOCTLs have to be performed on the IIO buffer's file descriptor, +obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl. + + ``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int)`` + Attach the DMABUF object, identified by its file descriptor, to the + IIO buffer. Returns zero on success, and a negative errno value on + error. + + ``IIO_BUFFER_DMABUF_DETACH_IOCTL(int)`` + Detach the given DMABUF object, identified by its file descriptor, + from the IIO buffer. Returns zero on success, and a negative errno + value on error. + + Note that closing the IIO buffer's file descriptor will + automatically detach all previously attached DMABUF objects. + + ``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)`` + Enqueue a previously attached DMABUF object to the buffer queue. + Enqueued DMABUFs will be read from (if output buffer) or written to + (if input buffer) as long as the buffer is enabled. diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 1b7292c58cd0..3eae8fcb1938 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -9,6 +9,8 @@ Industrial I/O iio_configfs + dmabuf_api + ep93xx_adc bno055 -- 2.43.0
WARNING: multiple messages have this Message-ID (diff)
From: Paul Cercueil <paul@crapouillou.net> To: "Jonathan Cameron" <jic23@kernel.org>, "Jonathan Corbet" <corbet@lwn.net>, "Lars-Peter Clausen" <lars@metafoo.de>, "Vinod Koul" <vkoul@kernel.org>, "Sumit Semwal" <sumit.semwal@linaro.org>, "Christian König" <christian.koenig@amd.com> Cc: Paul Cercueil <paul@crapouillou.net>, Michael Hennerich <Michael.Hennerich@analog.com>, linux-doc@vger.kernel.org, linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, Nuno Sa <nuno.sa@analog.com>, linaro-mm-sig@lists.linaro.org, Daniel Vetter <daniel@ffwll.ch>, dmaengine@vger.kernel.org, linux-media@vger.kernel.org Subject: [PATCH v6 6/6] Documentation: iio: Document high-speed DMABUF based API Date: Mon, 29 Jan 2024 18:02:01 +0100 [thread overview] Message-ID: <20240129170201.133785-7-paul@crapouillou.net> (raw) In-Reply-To: <20240129170201.133785-1-paul@crapouillou.net> Document the new DMABUF based API. Signed-off-by: Paul Cercueil <paul@crapouillou.net> --- v2: - Explicitly state that the new interface is optional and is not implemented by all drivers. - The IOCTLs can now only be called on the buffer FD returned by IIO_BUFFER_GET_FD_IOCTL. - Move the page up a bit in the index since it is core stuff and not driver-specific. v3: Update the documentation to reflect the new API. v5: Use description lists for the documentation of the three new IOCTLs instead of abusing subsections. --- Documentation/iio/dmabuf_api.rst | 54 ++++++++++++++++++++++++++++++++ Documentation/iio/index.rst | 2 ++ 2 files changed, 56 insertions(+) create mode 100644 Documentation/iio/dmabuf_api.rst diff --git a/Documentation/iio/dmabuf_api.rst b/Documentation/iio/dmabuf_api.rst new file mode 100644 index 000000000000..1cd6cd51a582 --- /dev/null +++ b/Documentation/iio/dmabuf_api.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=================================== +High-speed DMABUF interface for IIO +=================================== + +1. Overview +=========== + +The Industrial I/O subsystem supports access to buffers through a +file-based interface, with read() and write() access calls through the +IIO device's dev node. + +It additionally supports a DMABUF based interface, where the userspace +can attach DMABUF objects (externally created) to a IIO buffer, and +subsequently use them for data transfers. + +A userspace application can then use this interface to share DMABUF +objects between several interfaces, allowing it to transfer data in a +zero-copy fashion, for instance between IIO and the USB stack. + +The userspace application can also memory-map the DMABUF objects, and +access the sample data directly. The advantage of doing this vs. the +read() interface is that it avoids an extra copy of the data between the +kernel and userspace. This is particularly useful for high-speed devices +which produce several megabytes or even gigabytes of data per second. +It does however increase the userspace-kernelspace synchronization +overhead, as the DMA_BUF_SYNC_START and DMA_BUF_SYNC_END IOCTLs have to +be used for data integrity. + +2. User API +=========== + +As part of this interface, three new IOCTLs have been added. These three +IOCTLs have to be performed on the IIO buffer's file descriptor, +obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl. + + ``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int)`` + Attach the DMABUF object, identified by its file descriptor, to the + IIO buffer. Returns zero on success, and a negative errno value on + error. + + ``IIO_BUFFER_DMABUF_DETACH_IOCTL(int)`` + Detach the given DMABUF object, identified by its file descriptor, + from the IIO buffer. Returns zero on success, and a negative errno + value on error. + + Note that closing the IIO buffer's file descriptor will + automatically detach all previously attached DMABUF objects. + + ``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)`` + Enqueue a previously attached DMABUF object to the buffer queue. + Enqueued DMABUFs will be read from (if output buffer) or written to + (if input buffer) as long as the buffer is enabled. diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 1b7292c58cd0..3eae8fcb1938 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -9,6 +9,8 @@ Industrial I/O iio_configfs + dmabuf_api + ep93xx_adc bno055 -- 2.43.0
next prev parent reply other threads:[~2024-01-29 17:03 UTC|newest] Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top 2024-01-29 17:01 [PATCH v6 0/6] iio: new DMABUF based API, v6 Paul Cercueil 2024-01-29 17:01 ` Paul Cercueil 2024-01-29 17:01 ` [PATCH v6 1/6] dmaengine: Add API function dmaengine_prep_slave_dma_vec() Paul Cercueil 2024-01-29 17:01 ` Paul Cercueil 2024-01-30 16:08 ` Vinod Koul 2024-01-30 16:08 ` Vinod Koul 2024-01-30 17:23 ` Paul Cercueil 2024-01-30 17:23 ` Paul Cercueil 2024-01-29 17:01 ` [PATCH v6 2/6] dmaengine: dma-axi-dmac: Implement device_prep_slave_dma_vec Paul Cercueil 2024-01-29 17:01 ` Paul Cercueil 2024-01-29 17:01 ` [PATCH v6 3/6] iio: core: Add new DMABUF interface infrastructure Paul Cercueil 2024-01-29 17:01 ` Paul Cercueil 2024-01-29 17:01 ` [PATCH v6 4/6] iio: buffer-dma: Enable support for DMABUFs Paul Cercueil 2024-01-29 17:01 ` Paul Cercueil 2024-01-29 17:02 ` [PATCH v6 5/6] iio: buffer-dmaengine: Support new DMABUF based userspace API Paul Cercueil 2024-01-29 17:02 ` Paul Cercueil 2024-01-29 17:02 ` Paul Cercueil [this message] 2024-01-29 17:02 ` [PATCH v6 6/6] Documentation: iio: Document high-speed DMABUF based API Paul Cercueil
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=20240129170201.133785-7-paul@crapouillou.net \ --to=paul@crapouillou.net \ --cc=Michael.Hennerich@analog.com \ --cc=christian.koenig@amd.com \ --cc=corbet@lwn.net \ --cc=daniel@ffwll.ch \ --cc=dmaengine@vger.kernel.org \ --cc=dri-devel@lists.freedesktop.org \ --cc=jic23@kernel.org \ --cc=lars@metafoo.de \ --cc=linaro-mm-sig@lists.linaro.org \ --cc=linux-doc@vger.kernel.org \ --cc=linux-iio@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-media@vger.kernel.org \ --cc=nuno.sa@analog.com \ --cc=sumit.semwal@linaro.org \ --cc=vkoul@kernel.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.