1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =================================== 3 ===================================
4 High-speed DMABUF interface for IIO 4 High-speed DMABUF interface for IIO
5 =================================== 5 ===================================
6 6
7 1. Overview 7 1. Overview
8 =========== 8 ===========
9 9
10 The Industrial I/O subsystem supports access t 10 The Industrial I/O subsystem supports access to buffers through a
11 file-based interface, with read() and write() 11 file-based interface, with read() and write() access calls through the
12 IIO device's dev node. 12 IIO device's dev node.
13 13
14 It additionally supports a DMABUF based interf 14 It additionally supports a DMABUF based interface, where the userspace
15 can attach DMABUF objects (externally created) 15 can attach DMABUF objects (externally created) to an IIO buffer, and
16 subsequently use them for data transfers. 16 subsequently use them for data transfers.
17 17
18 A userspace application can then use this inte 18 A userspace application can then use this interface to share DMABUF
19 objects between several interfaces, allowing i 19 objects between several interfaces, allowing it to transfer data in a
20 zero-copy fashion, for instance between IIO an 20 zero-copy fashion, for instance between IIO and the USB stack.
21 21
22 The userspace application can also memory-map 22 The userspace application can also memory-map the DMABUF objects, and
23 access the sample data directly. The advantage 23 access the sample data directly. The advantage of doing this vs. the
24 read() interface is that it avoids an extra co 24 read() interface is that it avoids an extra copy of the data between the
25 kernel and userspace. This is particularly use 25 kernel and userspace. This is particularly useful for high-speed devices
26 which produce several megabytes or even gigaby 26 which produce several megabytes or even gigabytes of data per second.
27 It does however increase the userspace-kernels 27 It does however increase the userspace-kernelspace synchronization
28 overhead, as the DMA_BUF_SYNC_START and DMA_BU 28 overhead, as the DMA_BUF_SYNC_START and DMA_BUF_SYNC_END IOCTLs have to
29 be used for data integrity. 29 be used for data integrity.
30 30
31 2. User API 31 2. User API
32 =========== 32 ===========
33 33
34 As part of this interface, three new IOCTLs ha 34 As part of this interface, three new IOCTLs have been added. These three
35 IOCTLs have to be performed on the IIO buffer' 35 IOCTLs have to be performed on the IIO buffer's file descriptor, which
36 can be obtained using the IIO_BUFFER_GET_FD_IO 36 can be obtained using the IIO_BUFFER_GET_FD_IOCTL() ioctl.
37 37
38 ``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int fd)`` 38 ``IIO_BUFFER_DMABUF_ATTACH_IOCTL(int fd)``
39 Attach the DMABUF object, identified by it 39 Attach the DMABUF object, identified by its file descriptor, to the
40 IIO buffer. Returns zero on success, and a 40 IIO buffer. Returns zero on success, and a negative errno value on
41 error. 41 error.
42 42
43 ``IIO_BUFFER_DMABUF_DETACH_IOCTL(int fd)`` 43 ``IIO_BUFFER_DMABUF_DETACH_IOCTL(int fd)``
44 Detach the given DMABUF object, identified 44 Detach the given DMABUF object, identified by its file descriptor,
45 from the IIO buffer. Returns zero on succe 45 from the IIO buffer. Returns zero on success, and a negative errno
46 value on error. 46 value on error.
47 47
48 Note that closing the IIO buffer's file de 48 Note that closing the IIO buffer's file descriptor will
49 automatically detach all previously attach 49 automatically detach all previously attached DMABUF objects.
50 50
51 ``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio 51 ``IIO_BUFFER_DMABUF_ENQUEUE_IOCTL(struct iio_dmabuf *iio_dmabuf)``
52 Enqueue a previously attached DMABUF objec 52 Enqueue a previously attached DMABUF object to the buffer queue.
53 Enqueued DMABUFs will be read from (if out 53 Enqueued DMABUFs will be read from (if output buffer) or written to
54 (if input buffer) as long as the buffer is 54 (if input buffer) as long as the buffer is enabled.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.