Hi Paul.
On 6/7/24 12:44 AM, Paul Cercueil wrote:
Hi Randy,
Le jeudi 06 juin 2024 à 10:32 -0700, Randy Dunlap a écrit :
Hi,
On 6/5/24 4:08 AM, Paul Cercueil wrote:
Document the new DMABUF based API.
Signed-off-by: Paul Cercueil paul@crapouillou.net Signed-off-by: Nuno Sa nuno.sa@analog.com
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.
v8: Renamed dmabuf_api.rst -> iio_dmabuf_api.rst, and updated index.rst whose format changed in iio/togreg.
Documentation/iio/iio_dmabuf_api.rst | 54 ++++++++++++++++++++++++++++ Documentation/iio/index.rst | 1 + 2 files changed, 55 insertions(+) create mode 100644 Documentation/iio/iio_dmabuf_api.rst
diff --git a/Documentation/iio/iio_dmabuf_api.rst b/Documentation/iio/iio_dmabuf_api.rst new file mode 100644 index 000000000000..1cd6cd51a582 --- /dev/null +++ b/Documentation/iio/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
I would say/write: to an IIO buffer,
Right.
+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)``
(int fd) ?
Yes, I can change that. Although it's very obvious what the "int" is for, given the text above.
Yes. This is just to be consistent with the text below:
+ ``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)``
+ 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)``
ditto.
+ 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.
thanks.
Cheers, -Paul
thanks.