[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <14d802e84cbb8d3c9610386908706f264af34726.camel@crapouillou.net>
Date: Fri, 07 Jun 2024 09:44:01 +0200
From: Paul Cercueil <paul@...pouillou.net>
To: Randy Dunlap <rdunlap@...radead.org>, Jonathan Cameron
<jic23@...nel.org>, Lars-Peter Clausen <lars@...afoo.de>, Vinod Koul
<vkoul@...nel.org>, Sumit Semwal <sumit.semwal@...aro.org>, Christian
König <christian.koenig@....com>
Cc: Jonathan Corbet <corbet@....net>, Nuno Sa <nuno.sa@...log.com>,
linux-iio@...r.kernel.org, linux-doc@...r.kernel.org,
linux-kernel@...r.kernel.org, dmaengine@...r.kernel.org,
linux-media@...r.kernel.org, dri-devel@...ts.freedesktop.org,
linaro-mm-sig@...ts.linaro.org
Subject: Re: [PATCH v10 6/6] Documentation: iio: Document high-speed DMABUF
based API
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@...pouillou.net>
> > Signed-off-by: Nuno Sa <nuno.sa@...log.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.
>
> > + 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
Powered by blists - more mailing lists