| Message ID | 20230403154955.216148-2-paul@crapouillou.net (mailing list archive) |
|---|---|
| State | Handled Elsewhere |
| Headers | show |
| Series | iio: new DMABUF based API, v3 | expand |
Paul Cercueil <paul@crapouillou.net> writes: One nit: > Document the new DMABUF based API. > > Signed-off-by: Paul Cercueil <paul@crapouillou.net> > Cc: Jonathan Corbet <corbet@lwn.net> > Cc: linux-doc@vger.kernel.org > > --- > 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. > --- > Documentation/iio/dmabuf_api.rst | 59 ++++++++++++++++++++++++++++++++ > Documentation/iio/index.rst | 2 ++ > 2 files changed, 61 insertions(+) > create mode 100644 Documentation/iio/dmabuf_api.rst > > diff --git a/Documentation/iio/dmabuf_api.rst b/Documentation/iio/dmabuf_api.rst > new file mode 100644 > index 000000000000..4d70372c7ebd > --- /dev/null > +++ b/Documentation/iio/dmabuf_api.rst > @@ -0,0 +1,59 @@ > +.. 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 > +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)`` > +---------------------------------------------------------------- > + > +Attach the DMABUF object, identified by its file descriptor, to the IIO > +buffer. Returns zero on success, and a negative errno value on error. Rather than abusing subsections, this would be better done as a description list: IIO_BUFFER_DMABUF_ATTACH_IOCTL(int) Attach the DMABUF object, identified by its file descriptor, to the IIO buffer. Returns zero on success, and a negative errno value on error. Thanks, jon
Hi Jonathan, Le lundi 03 avril 2023 à 10:05 -0600, Jonathan Corbet a écrit : > Paul Cercueil <paul@crapouillou.net> writes: > > One nit: > > > Document the new DMABUF based API. > > > > Signed-off-by: Paul Cercueil <paul@crapouillou.net> > > Cc: Jonathan Corbet <corbet@lwn.net> > > Cc: linux-doc@vger.kernel.org > > > > --- > > 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. > > --- > > Documentation/iio/dmabuf_api.rst | 59 > > ++++++++++++++++++++++++++++++++ > > Documentation/iio/index.rst | 2 ++ > > 2 files changed, 61 insertions(+) > > create mode 100644 Documentation/iio/dmabuf_api.rst > > > > diff --git a/Documentation/iio/dmabuf_api.rst > > b/Documentation/iio/dmabuf_api.rst > > new file mode 100644 > > index 000000000000..4d70372c7ebd > > --- /dev/null > > +++ b/Documentation/iio/dmabuf_api.rst > > @@ -0,0 +1,59 @@ > > +.. 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 > > +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)`` > > +---------------------------------------------------------------- > > + > > +Attach the DMABUF object, identified by its file descriptor, to > > the IIO > > +buffer. Returns zero on success, and a negative errno value on > > error. > > Rather than abusing subsections, this would be better done as a > description list: > > IIO_BUFFER_DMABUF_ATTACH_IOCTL(int) > Attach the DMABUF object, identified by its file descriptor, to > the IIO buffer. Returns zero on success, and a negative errno > value on error. Noted, thanks. Cheers, -Paul
diff --git a/Documentation/iio/dmabuf_api.rst b/Documentation/iio/dmabuf_api.rst new file mode 100644 index 000000000000..4d70372c7ebd --- /dev/null +++ b/Documentation/iio/dmabuf_api.rst @@ -0,0 +1,59 @@ +.. 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 +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)`` +---------------------------------------------------------------- + +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)`` +-------------------------------------------------------- + +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. diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst index 1b7292c58cd0..3eae8fcb1938 100644 --- a/Documentation/iio/index.rst +++ b/Documentation/iio/index.rst @@ -9,6 +9,8 @@ Industrial I/O iio_configfs + dmabuf_api + ep93xx_adc bno055
Document the new DMABUF based API. Signed-off-by: Paul Cercueil <paul@crapouillou.net> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org --- 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. --- Documentation/iio/dmabuf_api.rst | 59 ++++++++++++++++++++++++++++++++ Documentation/iio/index.rst | 2 ++ 2 files changed, 61 insertions(+) create mode 100644 Documentation/iio/dmabuf_api.rst