1 .. SPDX-License-Identifier: GFDL-1.1-no-invari 1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L 2 .. c:namespace:: V4L
3 3
4 .. _mmap: 4 .. _mmap:
5 5
6 ****************************** 6 ******************************
7 Streaming I/O (Memory Mapping) 7 Streaming I/O (Memory Mapping)
8 ****************************** 8 ******************************
9 9
10 Input and output devices support this I/O meth 10 Input and output devices support this I/O method when the
11 ``V4L2_CAP_STREAMING`` flag in the ``capabilit 11 ``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
12 :c:type:`v4l2_capability` returned by the 12 :c:type:`v4l2_capability` returned by the
13 :ref:`VIDIOC_QUERYCAP` ioctl is set. There are 13 :ref:`VIDIOC_QUERYCAP` ioctl is set. There are two
14 streaming methods, to determine if the memory 14 streaming methods, to determine if the memory mapping flavor is
15 supported applications must call the :ref:`VID 15 supported applications must call the :ref:`VIDIOC_REQBUFS` ioctl
16 with the memory type set to ``V4L2_MEMORY_MMAP 16 with the memory type set to ``V4L2_MEMORY_MMAP``.
17 17
18 Streaming is an I/O method where only pointers 18 Streaming is an I/O method where only pointers to buffers are exchanged
19 between application and driver, the data itsel 19 between application and driver, the data itself is not copied. Memory
20 mapping is primarily intended to map buffers i 20 mapping is primarily intended to map buffers in device memory into the
21 application's address space. Device memory can 21 application's address space. Device memory can be for example the video
22 memory on a graphics card with a video capture 22 memory on a graphics card with a video capture add-on. However, being
23 the most efficient I/O method available for a 23 the most efficient I/O method available for a long time, many other
24 drivers support streaming as well, allocating 24 drivers support streaming as well, allocating buffers in DMA-able main
25 memory. 25 memory.
26 26
27 A driver can support many sets of buffers. Eac 27 A driver can support many sets of buffers. Each set is identified by a
28 unique buffer type value. The sets are indepen 28 unique buffer type value. The sets are independent and each set can hold
29 a different type of data. To access different 29 a different type of data. To access different sets at the same time
30 different file descriptors must be used. [#f1] 30 different file descriptors must be used. [#f1]_
31 31
32 To allocate device buffers applications call t 32 To allocate device buffers applications call the
33 :ref:`VIDIOC_REQBUFS` ioctl with the desired n 33 :ref:`VIDIOC_REQBUFS` ioctl with the desired number
34 of buffers and buffer type, for example ``V4L2 34 of buffers and buffer type, for example ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
35 This ioctl can also be used to change the numb 35 This ioctl can also be used to change the number of buffers or to free
36 the allocated memory, provided none of the buf 36 the allocated memory, provided none of the buffers are still mapped.
37 37
38 Before applications can access the buffers the 38 Before applications can access the buffers they must map them into their
39 address space with the :c:func:`mmap()` functi 39 address space with the :c:func:`mmap()` function. The
40 location of the buffers in device memory can b 40 location of the buffers in device memory can be determined with the
41 :ref:`VIDIOC_QUERYBUF` ioctl. In the single-pl 41 :ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar
42 API case, the ``m.offset`` and ``length`` retu 42 API case, the ``m.offset`` and ``length`` returned in a struct
43 :c:type:`v4l2_buffer` are passed as sixth and 43 :c:type:`v4l2_buffer` are passed as sixth and second
44 parameter to the :c:func:`mmap()` function. Wh 44 parameter to the :c:func:`mmap()` function. When using the
45 multi-planar API, struct :c:type:`v4l2_buffer` 45 multi-planar API, struct :c:type:`v4l2_buffer` contains an
46 array of struct :c:type:`v4l2_plane` structure 46 array of struct :c:type:`v4l2_plane` structures, each
47 containing its own ``m.offset`` and ``length`` 47 containing its own ``m.offset`` and ``length``. When using the
48 multi-planar API, every plane of every buffer 48 multi-planar API, every plane of every buffer has to be mapped
49 separately, so the number of calls to :c:func: 49 separately, so the number of calls to :c:func:`mmap()` should
50 be equal to number of buffers times number of 50 be equal to number of buffers times number of planes in each buffer. The
51 offset and length values must not be modified. 51 offset and length values must not be modified. Remember, the buffers are
52 allocated in physical memory, as opposed to vi 52 allocated in physical memory, as opposed to virtual memory, which can be
53 swapped out to disk. Applications should free 53 swapped out to disk. Applications should free the buffers as soon as
54 possible with the :c:func:`munmap()` function. 54 possible with the :c:func:`munmap()` function.
55 55
56 Example: Mapping buffers in the single-planar 56 Example: Mapping buffers in the single-planar API
57 ============================================== 57 =================================================
58 58
59 .. code-block:: c 59 .. code-block:: c
60 60
61 struct v4l2_requestbuffers reqbuf; 61 struct v4l2_requestbuffers reqbuf;
62 struct { 62 struct {
63 void *start; 63 void *start;
64 size_t length; 64 size_t length;
65 } *buffers; 65 } *buffers;
66 unsigned int i; 66 unsigned int i;
67 67
68 memset(&reqbuf, 0, sizeof(reqbuf)); 68 memset(&reqbuf, 0, sizeof(reqbuf));
69 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 69 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
70 reqbuf.memory = V4L2_MEMORY_MMAP; 70 reqbuf.memory = V4L2_MEMORY_MMAP;
71 reqbuf.count = 20; 71 reqbuf.count = 20;
72 72
73 if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqb 73 if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) {
74 if (errno == EINVAL) 74 if (errno == EINVAL)
75 printf("Video capturing or mmap-st 75 printf("Video capturing or mmap-streaming is not supported\\n");
76 else 76 else
77 perror("VIDIOC_REQBUFS"); 77 perror("VIDIOC_REQBUFS");
78 78
79 exit(EXIT_FAILURE); 79 exit(EXIT_FAILURE);
80 } 80 }
81 81
82 /* We want at least five buffers. */ 82 /* We want at least five buffers. */
83 83
84 if (reqbuf.count < 5) { 84 if (reqbuf.count < 5) {
85 /* You may need to free the buffers he 85 /* You may need to free the buffers here. */
86 printf("Not enough buffer memory\\n"); 86 printf("Not enough buffer memory\\n");
87 exit(EXIT_FAILURE); 87 exit(EXIT_FAILURE);
88 } 88 }
89 89
90 buffers = calloc(reqbuf.count, sizeof(*buf 90 buffers = calloc(reqbuf.count, sizeof(*buffers));
91 assert(buffers != NULL); 91 assert(buffers != NULL);
92 92
93 for (i = 0; i < reqbuf.count; i++) { 93 for (i = 0; i < reqbuf.count; i++) {
94 struct v4l2_buffer buffer; 94 struct v4l2_buffer buffer;
95 95
96 memset(&buffer, 0, sizeof(buffer)); 96 memset(&buffer, 0, sizeof(buffer));
97 buffer.type = reqbuf.type; 97 buffer.type = reqbuf.type;
98 buffer.memory = V4L2_MEMORY_MMAP; 98 buffer.memory = V4L2_MEMORY_MMAP;
99 buffer.index = i; 99 buffer.index = i;
100 100
101 if (-1 == ioctl (fd, VIDIOC_QUERYBUF, 101 if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
102 perror("VIDIOC_QUERYBUF"); 102 perror("VIDIOC_QUERYBUF");
103 exit(EXIT_FAILURE); 103 exit(EXIT_FAILURE);
104 } 104 }
105 105
106 buffers[i].length = buffer.length; /* 106 buffers[i].length = buffer.length; /* remember for munmap() */
107 107
108 buffers[i].start = mmap(NULL, buffer.l 108 buffers[i].start = mmap(NULL, buffer.length,
109 PROT_READ | PROT_WRITE, /* 109 PROT_READ | PROT_WRITE, /* recommended */
110 MAP_SHARED, /* 110 MAP_SHARED, /* recommended */
111 fd, buffer.m.offset); 111 fd, buffer.m.offset);
112 112
113 if (MAP_FAILED == buffers[i].start) { 113 if (MAP_FAILED == buffers[i].start) {
114 /* If you do not exit here you sho 114 /* If you do not exit here you should unmap() and free()
115 the buffers mapped so far. */ 115 the buffers mapped so far. */
116 perror("mmap"); 116 perror("mmap");
117 exit(EXIT_FAILURE); 117 exit(EXIT_FAILURE);
118 } 118 }
119 } 119 }
120 120
121 /* Cleanup. */ 121 /* Cleanup. */
122 122
123 for (i = 0; i < reqbuf.count; i++) 123 for (i = 0; i < reqbuf.count; i++)
124 munmap(buffers[i].start, buffers[i].le 124 munmap(buffers[i].start, buffers[i].length);
125 125
126 Example: Mapping buffers in the multi-planar A 126 Example: Mapping buffers in the multi-planar API
127 ============================================== 127 ================================================
128 128
129 .. code-block:: c 129 .. code-block:: c
130 130
131 struct v4l2_requestbuffers reqbuf; 131 struct v4l2_requestbuffers reqbuf;
132 /* Our current format uses 3 planes per bu 132 /* Our current format uses 3 planes per buffer */
133 #define FMT_NUM_PLANES = 3 133 #define FMT_NUM_PLANES = 3
134 134
135 struct { 135 struct {
136 void *start[FMT_NUM_PLANES]; 136 void *start[FMT_NUM_PLANES];
137 size_t length[FMT_NUM_PLANES]; 137 size_t length[FMT_NUM_PLANES];
138 } *buffers; 138 } *buffers;
139 unsigned int i, j; 139 unsigned int i, j;
140 140
141 memset(&reqbuf, 0, sizeof(reqbuf)); 141 memset(&reqbuf, 0, sizeof(reqbuf));
142 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_ 142 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
143 reqbuf.memory = V4L2_MEMORY_MMAP; 143 reqbuf.memory = V4L2_MEMORY_MMAP;
144 reqbuf.count = 20; 144 reqbuf.count = 20;
145 145
146 if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0 146 if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) {
147 if (errno == EINVAL) 147 if (errno == EINVAL)
148 printf("Video capturing or mmap-st 148 printf("Video capturing or mmap-streaming is not supported\\n");
149 else 149 else
150 perror("VIDIOC_REQBUFS"); 150 perror("VIDIOC_REQBUFS");
151 151
152 exit(EXIT_FAILURE); 152 exit(EXIT_FAILURE);
153 } 153 }
154 154
155 /* We want at least five buffers. */ 155 /* We want at least five buffers. */
156 156
157 if (reqbuf.count < 5) { 157 if (reqbuf.count < 5) {
158 /* You may need to free the buffers he 158 /* You may need to free the buffers here. */
159 printf("Not enough buffer memory\\n"); 159 printf("Not enough buffer memory\\n");
160 exit(EXIT_FAILURE); 160 exit(EXIT_FAILURE);
161 } 161 }
162 162
163 buffers = calloc(reqbuf.count, sizeof(*buf 163 buffers = calloc(reqbuf.count, sizeof(*buffers));
164 assert(buffers != NULL); 164 assert(buffers != NULL);
165 165
166 for (i = 0; i < reqbuf.count; i++) { 166 for (i = 0; i < reqbuf.count; i++) {
167 struct v4l2_buffer buffer; 167 struct v4l2_buffer buffer;
168 struct v4l2_plane planes[FMT_NUM_PLANE 168 struct v4l2_plane planes[FMT_NUM_PLANES];
169 169
170 memset(&buffer, 0, sizeof(buffer)); 170 memset(&buffer, 0, sizeof(buffer));
171 buffer.type = reqbuf.type; 171 buffer.type = reqbuf.type;
172 buffer.memory = V4L2_MEMORY_MMAP; 172 buffer.memory = V4L2_MEMORY_MMAP;
173 buffer.index = i; 173 buffer.index = i;
174 /* length in struct v4l2_buffer in mul 174 /* length in struct v4l2_buffer in multi-planar API stores the size
175 * of planes array. */ 175 * of planes array. */
176 buffer.length = FMT_NUM_PLANES; 176 buffer.length = FMT_NUM_PLANES;
177 buffer.m.planes = planes; 177 buffer.m.planes = planes;
178 178
179 if (ioctl(fd, VIDIOC_QUERYBUF, &buffer 179 if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < 0) {
180 perror("VIDIOC_QUERYBUF"); 180 perror("VIDIOC_QUERYBUF");
181 exit(EXIT_FAILURE); 181 exit(EXIT_FAILURE);
182 } 182 }
183 183
184 /* Every plane has to be mapped separa 184 /* Every plane has to be mapped separately */
185 for (j = 0; j < FMT_NUM_PLANES; j++) { 185 for (j = 0; j < FMT_NUM_PLANES; j++) {
186 buffers[i].length[j] = buffer.m.pl 186 buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
187 187
188 buffers[i].start[j] = mmap(NULL, b 188 buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
189 PROT_READ | PROT_WRITE, / 189 PROT_READ | PROT_WRITE, /* recommended */
190 MAP_SHARED, / 190 MAP_SHARED, /* recommended */
191 fd, buffer.m.planes[j].m. 191 fd, buffer.m.planes[j].m.mem_offset);
192 192
193 if (MAP_FAILED == buffers[i].start 193 if (MAP_FAILED == buffers[i].start[j]) {
194 /* If you do not exit here you 194 /* If you do not exit here you should unmap() and free()
195 the buffers and planes mapp 195 the buffers and planes mapped so far. */
196 perror("mmap"); 196 perror("mmap");
197 exit(EXIT_FAILURE); 197 exit(EXIT_FAILURE);
198 } 198 }
199 } 199 }
200 } 200 }
201 201
202 /* Cleanup. */ 202 /* Cleanup. */
203 203
204 for (i = 0; i < reqbuf.count; i++) 204 for (i = 0; i < reqbuf.count; i++)
205 for (j = 0; j < FMT_NUM_PLANES; j++) 205 for (j = 0; j < FMT_NUM_PLANES; j++)
206 munmap(buffers[i].start[j], buffer 206 munmap(buffers[i].start[j], buffers[i].length[j]);
207 207
208 Conceptually streaming drivers maintain two bu 208 Conceptually streaming drivers maintain two buffer queues, an incoming
209 and an outgoing queue. They separate the synch 209 and an outgoing queue. They separate the synchronous capture or output
210 operation locked to a video clock from the app 210 operation locked to a video clock from the application which is subject
211 to random disk or network delays and preemptio 211 to random disk or network delays and preemption by other processes,
212 thereby reducing the probability of data loss. 212 thereby reducing the probability of data loss. The queues are organized
213 as FIFOs, buffers will be output in the order 213 as FIFOs, buffers will be output in the order enqueued in the incoming
214 FIFO, and were captured in the order dequeued 214 FIFO, and were captured in the order dequeued from the outgoing FIFO.
215 215
216 The driver may require a minimum number of buf 216 The driver may require a minimum number of buffers enqueued at all times
217 to function, apart of this no limit exists on 217 to function, apart of this no limit exists on the number of buffers
218 applications can enqueue in advance, or dequeu 218 applications can enqueue in advance, or dequeue and process. They can
219 also enqueue in a different order than buffers 219 also enqueue in a different order than buffers have been dequeued, and
220 the driver can *fill* enqueued *empty* buffers 220 the driver can *fill* enqueued *empty* buffers in any order. [#f2]_ The
221 index number of a buffer (struct :c:type:`v4l2 221 index number of a buffer (struct :c:type:`v4l2_buffer`
222 ``index``) plays no role here, it only identif 222 ``index``) plays no role here, it only identifies the buffer.
223 223
224 Initially all mapped buffers are in dequeued s 224 Initially all mapped buffers are in dequeued state, inaccessible by the
225 driver. For capturing applications it is custo 225 driver. For capturing applications it is customary to first enqueue all
226 mapped buffers, then to start capturing and en 226 mapped buffers, then to start capturing and enter the read loop. Here
227 the application waits until a filled buffer ca 227 the application waits until a filled buffer can be dequeued, and
228 re-enqueues the buffer when the data is no lon 228 re-enqueues the buffer when the data is no longer needed. Output
229 applications fill and enqueue buffers, when en 229 applications fill and enqueue buffers, when enough buffers are stacked
230 up the output is started with :ref:`VIDIOC_STR 230 up the output is started with :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`.
231 In the write loop, when the application runs o 231 In the write loop, when the application runs out of free buffers, it
232 must wait until an empty buffer can be dequeue 232 must wait until an empty buffer can be dequeued and reused.
233 233
234 To enqueue and dequeue a buffer applications u 234 To enqueue and dequeue a buffer applications use the
235 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VID 235 :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
236 ioctl. The status of a buffer being mapped, en 236 ioctl. The status of a buffer being mapped, enqueued, full or empty can
237 be determined at any time using the :ref:`VIDI 237 be determined at any time using the :ref:`VIDIOC_QUERYBUF` ioctl. Two
238 methods exist to suspend execution of the appl 238 methods exist to suspend execution of the application until one or more
239 buffers can be dequeued. By default :ref:`VID 239 buffers can be dequeued. By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
240 blocks when no buffer is in the outgoing queue 240 blocks when no buffer is in the outgoing queue. When the ``O_NONBLOCK``
241 flag was given to the :c:func:`open()` functio 241 flag was given to the :c:func:`open()` function,
242 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns imme 242 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
243 error code when no buffer is available. The :c 243 error code when no buffer is available. The :c:func:`select()`
244 or :c:func:`poll()` functions are always avail 244 or :c:func:`poll()` functions are always available.
245 245
246 To start and stop capturing or output applicat 246 To start and stop capturing or output applications call the
247 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and : 247 :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
248 <VIDIOC_STREAMON>` ioctl. 248 <VIDIOC_STREAMON>` ioctl.
249 249
250 .. note:::ref:`VIDIOC_STREAMOFF <VIDIOC_STREAM 250 .. note:::ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
251 removes all buffers from both queues as a s 251 removes all buffers from both queues as a side effect. Since there is
252 no notion of doing anything "now" on a mult 252 no notion of doing anything "now" on a multitasking system, if an
253 application needs to synchronize with anoth 253 application needs to synchronize with another event it should examine
254 the struct ::c:type:`v4l2_buffer` ``timesta 254 the struct ::c:type:`v4l2_buffer` ``timestamp`` of captured
255 or outputted buffers. 255 or outputted buffers.
256 256
257 Drivers implementing memory mapping I/O must s 257 Drivers implementing memory mapping I/O must support the
258 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:` 258 :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF
259 <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_ 259 <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF
260 <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_ 260 <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
261 and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` 261 and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
262 <func-mmap>`, :c:func:`munmap()`, :ref:`select 262 <func-mmap>`, :c:func:`munmap()`, :ref:`select()
263 <func-select>` and :c:func:`poll()` function. 263 <func-select>` and :c:func:`poll()` function. [#f3]_
264 264
265 [capture example] 265 [capture example]
266 266
267 .. [#f1] 267 .. [#f1]
268 One could use one file descriptor and set t 268 One could use one file descriptor and set the buffer type field
269 accordingly when calling :ref:`VIDIOC_QBUF` 269 accordingly when calling :ref:`VIDIOC_QBUF` etc.,
270 but it makes the :c:func:`select()` functio 270 but it makes the :c:func:`select()` function ambiguous. We also
271 like the clean approach of one file descrip 271 like the clean approach of one file descriptor per logical stream.
272 Video overlay for example is also a logical 272 Video overlay for example is also a logical stream, although the CPU
273 is not needed for continuous operation. 273 is not needed for continuous operation.
274 274
275 .. [#f2] 275 .. [#f2]
276 Random enqueue order permits applications p 276 Random enqueue order permits applications processing images out of
277 order (such as video codecs) to return buff 277 order (such as video codecs) to return buffers earlier, reducing the
278 probability of data loss. Random fill order 278 probability of data loss. Random fill order allows drivers to reuse
279 buffers on a LIFO-basis, taking advantage o 279 buffers on a LIFO-basis, taking advantage of caches holding
280 scatter-gather lists and the like. 280 scatter-gather lists and the like.
281 281
282 .. [#f3] 282 .. [#f3]
283 At the driver level :c:func:`select()` and 283 At the driver level :c:func:`select()` and :c:func:`poll()` are
284 the same, and :c:func:`select()` is too imp 284 the same, and :c:func:`select()` is too important to be optional.
285 The rest should be evident. 285 The rest should be evident.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.