| Message ID | 20240605110845.86740-1-paul@crapouillou.net |
|---|---|
| Headers | show |
| Series | iio: new DMABUF based API v10 | expand |
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, > +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.
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. > > > + 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
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.
On Wed, 5 Jun 2024 13:08:39 +0200 Paul Cercueil <paul@crapouillou.net> wrote: > Hi Jonathan, > > Here is a revised (and hopefully final?) version of my DMABUF patchset. Fingers crossed it's just docs changes for v11. So on to the details of how to merge this... For the DMAEngine maintainers: Given IIO changes dominate this series it makes sense for me to pick it up through IIO. Do you want an immutable branch with the first patch on it, or is this unlikely to cause merge conflicts with any other ongoing work in dmabuffer land? I'm fine either way and if I don't hear back on this will do an immutable branch and announce it when I apply v11 (I hope!) Jonathan > > This v10 removes the extra "flags" parameter of > dmaengine_prep_peripheral_dma_vec(), and adds kernel doc to the function > as Vinod requested. > > As Nuno upstreamed support for output buffers, I (slightly) modified > patch 5/6 and now output buffers are supported with the DMABUF API. > All I did was remove a "fail if output" check really. > > This was based on next-20240605. > > Changelog: > - [1/6]: > - Add kernel doc to dmaengine_prep_peripheral_dma_vec() > - Remove extra flags parameter > - [2/6]: > - Use the new function prototype (without the extra prep_flags). > - [5/6]: > - Remove extra flags parameter to dmaengine_prep_peripheral_dma_vec() > - Add support for TX transfers > > Cheers, > -Paul > > Paul Cercueil (6): > dmaengine: Add API function dmaengine_prep_peripheral_dma_vec() > dmaengine: dma-axi-dmac: Implement device_prep_peripheral_dma_vec > iio: core: Add new DMABUF interface infrastructure > iio: buffer-dma: Enable support for DMABUFs > iio: buffer-dmaengine: Support new DMABUF based userspace API > Documentation: iio: Document high-speed DMABUF based API > > Documentation/iio/iio_dmabuf_api.rst | 54 ++ > Documentation/iio/index.rst | 1 + > drivers/dma/dma-axi-dmac.c | 40 ++ > drivers/iio/Kconfig | 1 + > drivers/iio/buffer/industrialio-buffer-dma.c | 180 ++++++- > .../buffer/industrialio-buffer-dmaengine.c | 62 ++- > drivers/iio/industrialio-buffer.c | 462 ++++++++++++++++++ > include/linux/dmaengine.h | 33 ++ > include/linux/iio/buffer-dma.h | 31 ++ > include/linux/iio/buffer_impl.h | 30 ++ > include/uapi/linux/iio/buffer.h | 22 + > 11 files changed, 896 insertions(+), 20 deletions(-) > create mode 100644 Documentation/iio/iio_dmabuf_api.rst >