Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-21 19:41:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: iio: Document high-speed DMABUF based API

Browse Source 
Document the new DMABUF based API.

Signed-off-by: Paul Cercueil <paul@crapouillou.net>
Co-developed-by: Nuno Sa <nuno.sa@analog.com>
Signed-off-by: Nuno Sa <nuno.sa@analog.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Link: https://patch.msgid.link/20240620122726.41232-7-paul@crapouillou.net
Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
This commit is contained in:
Paul Cercueil 2024-06-20 14:27:25 +02:00 committed by Jonathan Cameron
parent 7a86d46998
commit ebe061b9cc
2 changed files with 55 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
Documentation/iio/iio_dmabuf_api.rst Normal file
View File

@ -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 an 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, which
can be obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl.
``IIO_BUFFER_DMABUF_ATTACH_IOCTL(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 fd)``
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.

1
Documentation/iio/index.rst
View File

@ -9,6 +9,7 @@ Industrial I/O
iio_configfs
iio_devbuf
iio_dmabuf_api
iio_tools
Industrial I/O Kernel Drivers