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
+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 4c13bfa2865c..9cb4c50cb20d 100644
--- a/Documentation/iio/index.rst
+++ b/Documentation/iio/index.rst
@@ -9,6 +9,7 @@ Industrial I/O
 
    iio_configfs
    iio_devbuf
+   iio_dmabuf_api
    iio_tools
 
 Industrial I/O Kernel Drivers
-- 
2.43.0

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

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