Documentation/DocBook/media/v4l/io.xml

   1   <title>Input/Output</title>
   2
   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>
   6
   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>
  11
  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>
  16
  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>
  21
  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>
  28
  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>
  34
  35   <para>The following sections describe the various I/O methods in
  36 more detail.</para>
  37
  38   <section id="rw">
  39     <title>Read/Write</title>
  40
  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>
  46
  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>
  57
  58     <informalexample>
  59       <screen>
  60 &gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
  61 &gt; dd if=/dev/video of=myimage.422 bs=202752 count=1
  62 </screen>
  63     </informalexample>
  64
  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>
  82
  83   <section id="mmap">
  84     <title>Streaming I/O (Memory Mapping)</title>
  85
  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>
  92
  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>
 101
 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>
 113
 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>
 120
 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>
 137
 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;
 147
 148 memset(&amp;reqbuf, 0, sizeof(reqbuf));
 149 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 150 reqbuf.memory = V4L2_MEMORY_MMAP;
 151 reqbuf.count = 20;
 152
 153 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) {
 154         if (errno == EINVAL)
 155                 printf("Video capturing or mmap-streaming is not supported\n");
 156         else
 157                 perror("VIDIOC_REQBUFS");
 158
 159         exit(EXIT_FAILURE);
 160 }
 161
 162 /* We want at least five buffers. */
 163
 164 if (reqbuf.count &lt; 5) {
 165         /* You may need to free the buffers here. */
 166         printf("Not enough buffer memory\n");
 167         exit(EXIT_FAILURE);
 168 }
 169
 170 buffers = calloc(reqbuf.count, sizeof(*buffers));
 171 assert(buffers != NULL);
 172
 173 for (i = 0; i &lt; reqbuf.count; i++) {
 174         &v4l2-buffer; buffer;
 175
 176         memset(&amp;buffer, 0, sizeof(buffer));
 177         buffer.type = reqbuf.type;
 178         buffer.memory = V4L2_MEMORY_MMAP;
 179         buffer.index = i;
 180
 181         if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) {
 182                 perror("VIDIOC_QUERYBUF");
 183                 exit(EXIT_FAILURE);
 184         }
 185
 186         buffers[i].length = buffer.length; /* remember for munmap() */
 187
 188         buffers[i].start = mmap(NULL, buffer.length,
 189                                 PROT_READ | PROT_WRITE, /* recommended */
 190                                 MAP_SHARED,             /* recommended */
 191                                 fd, buffer.m.offset);
 192
 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 }
 200
 201 /* Cleanup. */
 202
 203 for (i = 0; i &lt; reqbuf.count; i++)
 204         munmap(buffers[i].start, buffers[i].length);
 205       </programlisting>
 206     </example>
 207
 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
 214
 215 struct {
 216         void *start[FMT_NUM_PLANES];
 217         size_t length[FMT_NUM_PLANES];
 218 } *buffers;
 219 unsigned int i, j;
 220
 221 memset(&amp;reqbuf, 0, sizeof(reqbuf));
 222 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
 223 reqbuf.memory = V4L2_MEMORY_MMAP;
 224 reqbuf.count = 20;
 225
 226 if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) &lt; 0) {
 227         if (errno == EINVAL)
 228                 printf("Video capturing or mmap-streaming is not supported\n");
 229         else
 230                 perror("VIDIOC_REQBUFS");
 231
 232         exit(EXIT_FAILURE);
 233 }
 234
 235 /* We want at least five buffers. */
 236
 237 if (reqbuf.count &lt; 5) {
 238         /* You may need to free the buffers here. */
 239         printf("Not enough buffer memory\n");
 240         exit(EXIT_FAILURE);
 241 }
 242
 243 buffers = calloc(reqbuf.count, sizeof(*buffers));
 244 assert(buffers != NULL);
 245
 246 for (i = 0; i &lt; reqbuf.count; i++) {
 247         &v4l2-buffer; buffer;
 248         &v4l2-plane; planes[FMT_NUM_PLANES];
 249
 250         memset(&amp;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;
 258
 259         if (ioctl(fd, &VIDIOC-QUERYBUF;, &amp;buffer) &lt; 0) {
 260                 perror("VIDIOC_QUERYBUF");
 261                 exit(EXIT_FAILURE);
 262         }
 263
 264         /* Every plane has to be mapped separately */
 265         for (j = 0; j &lt; FMT_NUM_PLANES; j++) {
 266                 buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
 267
 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);
 272
 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 }
 281
 282 /* Cleanup. */
 283
 284 for (i = 0; i &lt; reqbuf.count; i++)
 285         for (j = 0; j &lt; FMT_NUM_PLANES; j++)
 286                 munmap(buffers[i].start[j], buffers[i].length[j]);
 287       </programlisting>
 288     </example>
 289
 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>
 298
 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>
 313
 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>
 324
 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>
 335
 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>
 344
 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>
 359
 360     <para>[capture example]</para>
 361
 362   </section>
 363
 364   <section id="userp">
 365     <title>Streaming I/O (User Pointers)</title>
 366
 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>
 373
 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>
 383
 384     <example>
 385       <title>Initiating streaming I/O with user pointers</title>
 386
 387       <programlisting>
 388 &v4l2-requestbuffers; reqbuf;
 389
 390 memset (&amp;reqbuf, 0, sizeof (reqbuf));
 391 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 392 reqbuf.memory = V4L2_MEMORY_USERPTR;
 393
 394 if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
 395         if (errno == EINVAL)
 396                 printf ("Video capturing or user pointer streaming is not supported\n");
 397         else
 398                 perror ("VIDIOC_REQBUFS");
 399
 400         exit (EXIT_FAILURE);
 401 }
 402       </programlisting>
 403     </example>
 404
 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>
 426
 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>
 437
 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>
 452
 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>
 461
 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>
 474
 475   <section id="dmabuf">
 476     <title>Streaming I/O (DMA buffer importing)</title>
 477
 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>
 483
 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>
 490
 491     <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for
 492 details about exporting V4L2 buffers as DMABUF file descriptors.</para>
 493
 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>
 501
 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>
 511
 512     <example>
 513       <title>Initiating streaming I/O with DMABUF file descriptors</title>
 514
 515       <programlisting>
 516 &v4l2-requestbuffers; reqbuf;
 517
 518 memset(&amp;reqbuf, 0, sizeof (reqbuf));
 519 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 520 reqbuf.memory = V4L2_MEMORY_DMABUF;
 521 reqbuf.count = 1;
 522
 523 if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
 524         if (errno == EINVAL)
 525                 printf("Video capturing or DMABUF streaming is not supported\n");
 526         else
 527                 perror("VIDIOC_REQBUFS");
 528
 529         exit(EXIT_FAILURE);
 530 }
 531       </programlisting>
 532     </example>
 533
 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>
 539
 540     <example>
 541       <title>Queueing DMABUF using single plane API</title>
 542
 543       <programlisting>
 544 int buffer_queue(int v4lfd, int index, int dmafd)
 545 {
 546         &v4l2-buffer; buf;
 547
 548         memset(&amp;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;
 553
 554         if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {
 555                 perror("VIDIOC_QBUF");
 556                 return -1;
 557         }
 558
 559         return 0;
 560 }
 561       </programlisting>
 562     </example>
 563
 564     <example>
 565       <title>Queueing DMABUF using multi plane API</title>
 566
 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;
 573
 574         memset(&amp;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;
 580
 581         memset(&amp;planes, 0, sizeof planes);
 582
 583         for (i = 0; i &lt; n_planes; ++i)
 584                 buf.m.planes[i].m.fd = dmafd[i];
 585
 586         if (ioctl(v4lfd, &VIDIOC-QBUF;, &amp;buf) == -1) {
 587                 perror("VIDIOC_QBUF");
 588                 return -1;
 589         }
 590
 591         return 0;
 592 }
 593       </programlisting>
 594     </example>
 595
 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>
 601
 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>
 616
 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>
 624
 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>
 630
 631   </section>
 632
 633   <section id="async">
 634     <title>Asynchronous I/O</title>
 635
 636     <para>This method is not defined yet.</para>
 637   </section>
 638
 639   <section id="buffer">
 640     <title>Buffers</title>
 641
 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>
 655
 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>
 669
 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. Drivers and applications
 845 must 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. Drivers and applications
 852 must set this to 0.</entry>
 853           </row>
 854         </tbody>
 855       </tgroup>
 856     </table>
 857
 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 drivers and
 934             applications.</entry>
 935           </row>
 936         </tbody>
 937       </tgroup>
 938     </table>
 939
 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) capture stream, see
1010                 <xref linkend="sdr" />.</entry>
1011           </row>
1012           <row>
1013             <entry><constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant></entry>
1014             <entry>12</entry>
1015             <entry>Buffer for Software Defined Radio (SDR) output stream, see
1016                 <xref linkend="sdr" />.</entry>
1017           </row>
1018         </tbody>
1019       </tgroup>
1020     </table>
1021
1022     <table frame="none" pgwide="1" id="buffer-flags">
1023       <title>Buffer Flags</title>
1024       <tgroup cols="3">
1025         &cs-def;
1026         <tbody valign="top">
1027           <row>
1028             <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
1029             <entry>0x00000001</entry>
1030             <entry>The buffer resides in device memory and has been mapped
1031 into the application's address space, see <xref linkend="mmap" /> for details.
1032 Drivers set or clear this flag when the
1033 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1034           linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1035           linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
1036           </row>
1037           <row>
1038             <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
1039             <entry>0x00000002</entry>
1040           <entry>Internally drivers maintain two buffer queues, an
1041 incoming and outgoing queue. When this flag is set, the buffer is
1042 currently on the incoming queue. It automatically moves to the
1043 outgoing queue after the buffer has been filled (capture devices) or
1044 displayed (output devices). Drivers set or clear this flag when the
1045 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
1046 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
1047 always set and after <constant>VIDIOC_DQBUF</constant> always
1048 cleared.</entry>
1049           </row>
1050           <row>
1051             <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
1052             <entry>0x00000004</entry>
1053             <entry>When this flag is set, the buffer is currently on
1054 the outgoing queue, ready to be dequeued from the driver. Drivers set
1055 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
1056 is called. After calling the <constant>VIDIOC_QBUF</constant> or
1057 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
1058 buffer cannot be on both queues at the same time, the
1059 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
1060 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
1061 They can be both cleared however, then the buffer is in "dequeued"
1062 state, in the application domain so to say.</entry>
1063           </row>
1064           <row>
1065             <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
1066             <entry>0x00000040</entry>
1067             <entry>When this flag is set, the buffer has been dequeued
1068             successfully, although the data might have been corrupted.
1069             This is recoverable, streaming may continue as normal and
1070             the buffer may be reused normally.
1071             Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
1072             ioctl is called.</entry>
1073           </row>
1074           <row>
1075             <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
1076             <entry>0x00000008</entry>
1077           <entry>Drivers set or clear this flag when calling the
1078 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
1079 capture devices when the buffer contains a compressed image which is a
1080 key frame (or field), &ie; can be decompressed on its own. Also known as
1081 an I-frame.  Applications can set this bit when <structfield>type</structfield>
1082 refers to an output stream.</entry>
1083           </row>
1084           <row>
1085             <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
1086             <entry>0x00000010</entry>
1087             <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
1088 this flags predicted frames or fields which contain only differences to a
1089 previous key frame. Applications can set this bit when <structfield>type</structfield>
1090 refers to an output stream.</entry>
1091           </row>
1092           <row>
1093             <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
1094             <entry>0x00000020</entry>
1095             <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
1096 this flags a bi-directional predicted frame or field which contains only
1097 the differences between the current frame and both the preceding and following
1098 key frames to specify its content. Applications can set this bit when
1099 <structfield>type</structfield> refers to an output stream.</entry>
1100           </row>
1101           <row>
1102             <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
1103             <entry>0x00000100</entry>
1104             <entry>The <structfield>timecode</structfield> field is valid.
1105 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
1106 ioctl is called.  Applications can set this bit and the corresponding
1107 <structfield>timecode</structfield> structure when <structfield>type</structfield>
1108 refers to an output stream.</entry>
1109           </row>
1110           <row>
1111             <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
1112             <entry>0x00000400</entry>
1113             <entry>The buffer has been prepared for I/O and can be queued by the
1114 application. Drivers set or clear this flag when the
1115 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1116           linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link
1117           linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1118           linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry>
1119           </row>
1120           <row>
1121             <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
1122             <entry>0x00000800</entry>
1123             <entry>Caches do not have to be invalidated for this buffer.
1124 Typically applications shall use this flag if the data captured in the buffer
1125 is not going to be touched by the CPU, instead the buffer will, probably, be
1126 passed on to a DMA-capable hardware unit for further processing or output.
1127 </entry>
1128           </row>
1129           <row>
1130             <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
1131             <entry>0x00001000</entry>
1132             <entry>Caches do not have to be cleaned for this buffer.
1133 Typically applications shall use this flag for output buffers if the data
1134 in this buffer has not been created by the CPU but by some DMA-capable unit,
1135 in which case caches have not been used.</entry>
1136           </row>
1137           <row>
1138             <entry><constant>V4L2_BUF_FLAG_LAST</constant></entry>
1139             <entry>0x00100000</entry>
1140             <entry>Last buffer produced by the hardware. mem2mem codec drivers
1141 set this flag on the capture queue for the last buffer when the
1142 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link> or
1143 <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Due to hardware
1144 limitations, the last buffer may be empty. In this case the driver will set the
1145 <structfield>bytesused</structfield> field to 0, regardless of the format. Any
1146 Any subsequent call to the <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl
1147 will not block anymore, but return an &EPIPE;.</entry>
1148           </row>
1149           <row>
1150             <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry>
1151             <entry>0x0000e000</entry>
1152             <entry>Mask for timestamp types below. To test the
1153             timestamp type, mask out bits not belonging to timestamp
1154             type by performing a logical and operation with buffer
1155             flags and timestamp mask.</entry>
1156           </row>
1157           <row>
1158             <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry>
1159             <entry>0x00000000</entry>
1160             <entry>Unknown timestamp type. This type is used by
1161             drivers before Linux 3.9 and may be either monotonic (see
1162             below) or realtime (wall clock). Monotonic clock has been
1163             favoured in embedded systems whereas most of the drivers
1164             use the realtime clock. Either kinds of timestamps are
1165             available in user space via
1166             <function>clock_gettime(2)</function> using clock IDs
1167             <constant>CLOCK_MONOTONIC</constant> and
1168             <constant>CLOCK_REALTIME</constant>, respectively.</entry>
1169           </row>
1170           <row>
1171             <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry>
1172             <entry>0x00002000</entry>
1173             <entry>The buffer timestamp has been taken from the
1174             <constant>CLOCK_MONOTONIC</constant> clock. To access the
1175             same clock outside V4L2, use
1176             <function>clock_gettime(2)</function>.</entry>
1177           </row>
1178           <row>
1179             <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry>
1180             <entry>0x00004000</entry>
1181             <entry>The CAPTURE buffer timestamp has been taken from the
1182             corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry>
1183           </row>
1184           <row>
1185             <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry>
1186             <entry>0x00070000</entry>
1187             <entry>Mask for timestamp sources below. The timestamp source
1188             defines the point of time the timestamp is taken in relation to
1189             the frame. Logical 'and' operation between the
1190             <structfield>flags</structfield> field and
1191             <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the
1192             value of the timestamp source. Applications must set the timestamp
1193             source when <structfield>type</structfield> refers to an output stream
1194             and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry>
1195           </row>
1196           <row>
1197             <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry>
1198             <entry>0x00000000</entry>
1199             <entry>End Of Frame. The buffer timestamp has been taken
1200             when the last pixel of the frame has been received or the
1201             last pixel of the frame has been transmitted. In practice,
1202             software generated timestamps will typically be read from
1203             the clock a small amount of time after the last pixel has
1204             been received or transmitten, depending on the system and
1205             other activity in it.</entry>
1206           </row>
1207           <row>
1208             <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry>
1209             <entry>0x00010000</entry>
1210             <entry>Start Of Exposure. The buffer timestamp has been
1211             taken when the exposure of the frame has begun. This is
1212             only valid for the
1213             <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer
1214             type.</entry>
1215           </row>
1216         </tbody>
1217       </tgroup>
1218     </table>
1219
1220     <table pgwide="1" frame="none" id="v4l2-memory">
1221       <title>enum v4l2_memory</title>
1222       <tgroup cols="3">
1223         &cs-def;
1224         <tbody valign="top">
1225           <row>
1226             <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
1227             <entry>1</entry>
1228             <entry>The buffer is used for <link linkend="mmap">memory
1229 mapping</link> I/O.</entry>
1230           </row>
1231           <row>
1232             <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
1233             <entry>2</entry>
1234             <entry>The buffer is used for <link linkend="userp">user
1235 pointer</link> I/O.</entry>
1236           </row>
1237           <row>
1238             <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
1239             <entry>3</entry>
1240             <entry>[to do]</entry>
1241           </row>
1242           <row>
1243             <entry><constant>V4L2_MEMORY_DMABUF</constant></entry>
1244             <entry>4</entry>
1245             <entry>The buffer is used for <link linkend="dmabuf">DMA shared
1246 buffer</link> I/O.</entry>
1247           </row>
1248         </tbody>
1249       </tgroup>
1250     </table>
1251
1252     <section>
1253       <title>Timecodes</title>
1254
1255       <para>The <structname>v4l2_timecode</structname> structure is
1256 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
1257 (struct <structname>timeval</structname> timestamps are stored in
1258 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
1259
1260       <table frame="none" pgwide="1" id="v4l2-timecode">
1261         <title>struct <structname>v4l2_timecode</structname></title>
1262         <tgroup cols="3">
1263           &cs-str;
1264           <tbody valign="top">
1265             <row>
1266               <entry>__u32</entry>
1267               <entry><structfield>type</structfield></entry>
1268               <entry>Frame rate the timecodes are based on, see <xref
1269                   linkend="timecode-type" />.</entry>
1270             </row>
1271             <row>
1272               <entry>__u32</entry>
1273               <entry><structfield>flags</structfield></entry>
1274               <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
1275             </row>
1276             <row>
1277               <entry>__u8</entry>
1278               <entry><structfield>frames</structfield></entry>
1279               <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
1280             type of timecode.</entry>
1281             </row>
1282             <row>
1283               <entry>__u8</entry>
1284               <entry><structfield>seconds</structfield></entry>
1285               <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
1286             </row>
1287             <row>
1288               <entry>__u8</entry>
1289               <entry><structfield>minutes</structfield></entry>
1290               <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
1291             </row>
1292             <row>
1293               <entry>__u8</entry>
1294               <entry><structfield>hours</structfield></entry>
1295               <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
1296             </row>
1297             <row>
1298               <entry>__u8</entry>
1299               <entry><structfield>userbits</structfield>[4]</entry>
1300               <entry>The "user group" bits from the timecode.</entry>
1301             </row>
1302           </tbody>
1303         </tgroup>
1304       </table>
1305
1306       <table frame="none" pgwide="1" id="timecode-type">
1307         <title>Timecode Types</title>
1308         <tgroup cols="3">
1309         &cs-def;
1310           <tbody valign="top">
1311             <row>
1312               <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
1313               <entry>1</entry>
1314               <entry>24 frames per second, i.&nbsp;e. film.</entry>
1315             </row>
1316             <row>
1317               <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
1318               <entry>2</entry>
1319               <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
1320             </row>
1321             <row>
1322               <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
1323               <entry>3</entry>
1324               <entry>30 frames per second, &ie; NTSC video.</entry>
1325             </row>
1326             <row>
1327               <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
1328               <entry>4</entry>
1329               <entry></entry>
1330             </row>
1331             <row>
1332               <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
1333               <entry>5</entry>
1334               <entry></entry>
1335             </row>
1336           </tbody>
1337         </tgroup>
1338       </table>
1339
1340       <table frame="none" pgwide="1" id="timecode-flags">
1341         <title>Timecode Flags</title>
1342         <tgroup cols="3">
1343         &cs-def;
1344           <tbody valign="top">
1345             <row>
1346               <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
1347               <entry>0x0001</entry>
1348               <entry>Indicates "drop frame" semantics for counting frames
1349 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
1350 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
1351 count.</entry>
1352             </row>
1353             <row>
1354               <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
1355               <entry>0x0002</entry>
1356               <entry>The "color frame" flag.</entry>
1357             </row>
1358             <row>
1359               <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
1360               <entry>0x000C</entry>
1361               <entry>Field mask for the "binary group flags".</entry>
1362             </row>
1363             <row>
1364               <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
1365               <entry>0x0000</entry>
1366               <entry>Unspecified format.</entry>
1367             </row>
1368             <row>
1369               <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
1370               <entry>0x0008</entry>
1371               <entry>8-bit ISO characters.</entry>
1372             </row>
1373           </tbody>
1374         </tgroup>
1375       </table>
1376     </section>
1377   </section>
1378
1379   <section id="field-order">
1380     <title>Field Order</title>
1381
1382     <para>We have to distinguish between progressive and interlaced
1383 video. Progressive video transmits all lines of a video image
1384 sequentially. Interlaced video divides an image into two fields,
1385 containing only the odd and even lines of the image, respectively.
1386 Alternating the so called odd and even field are transmitted, and due
1387 to a small delay between fields a cathode ray TV displays the lines
1388 interleaved, yielding the original frame. This curious technique was
1389 invented because at refresh rates similar to film the image would
1390 fade out too quickly. Transmitting fields reduces the flicker without
1391 the necessity of doubling the frame rate and with it the bandwidth
1392 required for each channel.</para>
1393
1394     <para>It is important to understand a video camera does not expose
1395 one frame at a time, merely transmitting the frames separated into
1396 fields. The fields are in fact captured at two different instances in
1397 time. An object on screen may well move between one field and the
1398 next. For applications analysing motion it is of paramount importance
1399 to recognize which field of a frame is older, the <emphasis>temporal
1400 order</emphasis>.</para>
1401
1402     <para>When the driver provides or accepts images field by field
1403 rather than interleaved, it is also important applications understand
1404 how the fields combine to frames. We distinguish between top (aka odd) and
1405 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
1406 of the top field is the first line of an interlaced frame, the first
1407 line of the bottom field is the second line of that frame.</para>
1408
1409     <para>However because fields were captured one after the other,
1410 arguing whether a frame commences with the top or bottom field is
1411 pointless. Any two successive top and bottom, or bottom and top fields
1412 yield a valid frame. Only when the source was progressive to begin
1413 with, &eg; when transferring film to video, two fields may come from
1414 the same frame, creating a natural order.</para>
1415
1416     <para>Counter to intuition the top field is not necessarily the
1417 older field. Whether the older field contains the top or bottom lines
1418 is a convention determined by the video standard. Hence the
1419 distinction between temporal and spatial order of fields. The diagrams
1420 below should make this clearer.</para>
1421
1422     <para>All video capture and output devices must report the current
1423 field order. Some drivers may permit the selection of a different
1424 order, to this end applications initialize the
1425 <structfield>field</structfield> field of &v4l2-pix-format; before
1426 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
1427 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
1428
1429     <table frame="none" pgwide="1" id="v4l2-field">
1430       <title>enum v4l2_field</title>
1431       <tgroup cols="3">
1432         &cs-def;
1433         <tbody valign="top">
1434           <row>
1435             <entry><constant>V4L2_FIELD_ANY</constant></entry>
1436             <entry>0</entry>
1437             <entry>Applications request this field order when any
1438 one of the <constant>V4L2_FIELD_NONE</constant>,
1439 <constant>V4L2_FIELD_TOP</constant>,
1440 <constant>V4L2_FIELD_BOTTOM</constant>, or
1441 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
1442 Drivers choose depending on hardware capabilities or e.&nbsp;g. the
1443 requested image size, and return the actual field order. Drivers must
1444 never return <constant>V4L2_FIELD_ANY</constant>. If multiple
1445 field orders are possible the driver must choose one of the possible
1446 field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer;
1447 <structfield>field</structfield> can never be
1448 <constant>V4L2_FIELD_ANY</constant>.</entry>
1449           </row>
1450           <row>
1451             <entry><constant>V4L2_FIELD_NONE</constant></entry>
1452             <entry>1</entry>
1453             <entry>Images are in progressive format, not interlaced.
1454 The driver may also indicate this order when it cannot distinguish
1455 between <constant>V4L2_FIELD_TOP</constant> and
1456 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
1457           </row>
1458           <row>
1459             <entry><constant>V4L2_FIELD_TOP</constant></entry>
1460             <entry>2</entry>
1461             <entry>Images consist of the top (aka odd) field only.</entry>
1462           </row>
1463           <row>
1464             <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1465             <entry>3</entry>
1466             <entry>Images consist of the bottom (aka even) field only.
1467 Applications may wish to prevent a device from capturing interlaced
1468 images because they will have "comb" or "feathering" artefacts around
1469 moving objects.</entry>
1470           </row>
1471           <row>
1472             <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1473             <entry>4</entry>
1474             <entry>Images contain both fields, interleaved line by
1475 line. The temporal order of the fields (whether the top or bottom
1476 field is first transmitted) depends on the current video standard.
1477 M/NTSC transmits the bottom field first, all other standards the top
1478 field first.</entry>
1479           </row>
1480           <row>
1481             <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1482             <entry>5</entry>
1483             <entry>Images contain both fields, the top field lines
1484 are stored first in memory, immediately followed by the bottom field
1485 lines. Fields are always stored in temporal order, the older one first
1486 in memory. Image sizes refer to the frame, not fields.</entry>
1487           </row>
1488           <row>
1489             <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1490             <entry>6</entry>
1491             <entry>Images contain both fields, the bottom field
1492 lines are stored first in memory, immediately followed by the top
1493 field lines. Fields are always stored in temporal order, the older one
1494 first in memory. Image sizes refer to the frame, not fields.</entry>
1495           </row>
1496           <row>
1497             <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1498             <entry>7</entry>
1499             <entry>The two fields of a frame are passed in separate
1500 buffers, in temporal order, &ie; the older one first. To indicate the field
1501 parity (whether the current field is a top or bottom field) the driver
1502 or application, depending on data direction, must set &v4l2-buffer;
1503 <structfield>field</structfield> to
1504 <constant>V4L2_FIELD_TOP</constant> or
1505 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1506 to build a frame. If fields are successive, without any dropped fields
1507 between them (fields can drop individually), can be determined from
1508 the &v4l2-buffer; <structfield>sequence</structfield> field. This format
1509 cannot be selected when using the read/write I/O method since there
1510 is no way to communicate if a field was a top or bottom field.</entry>
1511           </row>
1512           <row>
1513             <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1514             <entry>8</entry>
1515             <entry>Images contain both fields, interleaved line by
1516 line, top field first. The top field is transmitted first.</entry>
1517           </row>
1518           <row>
1519             <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1520             <entry>9</entry>
1521             <entry>Images contain both fields, interleaved line by
1522 line, top field first. The bottom field is transmitted first.</entry>
1523           </row>
1524         </tbody>
1525       </tgroup>
1526     </table>
1527
1528     <figure id="fieldseq-tb">
1529         <title>Field Order, Top Field First Transmitted</title>
1530         <mediaobject>
1531           <imageobject>
1532             <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1533           </imageobject>
1534           <imageobject>
1535             <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1536           </imageobject>
1537         </mediaobject>
1538     </figure>
1539
1540     <figure id="fieldseq-bt">
1541         <title>Field Order, Bottom Field First Transmitted</title>
1542         <mediaobject>
1543           <imageobject>
1544             <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1545           </imageobject>
1546           <imageobject>
1547             <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1548           </imageobject>
1549         </mediaobject>
1550     </figure>
1551   </section>