| blob | 1c17f802b471d66e2ff005925f04dd1842167b06 |
1 <title>Input/Output</title>
3 <para>The V4L2 API defines several different methods to read from or
4 write to a device. All drivers exchanging data with applications must
5 support at least one of them.</para>
7 <para>The classic I/O method using the <function>read()</function>
8 and <function>write()</function> function is automatically selected
9 after opening a V4L2 device. When the driver does not support this
10 method attempts to read or write will fail at any time.</para>
12 <para>Other methods must be negotiated. To select the streaming I/O
13 method with memory mapped or user buffers applications call the
14 &VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
15 yet.</para>
17 <para>Video overlay can be considered another I/O method, although
18 the application does not directly receive the image data. It is
19 selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl.
20 For more information see <xref linkend="overlay" />.</para>
22 <para>Generally exactly one I/O method, including overlay, is
23 associated with each file descriptor. The only exceptions are
24 applications not exchanging data with a driver ("panel applications",
25 see <xref linkend="open" />) and drivers permitting simultaneous video capturing
26 and overlay using the same file descriptor, for compatibility with V4L
27 and earlier versions of V4L2.</para>
29 <para><constant>VIDIOC_S_FMT</constant> and
30 <constant>VIDIOC_REQBUFS</constant> would permit this to some degree,
31 but for simplicity drivers need not support switching the I/O method
32 (after first switching away from read/write) other than by closing
33 and reopening the device.</para>
35 <para>The following sections describe the various I/O methods in
36 more detail.</para>
38 <section id="rw">
39 <title>Read/Write</title>
41 <para>Input and output devices support the
42 <function>read()</function> and <function>write()</function> function,
43 respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in
44 the <structfield>capabilities</structfield> field of &v4l2-capability;
45 returned by the &VIDIOC-QUERYCAP; ioctl is set.</para>
47 <para>Drivers may need the CPU to copy the data, but they may also
48 support DMA to or from user memory, so this I/O method is not
49 necessarily less efficient than other methods merely exchanging buffer
50 pointers. It is considered inferior though because no meta-information
51 like frame counters or timestamps are passed. This information is
52 necessary to recognize frame dropping and to synchronize with other
53 data streams. However this is also the simplest I/O method, requiring
54 little or no setup to exchange data. It permits command line stunts
55 like this (the <application>vidctrl</application> tool is
56 fictitious):</para>
58 <informalexample>
59 <screen>
60 > vidctrl /dev/video --input=0 --format=YUYV --size=352x288
61 > dd if=/dev/video of=myimage.422 bs=202752 count=1
62 </screen>
63 </informalexample>
65 <para>To read from the device applications use the
66 &func-read; function, to write the &func-write; function.
67 Drivers must implement one I/O method if they
68 exchange data with applications, but it need not be this.<footnote>
69 <para>It would be desirable if applications could depend on
70 drivers supporting all I/O interfaces, but as much as the complex
71 memory mapping I/O can be inadequate for some devices we have no
72 reason to require this interface, which is most useful for simple
73 applications capturing still images.</para>
74 </footnote> When reading or writing is supported, the driver
75 must also support the &func-select; and &func-poll;
76 function.<footnote>
77 <para>At the driver level <function>select()</function> and
78 <function>poll()</function> are the same, and
79 <function>select()</function> is too important to be optional.</para>
80 </footnote></para>
81 </section>
83 <section id="mmap">
84 <title>Streaming I/O (Memory Mapping)</title>
86 <para>Input and output devices support this I/O method when the
87 <constant>V4L2_CAP_STREAMING</constant> flag in the
88 <structfield>capabilities</structfield> field of &v4l2-capability;
89 returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
90 streaming methods, to determine if the memory mapping flavor is
91 supported applications must call the &VIDIOC-REQBUFS; ioctl.</para>
93 <para>Streaming is an I/O method where only pointers to buffers
94 are exchanged between application and driver, the data itself is not
95 copied. Memory mapping is primarily intended to map buffers in device
96 memory into the application's address space. Device memory can be for
97 example the video memory on a graphics card with a video capture
98 add-on. However, being the most efficient I/O method available for a
99 long time, many other drivers support streaming as well, allocating
100 buffers in DMA-able main memory.</para>
102 <para>A driver can support many sets of buffers. Each set is
103 identified by a unique buffer type value. The sets are independent and
104 each set can hold a different type of data. To access different sets
105 at the same time different file descriptors must be used.<footnote>
106 <para>One could use one file descriptor and set the buffer
107 type field accordingly when calling &VIDIOC-QBUF; etc., but it makes
108 the <function>select()</function> function ambiguous. We also like the
109 clean approach of one file descriptor per logical stream. Video
110 overlay for example is also a logical stream, although the CPU is not
111 needed for continuous operation.</para>
112 </footnote></para>
114 <para>To allocate device buffers applications call the
115 &VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer
116 type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.
117 This ioctl can also be used to change the number of buffers or to free
118 the allocated memory, provided none of the buffers are still
119 mapped.</para>
121 <para>Before applications can access the buffers they must map
122 them into their address space with the &func-mmap; function. The
123 location of the buffers in device memory can be determined with the
124 &VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
125 <structfield>m.offset</structfield> and <structfield>length</structfield>
126 returned in a &v4l2-buffer; are passed as sixth and second parameter to the
127 <function>mmap()</function> function. When using the multi-planar API,
128 &v4l2-buffer; contains an array of &v4l2-plane; structures, each
129 containing its own <structfield>m.offset</structfield> and
130 <structfield>length</structfield>. When using the multi-planar API, every
131 plane of every buffer has to be mapped separately, so the number of
132 calls to &func-mmap; should be equal to number of buffers times number of
133 planes in each buffer. The offset and length values must not be modified.
134 Remember, the buffers are allocated in physical memory, as opposed to virtual
135 memory, which can be swapped out to disk. Applications should free the buffers
136 as soon as possible with the &func-munmap; function.</para>
138 <example>
139 <title>Mapping buffers in the single-planar API</title>
140 <programlisting>
141 &v4l2-requestbuffers; reqbuf;
142 struct {
143 void *start;
144 size_t length;
145 } *buffers;
146 unsigned int i;
148 memset(&reqbuf, 0, sizeof(reqbuf));
149 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
150 reqbuf.memory = V4L2_MEMORY_MMAP;
151 reqbuf.count = 20;
153 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) {
154 if (errno == EINVAL)
155 printf("Video capturing or mmap-streaming is not supported\n");
156 else
157 perror("VIDIOC_REQBUFS");
159 exit(EXIT_FAILURE);
160 }
162 /* We want at least five buffers. */
164 if (reqbuf.count < 5) {
165 /* You may need to free the buffers here. */
166 printf("Not enough buffer memory\n");
167 exit(EXIT_FAILURE);
168 }
170 buffers = calloc(reqbuf.count, sizeof(*buffers));
171 assert(buffers != NULL);
173 for (i = 0; i < reqbuf.count; i++) {
174 &v4l2-buffer; buffer;
176 memset(&buffer, 0, sizeof(buffer));
177 buffer.type = reqbuf.type;
178 buffer.memory = V4L2_MEMORY_MMAP;
179 buffer.index = i;
181 if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &buffer)) {
182 perror("VIDIOC_QUERYBUF");
183 exit(EXIT_FAILURE);
184 }
186 buffers[i].length = buffer.length; /* remember for munmap() */
188 buffers[i].start = mmap(NULL, buffer.length,
189 PROT_READ | PROT_WRITE, /* recommended */
190 MAP_SHARED, /* recommended */
191 fd, buffer.m.offset);
193 if (MAP_FAILED == buffers[i].start) {
194 /* If you do not exit here you should unmap() and free()
195 the buffers mapped so far. */
196 perror("mmap");
197 exit(EXIT_FAILURE);
198 }
199 }
201 /* Cleanup. */
203 for (i = 0; i < reqbuf.count; i++)
204 munmap(buffers[i].start, buffers[i].length);
205 </programlisting>
206 </example>
208 <example>
209 <title>Mapping buffers in the multi-planar API</title>
210 <programlisting>
211 &v4l2-requestbuffers; reqbuf;
212 /* Our current format uses 3 planes per buffer */
213 #define FMT_NUM_PLANES = 3
215 struct {
216 void *start[FMT_NUM_PLANES];
217 size_t length[FMT_NUM_PLANES];
218 } *buffers;
219 unsigned int i, j;
221 memset(&reqbuf, 0, sizeof(reqbuf));
222 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
223 reqbuf.memory = V4L2_MEMORY_MMAP;
224 reqbuf.count = 20;
226 if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) {
227 if (errno == EINVAL)
228 printf("Video capturing or mmap-streaming is not supported\n");
229 else
230 perror("VIDIOC_REQBUFS");
232 exit(EXIT_FAILURE);
233 }
235 /* We want at least five buffers. */
237 if (reqbuf.count < 5) {
238 /* You may need to free the buffers here. */
239 printf("Not enough buffer memory\n");
240 exit(EXIT_FAILURE);
241 }
243 buffers = calloc(reqbuf.count, sizeof(*buffers));
244 assert(buffers != NULL);
246 for (i = 0; i < reqbuf.count; i++) {
247 &v4l2-buffer; buffer;
248 &v4l2-plane; planes[FMT_NUM_PLANES];
250 memset(&buffer, 0, sizeof(buffer));
251 buffer.type = reqbuf.type;
252 buffer.memory = V4L2_MEMORY_MMAP;
253 buffer.index = i;
254 /* length in struct v4l2_buffer in multi-planar API stores the size
255 * of planes array. */
256 buffer.length = FMT_NUM_PLANES;
257 buffer.m.planes = planes;
259 if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) {
260 perror("VIDIOC_QUERYBUF");
261 exit(EXIT_FAILURE);
262 }
264 /* Every plane has to be mapped separately */
265 for (j = 0; j < FMT_NUM_PLANES; j++) {
266 buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
268 buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
269 PROT_READ | PROT_WRITE, /* recommended */
270 MAP_SHARED, /* recommended */
271 fd, buffer.m.planes[j].m.offset);
273 if (MAP_FAILED == buffers[i].start[j]) {
274 /* If you do not exit here you should unmap() and free()
275 the buffers and planes mapped so far. */
276 perror("mmap");
277 exit(EXIT_FAILURE);
278 }
279 }
280 }
282 /* Cleanup. */
284 for (i = 0; i < reqbuf.count; i++)
285 for (j = 0; j < FMT_NUM_PLANES; j++)
286 munmap(buffers[i].start[j], buffers[i].length[j]);
287 </programlisting>
288 </example>
290 <para>Conceptually streaming drivers maintain two buffer queues, an incoming
291 and an outgoing queue. They separate the synchronous capture or output
292 operation locked to a video clock from the application which is
293 subject to random disk or network delays and preemption by
294 other processes, thereby reducing the probability of data loss.
295 The queues are organized as FIFOs, buffers will be
296 output in the order enqueued in the incoming FIFO, and were
297 captured in the order dequeued from the outgoing FIFO.</para>
299 <para>The driver may require a minimum number of buffers enqueued
300 at all times to function, apart of this no limit exists on the number
301 of buffers applications can enqueue in advance, or dequeue and
302 process. They can also enqueue in a different order than buffers have
303 been dequeued, and the driver can <emphasis>fill</emphasis> enqueued
304 <emphasis>empty</emphasis> buffers in any order. <footnote>
305 <para>Random enqueue order permits applications processing
306 images out of order (such as video codecs) to return buffers earlier,
307 reducing the probability of data loss. Random fill order allows
308 drivers to reuse buffers on a LIFO-basis, taking advantage of caches
309 holding scatter-gather lists and the like.</para>
310 </footnote> The index number of a buffer (&v4l2-buffer;
311 <structfield>index</structfield>) plays no role here, it only
312 identifies the buffer.</para>
314 <para>Initially all mapped buffers are in dequeued state,
315 inaccessible by the driver. For capturing applications it is customary
316 to first enqueue all mapped buffers, then to start capturing and enter
317 the read loop. Here the application waits until a filled buffer can be
318 dequeued, and re-enqueues the buffer when the data is no longer
319 needed. Output applications fill and enqueue buffers, when enough
320 buffers are stacked up the output is started with
321 <constant>VIDIOC_STREAMON</constant>. In the write loop, when
322 the application runs out of free buffers, it must wait until an empty
323 buffer can be dequeued and reused.</para>
325 <para>To enqueue and dequeue a buffer applications use the
326 &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
327 mapped, enqueued, full or empty can be determined at any time using the
328 &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
329 application until one or more buffers can be dequeued. By default
330 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
331 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
332 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
333 returns immediately with an &EAGAIN; when no buffer is available. The
334 &func-select; or &func-poll; functions are always available.</para>
336 <para>To start and stop capturing or output applications call the
337 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
338 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
339 queues as a side effect. Since there is no notion of doing anything
340 "now" on a multitasking system, if an application needs to synchronize
341 with another event it should examine the &v4l2-buffer;
342 <structfield>timestamp</structfield> of captured or outputted buffers.
343 </para>
345 <para>Drivers implementing memory mapping I/O must
346 support the <constant>VIDIOC_REQBUFS</constant>,
347 <constant>VIDIOC_QUERYBUF</constant>,
348 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
349 <constant>VIDIOC_STREAMON</constant> and
350 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
351 <function>mmap()</function>, <function>munmap()</function>,
352 <function>select()</function> and <function>poll()</function>
353 function.<footnote>
354 <para>At the driver level <function>select()</function> and
355 <function>poll()</function> are the same, and
356 <function>select()</function> is too important to be optional. The
357 rest should be evident.</para>
358 </footnote></para>
360 <para>[capture example]</para>
362 </section>
364 <section id="userp">
365 <title>Streaming I/O (User Pointers)</title>
367 <para>Input and output devices support this I/O method when the
368 <constant>V4L2_CAP_STREAMING</constant> flag in the
369 <structfield>capabilities</structfield> field of &v4l2-capability;
370 returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
371 pointer method (not only memory mapping) is supported must be
372 determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
374 <para>This I/O method combines advantages of the read/write and
375 memory mapping methods. Buffers (planes) are allocated by the application
376 itself, and can reside for example in virtual or shared memory. Only
377 pointers to data are exchanged, these pointers and meta-information
378 are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
379 The driver must be switched into user pointer I/O mode by calling the
380 &VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
381 beforehand, consequently they are not indexed and cannot be queried like mapped
382 buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
384 <example>
385 <title>Initiating streaming I/O with user pointers</title>
387 <programlisting>
388 &v4l2-requestbuffers; reqbuf;
390 memset (&reqbuf, 0, sizeof (reqbuf));
391 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
392 reqbuf.memory = V4L2_MEMORY_USERPTR;
394 if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) {
395 if (errno == EINVAL)
396 printf ("Video capturing or user pointer streaming is not supported\n");
397 else
398 perror ("VIDIOC_REQBUFS");
400 exit (EXIT_FAILURE);
401 }
402 </programlisting>
403 </example>
405 <para>Buffer (plane) addresses and sizes are passed on the fly with the
406 &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
407 applications can pass different addresses and sizes at each
408 <constant>VIDIOC_QBUF</constant> call. If required by the hardware the
409 driver swaps memory pages within physical memory to create a
410 continuous area of memory. This happens transparently to the
411 application in the virtual memory subsystem of the kernel. When buffer
412 pages have been swapped out to disk they are brought back and finally
413 locked in physical memory for DMA.<footnote>
414 <para>We expect that frequently used buffers are typically not
415 swapped out. Anyway, the process of swapping, locking or generating
416 scatter-gather lists may be time consuming. The delay can be masked by
417 the depth of the incoming buffer queue, and perhaps by maintaining
418 caches assuming a buffer will be soon enqueued again. On the other
419 hand, to optimize memory usage drivers can limit the number of buffers
420 locked in advance and recycle the most recently used buffers first. Of
421 course, the pages of empty buffers in the incoming queue need not be
422 saved to disk. Output buffers must be saved on the incoming and
423 outgoing queue because an application may share them with other
424 processes.</para>
425 </footnote></para>
427 <para>Filled or displayed buffers are dequeued with the
428 &VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any
429 time between the completion of the DMA and this ioctl. The memory is
430 also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
431 when the device is closed. Applications must take care not to free
432 buffers without dequeuing. For once, the buffers remain locked until
433 further, wasting physical memory. Second the driver will not be
434 notified when the memory is returned to the application's free list
435 and subsequently reused for other purposes, possibly completing the
436 requested DMA and overwriting valuable data.</para>
438 <para>For capturing applications it is customary to enqueue a
439 number of empty buffers, to start capturing and enter the read loop.
440 Here the application waits until a filled buffer can be dequeued, and
441 re-enqueues the buffer when the data is no longer needed. Output
442 applications fill and enqueue buffers, when enough buffers are stacked
443 up output is started. In the write loop, when the application
444 runs out of free buffers it must wait until an empty buffer can be
445 dequeued and reused. Two methods exist to suspend execution of the
446 application until one or more buffers can be dequeued. By default
447 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
448 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
449 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
450 returns immediately with an &EAGAIN; when no buffer is available. The
451 &func-select; or &func-poll; function are always available.</para>
453 <para>To start and stop capturing or output applications call the
454 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
455 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
456 queues and unlocks all buffers as a side effect. Since there is no
457 notion of doing anything "now" on a multitasking system, if an
458 application needs to synchronize with another event it should examine
459 the &v4l2-buffer; <structfield>timestamp</structfield> of captured
460 or outputted buffers.</para>
462 <para>Drivers implementing user pointer I/O must
463 support the <constant>VIDIOC_REQBUFS</constant>,
464 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
465 <constant>VIDIOC_STREAMON</constant> and
466 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
467 <function>select()</function> and <function>poll()</function> function.<footnote>
468 <para>At the driver level <function>select()</function> and
469 <function>poll()</function> are the same, and
470 <function>select()</function> is too important to be optional. The
471 rest should be evident.</para>
472 </footnote></para>
473 </section>
475 <section id="dmabuf">
476 <title>Streaming I/O (DMA buffer importing)</title>
478 <note>
479 <title>Experimental</title>
480 <para>This is an <link linkend="experimental">experimental</link>
481 interface and may change in the future.</para>
482 </note>
484 <para>The DMABUF framework provides a generic method for sharing buffers
485 between multiple devices. Device drivers that support DMABUF can export a DMA
486 buffer to userspace as a file descriptor (known as the exporter role), import a
487 DMA buffer from userspace using a file descriptor previously exported for a
488 different or the same device (known as the importer role), or both. This
489 section describes the DMABUF importer role API in V4L2.</para>
491 <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for
492 details about exporting V4L2 buffers as DMABUF file descriptors.</para>
494 <para>Input and output devices support the streaming I/O method when the
495 <constant>V4L2_CAP_STREAMING</constant> flag in the
496 <structfield>capabilities</structfield> field of &v4l2-capability; returned by
497 the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through
498 DMABUF file descriptors is supported is determined by calling the
499 &VIDIOC-REQBUFS; ioctl with the memory type set to
500 <constant>V4L2_MEMORY_DMABUF</constant>.</para>
502 <para>This I/O method is dedicated to sharing DMA buffers between different
503 devices, which may be V4L devices or other video-related devices (e.g. DRM).
504 Buffers (planes) are allocated by a driver on behalf of an application. Next,
505 these buffers are exported to the application as file descriptors using an API
506 which is specific for an allocator driver. Only such file descriptor are
507 exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or
508 in &v4l2-plane; in the multi-planar API case). The driver must be switched
509 into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer
510 type.</para>
512 <example>
513 <title>Initiating streaming I/O with DMABUF file descriptors</title>
515 <programlisting>
516 &v4l2-requestbuffers; reqbuf;
518 memset(&reqbuf, 0, sizeof (reqbuf));
519 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
520 reqbuf.memory = V4L2_MEMORY_DMABUF;
521 reqbuf.count = 1;
523 if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) {
524 if (errno == EINVAL)
525 printf("Video capturing or DMABUF streaming is not supported\n");
526 else
527 perror("VIDIOC_REQBUFS");
529 exit(EXIT_FAILURE);
530 }
531 </programlisting>
532 </example>
534 <para>The buffer (plane) file descriptor is passed on the fly with the
535 &VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be
536 associated with a different DMABUF descriptor. Although buffers are commonly
537 cycled, applications can pass a different DMABUF descriptor at each
538 <constant>VIDIOC_QBUF</constant> call.</para>
540 <example>
541 <title>Queueing DMABUF using single plane API</title>
543 <programlisting>
544 int buffer_queue(int v4lfd, int index, int dmafd)
545 {
546 &v4l2-buffer; buf;
548 memset(&buf, 0, sizeof buf);
549 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
550 buf.memory = V4L2_MEMORY_DMABUF;
551 buf.index = index;
552 buf.m.fd = dmafd;
554 if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) {
555 perror("VIDIOC_QBUF");
556 return -1;
557 }
559 return 0;
560 }
561 </programlisting>
562 </example>
564 <example>
565 <title>Queueing DMABUF using multi plane API</title>
567 <programlisting>
568 int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
569 {
570 &v4l2-buffer; buf;
571 &v4l2-plane; planes[VIDEO_MAX_PLANES];
572 int i;
574 memset(&buf, 0, sizeof buf);
575 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
576 buf.memory = V4L2_MEMORY_DMABUF;
577 buf.index = index;
578 buf.m.planes = planes;
579 buf.length = n_planes;
581 memset(&planes, 0, sizeof planes);
583 for (i = 0; i < n_planes; ++i)
584 buf.m.planes[i].m.fd = dmafd[i];
586 if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) {
587 perror("VIDIOC_QBUF");
588 return -1;
589 }
591 return 0;
592 }
593 </programlisting>
594 </example>
596 <para>Captured or displayed buffers are dequeued with the
597 &VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any
598 time between the completion of the DMA and this ioctl. The memory is
599 also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
600 when the device is closed.</para>
602 <para>For capturing applications it is customary to enqueue a
603 number of empty buffers, to start capturing and enter the read loop.
604 Here the application waits until a filled buffer can be dequeued, and
605 re-enqueues the buffer when the data is no longer needed. Output
606 applications fill and enqueue buffers, when enough buffers are stacked
607 up output is started. In the write loop, when the application
608 runs out of free buffers it must wait until an empty buffer can be
609 dequeued and reused. Two methods exist to suspend execution of the
610 application until one or more buffers can be dequeued. By default
611 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
612 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
613 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
614 returns immediately with an &EAGAIN; when no buffer is available. The
615 &func-select; and &func-poll; functions are always available.</para>
617 <para>To start and stop capturing or displaying applications call the
618 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that
619 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and
620 unlocks all buffers as a side effect. Since there is no notion of doing
621 anything "now" on a multitasking system, if an application needs to synchronize
622 with another event it should examine the &v4l2-buffer;
623 <structfield>timestamp</structfield> of captured or outputted buffers.</para>
625 <para>Drivers implementing DMABUF importing I/O must support the
626 <constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>,
627 <constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and
628 <constant>VIDIOC_STREAMOFF</constant> ioctls, and the
629 <function>select()</function> and <function>poll()</function> functions.</para>
631 </section>
633 <section id="async">
634 <title>Asynchronous I/O</title>
636 <para>This method is not defined yet.</para>
637 </section>
639 <section id="buffer">
640 <title>Buffers</title>
642 <para>A buffer contains data exchanged by application and
643 driver using one of the Streaming I/O methods. In the multi-planar API, the
644 data is held in planes, while the buffer structure acts as a container
645 for the planes. Only pointers to buffers (planes) are exchanged, the data
646 itself is not copied. These pointers, together with meta-information like
647 timestamps or field parity, are stored in a struct
648 <structname>v4l2_buffer</structname>, argument to
649 the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
650 In the multi-planar API, some plane-specific members of struct
651 <structname>v4l2_buffer</structname>, such as pointers and sizes for each
652 plane, are stored in struct <structname>v4l2_plane</structname> instead.
653 In that case, struct <structname>v4l2_buffer</structname> contains an array of
654 plane structures.</para>
656 <para>Dequeued video buffers come with timestamps. The driver
657 decides at which part of the frame and with which clock the
658 timestamp is taken. Please see flags in the masks
659 <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and
660 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref
661 linkend="buffer-flags" />. These flags are always valid and constant
662 across all buffers during the whole video stream. Changes in these
663 flags may take place as a side effect of &VIDIOC-S-INPUT; or
664 &VIDIOC-S-OUTPUT; however. The
665 <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type
666 which is used by e.g. on mem-to-mem devices is an exception to the
667 rule: the timestamp source flags are copied from the OUTPUT video
668 buffer to the CAPTURE video buffer.</para>
670 <table frame="none" pgwide="1" id="v4l2-buffer">
671 <title>struct <structname>v4l2_buffer</structname></title>
672 <tgroup cols="4">
673 &cs-ustr;
674 <tbody valign="top">
675 <row>
676 <entry>__u32</entry>
677 <entry><structfield>index</structfield></entry>
678 <entry></entry>
679 <entry>Number of the buffer, set by the application except
680 when calling &VIDIOC-DQBUF;, then it is set by the driver.
681 This field can range from zero to the number of buffers allocated
682 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>),
683 plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry>
684 </row>
685 <row>
686 <entry>__u32</entry>
687 <entry><structfield>type</structfield></entry>
688 <entry></entry>
689 <entry>Type of the buffer, same as &v4l2-format;
690 <structfield>type</structfield> or &v4l2-requestbuffers;
691 <structfield>type</structfield>, set by the application. See <xref
692 linkend="v4l2-buf-type" /></entry>
693 </row>
694 <row>
695 <entry>__u32</entry>
696 <entry><structfield>bytesused</structfield></entry>
697 <entry></entry>
698 <entry>The number of bytes occupied by the data in the
699 buffer. It depends on the negotiated data format and may change with
700 each buffer for compressed variable size data like JPEG images.
701 Drivers must set this field when <structfield>type</structfield>
702 refers to an input stream, applications when it refers to an output stream.
703 If the application sets this to 0 for an output stream, then
704 <structfield>bytesused</structfield> will be set to the size of the
705 buffer (see the <structfield>length</structfield> field of this struct) by
706 the driver. For multiplanar formats this field is ignored and the
707 <structfield>planes</structfield> pointer is used instead.</entry>
708 </row>
709 <row>
710 <entry>__u32</entry>
711 <entry><structfield>flags</structfield></entry>
712 <entry></entry>
713 <entry>Flags set by the application or driver, see <xref
714 linkend="buffer-flags" />.</entry>
715 </row>
716 <row>
717 <entry>__u32</entry>
718 <entry><structfield>field</structfield></entry>
719 <entry></entry>
720 <entry>Indicates the field order of the image in the
721 buffer, see <xref linkend="v4l2-field" />. This field is not used when
722 the buffer contains VBI data. Drivers must set it when
723 <structfield>type</structfield> refers to an input stream,
724 applications when it refers to an output stream.</entry>
725 </row>
726 <row>
727 <entry>struct timeval</entry>
728 <entry><structfield>timestamp</structfield></entry>
729 <entry></entry>
730 <entry><para>For input streams this is time when the first data
731 byte was captured, as returned by the
732 <function>clock_gettime()</function> function for the relevant
733 clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in
734 <xref linkend="buffer-flags" />. For output streams the driver
735 stores the time at which the last data byte was actually sent out
736 in the <structfield>timestamp</structfield> field. This permits
737 applications to monitor the drift between the video and system
738 clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant>
739 the application has to fill in the timestamp which will be copied
740 by the driver to the capture stream.</para></entry>
741 </row>
742 <row>
743 <entry>&v4l2-timecode;</entry>
744 <entry><structfield>timecode</structfield></entry>
745 <entry></entry>
746 <entry>When <structfield>type</structfield> is
747 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
748 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
749 <structfield>flags</structfield>, this structure contains a frame
750 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
751 mode the top and bottom field contain the same timecode.
752 Timecodes are intended to help video editing and are typically recorded on
753 video tapes, but also embedded in compressed formats like MPEG. This
754 field is independent of the <structfield>timestamp</structfield> and
755 <structfield>sequence</structfield> fields.</entry>
756 </row>
757 <row>
758 <entry>__u32</entry>
759 <entry><structfield>sequence</structfield></entry>
760 <entry></entry>
761 <entry>Set by the driver, counting the frames (not fields!) in
762 sequence. This field is set for both input and output devices.</entry>
763 </row>
764 <row>
765 <entry spanname="hspan"><para>In <link
766 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
767 bottom field have the same sequence number. The count starts at zero
768 and includes dropped or repeated frames. A dropped frame was received
769 by an input device but could not be stored due to lack of free buffer
770 space. A repeated frame was displayed again by an output device
771 because the application did not pass new data in
772 time.</para><para>Note this may count the frames received
773 e.g. over USB, without taking into account the frames dropped by the
774 remote hardware due to limited compression throughput or bus
775 bandwidth. These devices identify by not enumerating any video
776 standards, see <xref linkend="standard" />.</para></entry>
777 </row>
778 <row>
779 <entry>__u32</entry>
780 <entry><structfield>memory</structfield></entry>
781 <entry></entry>
782 <entry>This field must be set by applications and/or drivers
783 in accordance with the selected I/O method. See <xref linkend="v4l2-memory"
784 /></entry>
785 </row>
786 <row>
787 <entry>union</entry>
788 <entry><structfield>m</structfield></entry>
789 </row>
790 <row>
791 <entry></entry>
792 <entry>__u32</entry>
793 <entry><structfield>offset</structfield></entry>
794 <entry>For the single-planar API and when
795 <structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
796 is the offset of the buffer from the start of the device memory. The value is
797 returned by the driver and apart of serving as parameter to the &func-mmap;
798 function not useful for applications. See <xref linkend="mmap" /> for details
799 </entry>
800 </row>
801 <row>
802 <entry></entry>
803 <entry>unsigned long</entry>
804 <entry><structfield>userptr</structfield></entry>
805 <entry>For the single-planar API and when
806 <structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
807 this is a pointer to the buffer (casted to unsigned long type) in virtual
808 memory, set by the application. See <xref linkend="userp" /> for details.
809 </entry>
810 </row>
811 <row>
812 <entry></entry>
813 <entry>struct v4l2_plane</entry>
814 <entry><structfield>*planes</structfield></entry>
815 <entry>When using the multi-planar API, contains a userspace pointer
816 to an array of &v4l2-plane;. The size of the array should be put
817 in the <structfield>length</structfield> field of this
818 <structname>v4l2_buffer</structname> structure.</entry>
819 </row>
820 <row>
821 <entry></entry>
822 <entry>int</entry>
823 <entry><structfield>fd</structfield></entry>
824 <entry>For the single-plane API and when
825 <structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this
826 is the file descriptor associated with a DMABUF buffer.</entry>
827 </row>
828 <row>
829 <entry>__u32</entry>
830 <entry><structfield>length</structfield></entry>
831 <entry></entry>
832 <entry>Size of the buffer (not the payload) in bytes for the
833 single-planar API. This is set by the driver based on the calls to
834 &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets
835 this to the number of elements in the <structfield>planes</structfield>
836 array. The driver will fill in the actual number of valid elements in
837 that array.
838 </entry>
839 </row>
840 <row>
841 <entry>__u32</entry>
842 <entry><structfield>reserved2</structfield></entry>
843 <entry></entry>
844 <entry>A place holder for future extensions. Applications
845 should set this to 0.</entry>
846 </row>
847 <row>
848 <entry>__u32</entry>
849 <entry><structfield>reserved</structfield></entry>
850 <entry></entry>
851 <entry>A place holder for future extensions. Applications
852 should set this to 0.</entry>
853 </row>
854 </tbody>
855 </tgroup>
856 </table>
858 <table frame="none" pgwide="1" id="v4l2-plane">
859 <title>struct <structname>v4l2_plane</structname></title>
860 <tgroup cols="4">
861 &cs-ustr;
862 <tbody valign="top">
863 <row>
864 <entry>__u32</entry>
865 <entry><structfield>bytesused</structfield></entry>
866 <entry></entry>
867 <entry>The number of bytes occupied by data in the plane
868 (its payload). Drivers must set this field when <structfield>type</structfield>
869 refers to an input stream, applications when it refers to an output stream.
870 If the application sets this to 0 for an output stream, then
871 <structfield>bytesused</structfield> will be set to the size of the
872 plane (see the <structfield>length</structfield> field of this struct)
873 by the driver. Note that the actual image data starts at
874 <structfield>data_offset</structfield> which may not be 0.</entry>
875 </row>
876 <row>
877 <entry>__u32</entry>
878 <entry><structfield>length</structfield></entry>
879 <entry></entry>
880 <entry>Size in bytes of the plane (not its payload). This is set by the driver
881 based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry>
882 </row>
883 <row>
884 <entry>union</entry>
885 <entry><structfield>m</structfield></entry>
886 <entry></entry>
887 <entry></entry>
888 </row>
889 <row>
890 <entry></entry>
891 <entry>__u32</entry>
892 <entry><structfield>mem_offset</structfield></entry>
893 <entry>When the memory type in the containing &v4l2-buffer; is
894 <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
895 should be passed to &func-mmap;, similar to the
896 <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
897 </row>
898 <row>
899 <entry></entry>
900 <entry>unsigned long</entry>
901 <entry><structfield>userptr</structfield></entry>
902 <entry>When the memory type in the containing &v4l2-buffer; is
903 <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
904 pointer to the memory allocated for this plane by an application.
905 </entry>
906 </row>
907 <row>
908 <entry></entry>
909 <entry>int</entry>
910 <entry><structfield>fd</structfield></entry>
911 <entry>When the memory type in the containing &v4l2-buffer; is
912 <constant>V4L2_MEMORY_DMABUF</constant>, this is a file
913 descriptor associated with a DMABUF buffer, similar to the
914 <structfield>fd</structfield> field in &v4l2-buffer;.</entry>
915 </row>
916 <row>
917 <entry>__u32</entry>
918 <entry><structfield>data_offset</structfield></entry>
919 <entry></entry>
920 <entry>Offset in bytes to video data in the plane.
921 Drivers must set this field when <structfield>type</structfield>
922 refers to an input stream, applications when it refers to an output stream.
923 Note that data_offset is included in <structfield>bytesused</structfield>.
924 So the size of the image in the plane is
925 <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at
926 offset <structfield>data_offset</structfield> from the start of the plane.
927 </entry>
928 </row>
929 <row>
930 <entry>__u32</entry>
931 <entry><structfield>reserved[11]</structfield></entry>
932 <entry></entry>
933 <entry>Reserved for future use. Should be zeroed by an
934 application.</entry>
935 </row>
936 </tbody>
937 </tgroup>
938 </table>
940 <table frame="none" pgwide="1" id="v4l2-buf-type">
941 <title>enum v4l2_buf_type</title>
942 <tgroup cols="3">
943 &cs-def;
944 <tbody valign="top">
945 <row>
946 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
947 <entry>1</entry>
948 <entry>Buffer of a single-planar video capture stream, see <xref
949 linkend="capture" />.</entry>
950 </row>
951 <row>
952 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
953 </entry>
954 <entry>9</entry>
955 <entry>Buffer of a multi-planar video capture stream, see <xref
956 linkend="capture" />.</entry>
957 </row>
958 <row>
959 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
960 <entry>2</entry>
961 <entry>Buffer of a single-planar video output stream, see <xref
962 linkend="output" />.</entry>
963 </row>
964 <row>
965 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
966 </entry>
967 <entry>10</entry>
968 <entry>Buffer of a multi-planar video output stream, see <xref
969 linkend="output" />.</entry>
970 </row>
971 <row>
972 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
973 <entry>3</entry>
974 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
975 </row>
976 <row>
977 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
978 <entry>4</entry>
979 <entry>Buffer of a raw VBI capture stream, see <xref
980 linkend="raw-vbi" />.</entry>
981 </row>
982 <row>
983 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
984 <entry>5</entry>
985 <entry>Buffer of a raw VBI output stream, see <xref
986 linkend="raw-vbi" />.</entry>
987 </row>
988 <row>
989 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
990 <entry>6</entry>
991 <entry>Buffer of a sliced VBI capture stream, see <xref
992 linkend="sliced" />.</entry>
993 </row>
994 <row>
995 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
996 <entry>7</entry>
997 <entry>Buffer of a sliced VBI output stream, see <xref
998 linkend="sliced" />.</entry>
999 </row>
1000 <row>
1001 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
1002 <entry>8</entry>
1003 <entry>Buffer for video output overlay (OSD), see <xref
1004 linkend="osd" />.</entry>
1005 </row>
1006 <row>
1007 <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry>
1008 <entry>11</entry>
1009 <entry>Buffer for Software Defined Radio (SDR), see <xref
1010 linkend="sdr" />.</entry>
1011 </row>
1012 </tbody>
1013 </tgroup>
1014 </table>
1016 <table frame="none" pgwide="1" id="buffer-flags">
1017 <title>Buffer Flags</title>
1018 <tgroup cols="3">
1019 &cs-def;
1020 <tbody valign="top">
1021 <row>
1022 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
1023 <entry>0x00000001</entry>
1024 <entry>The buffer resides in device memory and has been mapped
1025 into the application's address space, see <xref linkend="mmap" /> for details.
1026 Drivers set or clear this flag when the
1027 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1028 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1029 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
1030 </row>
1031 <row>
1032 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
1033 <entry>0x00000002</entry>
1034 <entry>Internally drivers maintain two buffer queues, an
1035 incoming and outgoing queue. When this flag is set, the buffer is
1036 currently on the incoming queue. It automatically moves to the
1037 outgoing queue after the buffer has been filled (capture devices) or
1038 displayed (output devices). Drivers set or clear this flag when the
1039 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
1040 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
1041 always set and after <constant>VIDIOC_DQBUF</constant> always
1042 cleared.</entry>
1043 </row>
1044 <row>
1045 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
1046 <entry>0x00000004</entry>
1047 <entry>When this flag is set, the buffer is currently on
1048 the outgoing queue, ready to be dequeued from the driver. Drivers set
1049 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
1050 is called. After calling the <constant>VIDIOC_QBUF</constant> or
1051 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
1052 buffer cannot be on both queues at the same time, the
1053 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
1054 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
1055 They can be both cleared however, then the buffer is in "dequeued"
1056 state, in the application domain so to say.</entry>
1057 </row>
1058 <row>
1059 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
1060 <entry>0x00000040</entry>
1061 <entry>When this flag is set, the buffer has been dequeued
1062 successfully, although the data might have been corrupted.
1063 This is recoverable, streaming may continue as normal and
1064 the buffer may be reused normally.
1065 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
1066 ioctl is called.</entry>
1067 </row>
1068 <row>
1069 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
1070 <entry>0x00000008</entry>
1071 <entry>Drivers set or clear this flag when calling the
1072 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
1073 capture devices when the buffer contains a compressed image which is a
1074 key frame (or field), &ie; can be decompressed on its own. Also known as
1075 an I-frame. Applications can set this bit when <structfield>type</structfield>
1076 refers to an output stream.</entry>
1077 </row>
1078 <row>
1079 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
1080 <entry>0x00000010</entry>
1081 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
1082 this flags predicted frames or fields which contain only differences to a
1083 previous key frame. Applications can set this bit when <structfield>type</structfield>
1084 refers to an output stream.</entry>
1085 </row>
1086 <row>
1087 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
1088 <entry>0x00000020</entry>
1089 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
1090 this flags a bi-directional predicted frame or field which contains only
1091 the differences between the current frame and both the preceding and following
1092 key frames to specify its content. Applications can set this bit when
1093 <structfield>type</structfield> refers to an output stream.</entry>
1094 </row>
1095 <row>
1096 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
1097 <entry>0x00000100</entry>
1098 <entry>The <structfield>timecode</structfield> field is valid.
1099 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
1100 ioctl is called. Applications can set this bit and the corresponding
1101 <structfield>timecode</structfield> structure when <structfield>type</structfield>
1102 refers to an output stream.</entry>
1103 </row>
1104 <row>
1105 <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
1106 <entry>0x00000400</entry>
1107 <entry>The buffer has been prepared for I/O and can be queued by the
1108 application. Drivers set or clear this flag when the
1109 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1110 linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link
1111 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1112 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry>
1113 </row>
1114 <row>
1115 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
1116 <entry>0x00000800</entry>
1117 <entry>Caches do not have to be invalidated for this buffer.
1118 Typically applications shall use this flag if the data captured in the buffer
1119 is not going to be touched by the CPU, instead the buffer will, probably, be
1120 passed on to a DMA-capable hardware unit for further processing or output.
1121 </entry>
1122 </row>
1123 <row>
1124 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
1125 <entry>0x00001000</entry>
1126 <entry>Caches do not have to be cleaned for this buffer.
1127 Typically applications shall use this flag for output buffers if the data
1128 in this buffer has not been created by the CPU but by some DMA-capable unit,
1129 in which case caches have not been used.</entry>
1130 </row>
1131 <row>
1132 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry>
1133 <entry>0x0000e000</entry>
1134 <entry>Mask for timestamp types below. To test the
1135 timestamp type, mask out bits not belonging to timestamp
1136 type by performing a logical and operation with buffer
1137 flags and timestamp mask.</entry>
1138 </row>
1139 <row>
1140 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry>
1141 <entry>0x00000000</entry>
1142 <entry>Unknown timestamp type. This type is used by
1143 drivers before Linux 3.9 and may be either monotonic (see
1144 below) or realtime (wall clock). Monotonic clock has been
1145 favoured in embedded systems whereas most of the drivers
1146 use the realtime clock. Either kinds of timestamps are
1147 available in user space via
1148 <function>clock_gettime(2)</function> using clock IDs
1149 <constant>CLOCK_MONOTONIC</constant> and
1150 <constant>CLOCK_REALTIME</constant>, respectively.</entry>
1151 </row>
1152 <row>
1153 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry>
1154 <entry>0x00002000</entry>
1155 <entry>The buffer timestamp has been taken from the
1156 <constant>CLOCK_MONOTONIC</constant> clock. To access the
1157 same clock outside V4L2, use
1158 <function>clock_gettime(2)</function> .</entry>
1159 </row>
1160 <row>
1161 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry>
1162 <entry>0x00004000</entry>
1163 <entry>The CAPTURE buffer timestamp has been taken from the
1164 corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry>
1165 </row>
1166 <row>
1167 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry>
1168 <entry>0x00070000</entry>
1169 <entry>Mask for timestamp sources below. The timestamp source
1170 defines the point of time the timestamp is taken in relation to
1171 the frame. Logical 'and' operation between the
1172 <structfield>flags</structfield> field and
1173 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the
1174 value of the timestamp source. Applications must set the timestamp
1175 source when <structfield>type</structfield> refers to an output stream
1176 and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry>
1177 </row>
1178 <row>
1179 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>
1180 <entry>0x00000000</entry>
1181 <entry>End Of Frame. The buffer timestamp has been taken
1182 when the last pixel of the frame has been received or the
1183 last pixel of the frame has been transmitted. In practice,
1184 software generated timestamps will typically be read from
1185 the clock a small amount of time after the last pixel has
1186 been received or transmitten, depending on the system and
1187 other activity in it.</entry>
1188 </row>
1189 <row>
1190 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry>
1191 <entry>0x00010000</entry>
1192 <entry>Start Of Exposure. The buffer timestamp has been
1193 taken when the exposure of the frame has begun. This is
1194 only valid for the
1195 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer
1196 type.</entry>
1197 </row>
1198 </tbody>
1199 </tgroup>
1200 </table>
1202 <table pgwide="1" frame="none" id="v4l2-memory">
1203 <title>enum v4l2_memory</title>
1204 <tgroup cols="3">
1205 &cs-def;
1206 <tbody valign="top">
1207 <row>
1208 <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
1209 <entry>1</entry>
1210 <entry>The buffer is used for <link linkend="mmap">memory
1211 mapping</link> I/O.</entry>
1212 </row>
1213 <row>
1214 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
1215 <entry>2</entry>
1216 <entry>The buffer is used for <link linkend="userp">user
1217 pointer</link> I/O.</entry>
1218 </row>
1219 <row>
1220 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
1221 <entry>3</entry>
1222 <entry>[to do]</entry>
1223 </row>
1224 <row>
1225 <entry><constant>V4L2_MEMORY_DMABUF</constant></entry>
1226 <entry>4</entry>
1227 <entry>The buffer is used for <link linkend="dmabuf">DMA shared
1228 buffer</link> I/O.</entry>
1229 </row>
1230 </tbody>
1231 </tgroup>
1232 </table>
1234 <section>
1235 <title>Timecodes</title>
1237 <para>The <structname>v4l2_timecode</structname> structure is
1238 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
1239 (struct <structname>timeval</structname> timestamps are stored in
1240 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
1242 <table frame="none" pgwide="1" id="v4l2-timecode">
1243 <title>struct <structname>v4l2_timecode</structname></title>
1244 <tgroup cols="3">
1245 &cs-str;
1246 <tbody valign="top">
1247 <row>
1248 <entry>__u32</entry>
1249 <entry><structfield>type</structfield></entry>
1250 <entry>Frame rate the timecodes are based on, see <xref
1251 linkend="timecode-type" />.</entry>
1252 </row>
1253 <row>
1254 <entry>__u32</entry>
1255 <entry><structfield>flags</structfield></entry>
1256 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
1257 </row>
1258 <row>
1259 <entry>__u8</entry>
1260 <entry><structfield>frames</structfield></entry>
1261 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
1262 type of timecode.</entry>
1263 </row>
1264 <row>
1265 <entry>__u8</entry>
1266 <entry><structfield>seconds</structfield></entry>
1267 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
1268 </row>
1269 <row>
1270 <entry>__u8</entry>
1271 <entry><structfield>minutes</structfield></entry>
1272 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
1273 </row>
1274 <row>
1275 <entry>__u8</entry>
1276 <entry><structfield>hours</structfield></entry>
1277 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
1278 </row>
1279 <row>
1280 <entry>__u8</entry>
1281 <entry><structfield>userbits</structfield>[4]</entry>
1282 <entry>The "user group" bits from the timecode.</entry>
1283 </row>
1284 </tbody>
1285 </tgroup>
1286 </table>
1288 <table frame="none" pgwide="1" id="timecode-type">
1289 <title>Timecode Types</title>
1290 <tgroup cols="3">
1291 &cs-def;
1292 <tbody valign="top">
1293 <row>
1294 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
1295 <entry>1</entry>
1296 <entry>24 frames per second, i. e. film.</entry>
1297 </row>
1298 <row>
1299 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
1300 <entry>2</entry>
1301 <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
1302 </row>
1303 <row>
1304 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
1305 <entry>3</entry>
1306 <entry>30 frames per second, &ie; NTSC video.</entry>
1307 </row>
1308 <row>
1309 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
1310 <entry>4</entry>
1311 <entry></entry>
1312 </row>
1313 <row>
1314 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
1315 <entry>5</entry>
1316 <entry></entry>
1317 </row>
1318 </tbody>
1319 </tgroup>
1320 </table>
1322 <table frame="none" pgwide="1" id="timecode-flags">
1323 <title>Timecode Flags</title>
1324 <tgroup cols="3">
1325 &cs-def;
1326 <tbody valign="top">
1327 <row>
1328 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
1329 <entry>0x0001</entry>
1330 <entry>Indicates "drop frame" semantics for counting frames
1331 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
1332 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
1333 count.</entry>
1334 </row>
1335 <row>
1336 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
1337 <entry>0x0002</entry>
1338 <entry>The "color frame" flag.</entry>
1339 </row>
1340 <row>
1341 <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
1342 <entry>0x000C</entry>
1343 <entry>Field mask for the "binary group flags".</entry>
1344 </row>
1345 <row>
1346 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
1347 <entry>0x0000</entry>
1348 <entry>Unspecified format.</entry>
1349 </row>
1350 <row>
1351 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
1352 <entry>0x0008</entry>
1353 <entry>8-bit ISO characters.</entry>
1354 </row>
1355 </tbody>
1356 </tgroup>
1357 </table>
1358 </section>
1359 </section>
1361 <section id="field-order">
1362 <title>Field Order</title>
1364 <para>We have to distinguish between progressive and interlaced
1365 video. Progressive video transmits all lines of a video image
1366 sequentially. Interlaced video divides an image into two fields,
1367 containing only the odd and even lines of the image, respectively.
1368 Alternating the so called odd and even field are transmitted, and due
1369 to a small delay between fields a cathode ray TV displays the lines
1370 interleaved, yielding the original frame. This curious technique was
1371 invented because at refresh rates similar to film the image would
1372 fade out too quickly. Transmitting fields reduces the flicker without
1373 the necessity of doubling the frame rate and with it the bandwidth
1374 required for each channel.</para>
1376 <para>It is important to understand a video camera does not expose
1377 one frame at a time, merely transmitting the frames separated into
1378 fields. The fields are in fact captured at two different instances in
1379 time. An object on screen may well move between one field and the
1380 next. For applications analysing motion it is of paramount importance
1381 to recognize which field of a frame is older, the <emphasis>temporal
1382 order</emphasis>.</para>
1384 <para>When the driver provides or accepts images field by field
1385 rather than interleaved, it is also important applications understand
1386 how the fields combine to frames. We distinguish between top (aka odd) and
1387 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
1388 of the top field is the first line of an interlaced frame, the first
1389 line of the bottom field is the second line of that frame.</para>
1391 <para>However because fields were captured one after the other,
1392 arguing whether a frame commences with the top or bottom field is
1393 pointless. Any two successive top and bottom, or bottom and top fields
1394 yield a valid frame. Only when the source was progressive to begin
1395 with, ⪚ when transferring film to video, two fields may come from
1396 the same frame, creating a natural order.</para>
1398 <para>Counter to intuition the top field is not necessarily the
1399 older field. Whether the older field contains the top or bottom lines
1400 is a convention determined by the video standard. Hence the
1401 distinction between temporal and spatial order of fields. The diagrams
1402 below should make this clearer.</para>
1404 <para>All video capture and output devices must report the current
1405 field order. Some drivers may permit the selection of a different
1406 order, to this end applications initialize the
1407 <structfield>field</structfield> field of &v4l2-pix-format; before
1408 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
1409 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
1411 <table frame="none" pgwide="1" id="v4l2-field">
1412 <title>enum v4l2_field</title>
1413 <tgroup cols="3">
1414 &cs-def;
1415 <tbody valign="top">
1416 <row>
1417 <entry><constant>V4L2_FIELD_ANY</constant></entry>
1418 <entry>0</entry>
1419 <entry>Applications request this field order when any
1420 one of the <constant>V4L2_FIELD_NONE</constant>,
1421 <constant>V4L2_FIELD_TOP</constant>,
1422 <constant>V4L2_FIELD_BOTTOM</constant>, or
1423 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
1424 Drivers choose depending on hardware capabilities or e. g. the
1425 requested image size, and return the actual field order. Drivers must
1426 never return <constant>V4L2_FIELD_ANY</constant>. If multiple
1427 field orders are possible the driver must choose one of the possible
1428 field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer;
1429 <structfield>field</structfield> can never be
1430 <constant>V4L2_FIELD_ANY</constant>.</entry>
1431 </row>
1432 <row>
1433 <entry><constant>V4L2_FIELD_NONE</constant></entry>
1434 <entry>1</entry>
1435 <entry>Images are in progressive format, not interlaced.
1436 The driver may also indicate this order when it cannot distinguish
1437 between <constant>V4L2_FIELD_TOP</constant> and
1438 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
1439 </row>
1440 <row>
1441 <entry><constant>V4L2_FIELD_TOP</constant></entry>
1442 <entry>2</entry>
1443 <entry>Images consist of the top (aka odd) field only.</entry>
1444 </row>
1445 <row>
1446 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1447 <entry>3</entry>
1448 <entry>Images consist of the bottom (aka even) field only.
1449 Applications may wish to prevent a device from capturing interlaced
1450 images because they will have "comb" or "feathering" artefacts around
1451 moving objects.</entry>
1452 </row>
1453 <row>
1454 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1455 <entry>4</entry>
1456 <entry>Images contain both fields, interleaved line by
1457 line. The temporal order of the fields (whether the top or bottom
1458 field is first transmitted) depends on the current video standard.
1459 M/NTSC transmits the bottom field first, all other standards the top
1460 field first.</entry>
1461 </row>
1462 <row>
1463 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1464 <entry>5</entry>
1465 <entry>Images contain both fields, the top field lines
1466 are stored first in memory, immediately followed by the bottom field
1467 lines. Fields are always stored in temporal order, the older one first
1468 in memory. Image sizes refer to the frame, not fields.</entry>
1469 </row>
1470 <row>
1471 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1472 <entry>6</entry>
1473 <entry>Images contain both fields, the bottom field
1474 lines are stored first in memory, immediately followed by the top
1475 field lines. Fields are always stored in temporal order, the older one
1476 first in memory. Image sizes refer to the frame, not fields.</entry>
1477 </row>
1478 <row>
1479 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1480 <entry>7</entry>
1481 <entry>The two fields of a frame are passed in separate
1482 buffers, in temporal order, &ie; the older one first. To indicate the field
1483 parity (whether the current field is a top or bottom field) the driver
1484 or application, depending on data direction, must set &v4l2-buffer;
1485 <structfield>field</structfield> to
1486 <constant>V4L2_FIELD_TOP</constant> or
1487 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1488 to build a frame. If fields are successive, without any dropped fields
1489 between them (fields can drop individually), can be determined from
1490 the &v4l2-buffer; <structfield>sequence</structfield> field. This format
1491 cannot be selected when using the read/write I/O method since there
1492 is no way to communicate if a field was a top or bottom field.</entry>
1493 </row>
1494 <row>
1495 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1496 <entry>8</entry>
1497 <entry>Images contain both fields, interleaved line by
1498 line, top field first. The top field is transmitted first.</entry>
1499 </row>
1500 <row>
1501 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1502 <entry>9</entry>
1503 <entry>Images contain both fields, interleaved line by
1504 line, top field first. The bottom field is transmitted first.</entry>
1505 </row>
1506 </tbody>
1507 </tgroup>
1508 </table>
1510 <figure id="fieldseq-tb">
1511 <title>Field Order, Top Field First Transmitted</title>
1512 <mediaobject>
1513 <imageobject>
1514 <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1515 </imageobject>
1516 <imageobject>
1517 <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1518 </imageobject>
1519 </mediaobject>
1520 </figure>
1522 <figure id="fieldseq-bt">
1523 <title>Field Order, Bottom Field First Transmitted</title>
1524 <mediaobject>
1525 <imageobject>
1526 <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1527 </imageobject>
1528 <imageobject>
1529 <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1530 </imageobject>
1531 </mediaobject>
1532 </figure>
1533 </section>