Hi,
On 6/5/24 4:08 AM, Paul Cercueil wrote:
> Document the new DMABUF based API.
>
> Signed-off-by: Paul Cercueil <paul@xxxxxxxxxxxxxxx>
> Signed-off-by: Nuno Sa <nuno.sa@xxxxxxxxxx>
>
> ---
> 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,
> +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)
?
> + 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.
--
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html
