55 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===================================4High-speed DMABUF interface for IIO5===================================6 71. Overview8===========9 10The Industrial I/O subsystem supports access to buffers through a11file-based interface, with read() and write() access calls through the12IIO device's dev node.13 14It additionally supports a DMABUF based interface, where the userspace15can attach DMABUF objects (externally created) to an IIO buffer, and16subsequently use them for data transfers.17 18A userspace application can then use this interface to share DMABUF19objects between several interfaces, allowing it to transfer data in a20zero-copy fashion, for instance between IIO and the USB stack.21 22The userspace application can also memory-map the DMABUF objects, and23access the sample data directly. The advantage of doing this vs. the24read() interface is that it avoids an extra copy of the data between the25kernel and userspace. This is particularly useful for high-speed devices26which produce several megabytes or even gigabytes of data per second.27It does however increase the userspace-kernelspace synchronization28overhead, as the DMA_BUF_SYNC_START and DMA_BUF_SYNC_END IOCTLs have to29be used for data integrity.30 312. User API32===========33 34As part of this interface, three new IOCTLs have been added. These three35IOCTLs have to be performed on the IIO buffer's file descriptor, which36can be obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl.37 38 ``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int fd)``39 Attach the DMABUF object, identified by its file descriptor, to the40 IIO buffer. Returns zero on success, and a negative errno value on41 error.42 43 ``IIO_BUFFER_DMABUF_DETACH_IOCTL(int fd)``44 Detach the given DMABUF object, identified by its file descriptor,45 from the IIO buffer. Returns zero on success, and a negative errno46 value on error.47 48 Note that closing the IIO buffer's file descriptor will49 automatically detach all previously attached DMABUF objects.50 51 ``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)``52 Enqueue a previously attached DMABUF object to the buffer queue.53 Enqueued DMABUFs will be read from (if output buffer) or written to54 (if input buffer) as long as the buffer is enabled.55