1 .. SPDX-License-Identifier: GFDL-1.1-no-invari !! 1 .. Permission is granted to copy, distribute and/or modify this
2 .. c:namespace:: V4L !! 2 .. document under the terms of the GNU Free Documentation License,
>> 3 .. Version 1.1 or any later version published by the Free Software
>> 4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
>> 5 .. and no Back-Cover Texts. A copy of the license is included at
>> 6 .. Documentation/userspace-api/media/fdl-appendix.rst.
>> 7 ..
>> 8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
3 9
4 .. _dmabuf: 10 .. _dmabuf:
5 11
6 ************************************ 12 ************************************
7 Streaming I/O (DMA buffer importing) 13 Streaming I/O (DMA buffer importing)
8 ************************************ 14 ************************************
9 15
10 The DMABUF framework provides a generic method 16 The DMABUF framework provides a generic method for sharing buffers
11 between multiple devices. Device drivers that 17 between multiple devices. Device drivers that support DMABUF can export
12 a DMA buffer to userspace as a file descriptor 18 a DMA buffer to userspace as a file descriptor (known as the exporter
13 role), import a DMA buffer from userspace usin 19 role), import a DMA buffer from userspace using a file descriptor
14 previously exported for a different or the sam 20 previously exported for a different or the same device (known as the
15 importer role), or both. This section describe 21 importer role), or both. This section describes the DMABUF importer role
16 API in V4L2. 22 API in V4L2.
17 23
18 Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF 24 Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF>` for details about
19 exporting V4L2 buffers as DMABUF file descript 25 exporting V4L2 buffers as DMABUF file descriptors.
20 26
21 Input and output devices support the streaming 27 Input and output devices support the streaming I/O method when the
22 ``V4L2_CAP_STREAMING`` flag in the ``capabilit 28 ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
23 :c:type:`v4l2_capability` returned by the 29 :c:type:`v4l2_capability` returned by the
24 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl 30 :ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether
25 importing DMA buffers through DMABUF file desc 31 importing DMA buffers through DMABUF file descriptors is supported is
26 determined by calling the :ref:`VIDIOC_REQBUFS 32 determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
27 ioctl with the memory type set to ``V4L2_MEMOR 33 ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
28 34
29 This I/O method is dedicated to sharing DMA bu 35 This I/O method is dedicated to sharing DMA buffers between different
30 devices, which may be V4L devices or other vid 36 devices, which may be V4L devices or other video-related devices (e.g.
31 DRM). Buffers (planes) are allocated by a driv 37 DRM). Buffers (planes) are allocated by a driver on behalf of an
32 application. Next, these buffers are exported 38 application. Next, these buffers are exported to the application as file
33 descriptors using an API which is specific for 39 descriptors using an API which is specific for an allocator driver. Only
34 such file descriptor are exchanged. The descri 40 such file descriptor are exchanged. The descriptors and meta-information
35 are passed in struct :c:type:`v4l2_buffer` (or 41 are passed in struct :c:type:`v4l2_buffer` (or in struct
36 :c:type:`v4l2_plane` in the multi-planar API c 42 :c:type:`v4l2_plane` in the multi-planar API case). The
37 driver must be switched into DMABUF I/O mode b 43 driver must be switched into DMABUF I/O mode by calling the
38 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with th 44 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
39 45
>> 46
40 Example: Initiating streaming I/O with DMABUF 47 Example: Initiating streaming I/O with DMABUF file descriptors
41 ============================================== 48 ==============================================================
42 49
43 .. code-block:: c 50 .. code-block:: c
44 51
45 struct v4l2_requestbuffers reqbuf; 52 struct v4l2_requestbuffers reqbuf;
46 53
47 memset(&reqbuf, 0, sizeof (reqbuf)); 54 memset(&reqbuf, 0, sizeof (reqbuf));
48 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 55 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
49 reqbuf.memory = V4L2_MEMORY_DMABUF; 56 reqbuf.memory = V4L2_MEMORY_DMABUF;
50 reqbuf.count = 1; 57 reqbuf.count = 1;
51 58
52 if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == 59 if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
53 if (errno == EINVAL) 60 if (errno == EINVAL)
54 printf("Video capturing or DMABUF 61 printf("Video capturing or DMABUF streaming is not supported\\n");
55 else 62 else
56 perror("VIDIOC_REQBUFS"); 63 perror("VIDIOC_REQBUFS");
57 64
58 exit(EXIT_FAILURE); 65 exit(EXIT_FAILURE);
59 } 66 }
60 67
61 The buffer (plane) file descriptor is passed o 68 The buffer (plane) file descriptor is passed on the fly with the
62 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In cas 69 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar
63 buffers, every plane can be associated with a 70 buffers, every plane can be associated with a different DMABUF
64 descriptor. Although buffers are commonly cycl 71 descriptor. Although buffers are commonly cycled, applications can pass
65 a different DMABUF descriptor at each :ref:`VI 72 a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
66 73
67 Example: Queueing DMABUF using single plane AP 74 Example: Queueing DMABUF using single plane API
68 ============================================== 75 ===============================================
69 76
70 .. code-block:: c 77 .. code-block:: c
71 78
72 int buffer_queue(int v4lfd, int index, int 79 int buffer_queue(int v4lfd, int index, int dmafd)
73 { 80 {
74 struct v4l2_buffer buf; 81 struct v4l2_buffer buf;
75 82
76 memset(&buf, 0, sizeof buf); 83 memset(&buf, 0, sizeof buf);
77 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE 84 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
78 buf.memory = V4L2_MEMORY_DMABUF; 85 buf.memory = V4L2_MEMORY_DMABUF;
79 buf.index = index; 86 buf.index = index;
80 buf.m.fd = dmafd; 87 buf.m.fd = dmafd;
81 88
82 if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == 89 if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
83 perror("VIDIOC_QBUF"); 90 perror("VIDIOC_QBUF");
84 return -1; 91 return -1;
85 } 92 }
86 93
87 return 0; 94 return 0;
88 } 95 }
89 96
90 Example 3.6. Queueing DMABUF using multi plane 97 Example 3.6. Queueing DMABUF using multi plane API
91 ============================================== 98 ==================================================
92 99
93 .. code-block:: c 100 .. code-block:: c
94 101
95 int buffer_queue_mp(int v4lfd, int index, 102 int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
96 { 103 {
97 struct v4l2_buffer buf; 104 struct v4l2_buffer buf;
98 struct v4l2_plane planes[VIDEO_MAX_PLA 105 struct v4l2_plane planes[VIDEO_MAX_PLANES];
99 int i; 106 int i;
100 107
101 memset(&buf, 0, sizeof buf); 108 memset(&buf, 0, sizeof buf);
102 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE 109 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
103 buf.memory = V4L2_MEMORY_DMABUF; 110 buf.memory = V4L2_MEMORY_DMABUF;
104 buf.index = index; 111 buf.index = index;
105 buf.m.planes = planes; 112 buf.m.planes = planes;
106 buf.length = n_planes; 113 buf.length = n_planes;
107 114
108 memset(&planes, 0, sizeof planes); 115 memset(&planes, 0, sizeof planes);
109 116
110 for (i = 0; i < n_planes; ++i) 117 for (i = 0; i < n_planes; ++i)
111 buf.m.planes[i].m.fd = dmafd[i]; 118 buf.m.planes[i].m.fd = dmafd[i];
112 119
113 if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == 120 if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
114 perror("VIDIOC_QBUF"); 121 perror("VIDIOC_QBUF");
115 return -1; 122 return -1;
116 } 123 }
117 124
118 return 0; 125 return 0;
119 } 126 }
120 127
121 Captured or displayed buffers are dequeued wit 128 Captured or displayed buffers are dequeued with the
122 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The d 129 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
123 buffer at any time between the completion of t 130 buffer at any time between the completion of the DMA and this ioctl. The
124 memory is also unlocked when 131 memory is also unlocked when
125 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is c 132 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
126 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or whe 133 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed.
127 134
128 For capturing applications it is customary to 135 For capturing applications it is customary to enqueue a number of empty
129 buffers, to start capturing and enter the read 136 buffers, to start capturing and enter the read loop. Here the
130 application waits until a filled buffer can be 137 application waits until a filled buffer can be dequeued, and re-enqueues
131 the buffer when the data is no longer needed. 138 the buffer when the data is no longer needed. Output applications fill
132 and enqueue buffers, when enough buffers are s 139 and enqueue buffers, when enough buffers are stacked up output is
133 started. In the write loop, when the applicati 140 started. In the write loop, when the application runs out of free
134 buffers it must wait until an empty buffer can 141 buffers it must wait until an empty buffer can be dequeued and reused.
135 Two methods exist to suspend execution of the 142 Two methods exist to suspend execution of the application until one or
136 more buffers can be dequeued. By default :ref: 143 more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
137 <VIDIOC_QBUF>` blocks when no buffer is in the 144 <VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
138 ``O_NONBLOCK`` flag was given to the :c:func:` !! 145 ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
139 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns imme 146 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
140 error code when no buffer is available. The 147 error code when no buffer is available. The
141 :c:func:`select()` and :c:func:`poll()` !! 148 :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
142 functions are always available. 149 functions are always available.
143 150
144 To start and stop capturing or displaying appl 151 To start and stop capturing or displaying applications call the
145 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and 152 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
146 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioct 153 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls.
147 154
148 .. note:: 155 .. note::
149 156
150 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` r 157 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
151 both queues and unlocks all buffers as a si 158 both queues and unlocks all buffers as a side effect. Since there is no
152 notion of doing anything "now" on a multita 159 notion of doing anything "now" on a multitasking system, if an
153 application needs to synchronize with anoth 160 application needs to synchronize with another event it should examine
154 the struct :c:type:`v4l2_buffer` ``timestam 161 the struct :c:type:`v4l2_buffer` ``timestamp`` of captured or
155 outputted buffers. 162 outputted buffers.
156 163
157 Drivers implementing DMABUF importing I/O must 164 Drivers implementing DMABUF importing I/O must support the
158 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:` 165 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
159 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIO 166 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON
160 <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF 167 <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
161 and the :c:func:`select()` and :c:func:`poll() !! 168 and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
162 functions. 169 functions.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.