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@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, 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
