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@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. > 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. -- #Randy https://people.kernel.org/tglx/notes-about-netiquette https://subspace.kernel.org/etiquette.html
