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 struct &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 buffers, or set the
 343 field before enqueuing buffers for output.</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 buffers, or set the field before enqueuing buffers for output.</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 linked="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 buffers, or set the field
 624 before enqueuing buffers for output.</para>
 625
 626     <para>Drivers implementing DMABUF importing I/O must support the
 627 <constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>,
 628 <constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and
 629 <constant>VIDIOC_STREAMOFF</constant> ioctls, and the
 630 <function>select()</function> and <function>poll()</function> functions.</para>
 631
 632   </section>
 633
 634   <section id="async">
 635     <title>Asynchronous I/O</title>
 636
 637     <para>This method is not defined yet.</para>
 638   </section>
 639
 640   <section id="buffer">
 641     <title>Buffers</title>
 642
 643     <para>A buffer contains data exchanged by application and
 644 driver using one of the Streaming I/O methods. In the multi-planar API, the
 645 data is held in planes, while the buffer structure acts as a container
 646 for the planes. Only pointers to buffers (planes) are exchanged, the data
 647 itself is not copied. These pointers, together with meta-information like
 648 timestamps or field parity, are stored in a struct
 649 <structname>v4l2_buffer</structname>, argument to
 650 the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
 651 In the multi-planar API, some plane-specific members of struct
 652 <structname>v4l2_buffer</structname>, such as pointers and sizes for each
 653 plane, are stored in struct <structname>v4l2_plane</structname> instead.
 654 In that case, struct <structname>v4l2_buffer</structname> contains an array of
 655 plane structures.</para>
 656
 657       <para>Nominally timestamps refer to the first data byte transmitted.
 658 In practice however the wide range of hardware covered by the V4L2 API
 659 limits timestamp accuracy. Often an interrupt routine will
 660 sample the system clock shortly after the field or frame was stored
 661 completely in memory. So applications must expect a constant
 662 difference up to one field or frame period plus a small (few scan
 663 lines) random error. The delay and error can be much
 664 larger due to compression or transmission over an external bus when
 665 the frames are not properly stamped by the sender. This is frequently
 666 the case with USB cameras. Here timestamps refer to the instant the
 667 field or frame was received by the driver, not the capture time. These
 668 devices identify by not enumerating any video standards, see <xref
 669 linkend="standard" />.</para>
 670
 671       <para>Similar limitations apply to output timestamps. Typically
 672 the video hardware locks to a clock controlling the video timing, the
 673 horizontal and vertical synchronization pulses. At some point in the
 674 line sequence, possibly the vertical blanking, an interrupt routine
 675 samples the system clock, compares against the timestamp and programs
 676 the hardware to repeat the previous field or frame, or to display the
 677 buffer contents.</para>
 678
 679       <para>Apart of limitations of the video device and natural
 680 inaccuracies of all clocks, it should be noted system time itself is
 681 not perfectly stable. It can be affected by power saving cycles,
 682 warped to insert leap seconds, or even turned back or forth by the
 683 system administrator affecting long term measurements. <footnote>
 684           <para>Since no other Linux multimedia
 685 API supports unadjusted time it would be foolish to introduce here. We
 686 must use a universally supported clock to synchronize different media,
 687 hence time of day.</para>
 688         </footnote></para>
 689
 690     <table frame="none" pgwide="1" id="v4l2-buffer">
 691       <title>struct <structname>v4l2_buffer</structname></title>
 692       <tgroup cols="4">
 693         &cs-ustr;
 694         <tbody valign="top">
 695           <row>
 696             <entry>__u32</entry>
 697             <entry><structfield>index</structfield></entry>
 698             <entry></entry>
 699             <entry>Number of the buffer, set by the application. This
 700 field is only used for <link linkend="mmap">memory mapping</link> I/O
 701 and can range from zero to the number of buffers allocated
 702 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
 703           </row>
 704           <row>
 705             <entry>__u32</entry>
 706             <entry><structfield>type</structfield></entry>
 707             <entry></entry>
 708             <entry>Type of the buffer, same as &v4l2-format;
 709 <structfield>type</structfield> or &v4l2-requestbuffers;
 710 <structfield>type</structfield>, set by the application. See <xref
 711 linkend="v4l2-buf-type" /></entry>
 712           </row>
 713           <row>
 714             <entry>__u32</entry>
 715             <entry><structfield>bytesused</structfield></entry>
 716             <entry></entry>
 717             <entry>The number of bytes occupied by the data in the
 718 buffer. It depends on the negotiated data format and may change with
 719 each buffer for compressed variable size data like JPEG images.
 720 Drivers must set this field when <structfield>type</structfield>
 721 refers to an input stream, applications when an output stream.</entry>
 722           </row>
 723           <row>
 724             <entry>__u32</entry>
 725             <entry><structfield>flags</structfield></entry>
 726             <entry></entry>
 727             <entry>Flags set by the application or driver, see <xref
 728 linkend="buffer-flags" />.</entry>
 729           </row>
 730           <row>
 731             <entry>__u32</entry>
 732             <entry><structfield>field</structfield></entry>
 733             <entry></entry>
 734             <entry>Indicates the field order of the image in the
 735 buffer, see <xref linkend="v4l2-field" />. This field is not used when
 736 the buffer contains VBI data. Drivers must set it when
 737 <structfield>type</structfield> refers to an input stream,
 738 applications when an output stream.</entry>
 739           </row>
 740           <row>
 741             <entry>struct timeval</entry>
 742             <entry><structfield>timestamp</structfield></entry>
 743             <entry></entry>
 744             <entry><para>For input streams this is the
 745 system time (as returned by the <function>gettimeofday()</function>
 746 function) when the first data byte was captured. For output streams
 747 the data will not be displayed before this time, secondary to the
 748 nominal frame rate determined by the current video standard in
 749 enqueued order. Applications can for example zero this field to
 750 display frames as soon as possible. The driver stores the time at
 751 which the first data byte was actually sent out in the
 752 <structfield>timestamp</structfield> field. This permits
 753 applications to monitor the drift between the video and system
 754 clock.</para></entry>
 755           </row>
 756           <row>
 757             <entry>&v4l2-timecode;</entry>
 758             <entry><structfield>timecode</structfield></entry>
 759             <entry></entry>
 760             <entry>When <structfield>type</structfield> is
 761 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
 762 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
 763 <structfield>flags</structfield>, this structure contains a frame
 764 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
 765 mode the top and bottom field contain the same timecode.
 766 Timecodes are intended to help video editing and are typically recorded on
 767 video tapes, but also embedded in compressed formats like MPEG. This
 768 field is independent of the <structfield>timestamp</structfield> and
 769 <structfield>sequence</structfield> fields.</entry>
 770           </row>
 771           <row>
 772             <entry>__u32</entry>
 773             <entry><structfield>sequence</structfield></entry>
 774             <entry></entry>
 775             <entry>Set by the driver, counting the frames (not fields!) in
 776 sequence. This field is set for both input and output devices.</entry>
 777           </row>
 778           <row>
 779             <entry spanname="hspan"><para>In <link
 780 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
 781 bottom field have the same sequence number. The count starts at zero
 782 and includes dropped or repeated frames. A dropped frame was received
 783 by an input device but could not be stored due to lack of free buffer
 784 space. A repeated frame was displayed again by an output device
 785 because the application did not pass new data in
 786 time.</para><para>Note this may count the frames received
 787 e.g. over USB, without taking into account the frames dropped by the
 788 remote hardware due to limited compression throughput or bus
 789 bandwidth. These devices identify by not enumerating any video
 790 standards, see <xref linkend="standard" />.</para></entry>
 791           </row>
 792           <row>
 793             <entry>__u32</entry>
 794             <entry><structfield>memory</structfield></entry>
 795             <entry></entry>
 796             <entry>This field must be set by applications and/or drivers
 797 in accordance with the selected I/O method. See <xref linkend="v4l2-memory"
 798             /></entry>
 799           </row>
 800           <row>
 801             <entry>union</entry>
 802             <entry><structfield>m</structfield></entry>
 803           </row>
 804           <row>
 805             <entry></entry>
 806             <entry>__u32</entry>
 807             <entry><structfield>offset</structfield></entry>
 808             <entry>For the single-planar API and when
 809 <structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
 810 is the offset of the buffer from the start of the device memory. The value is
 811 returned by the driver and apart of serving as parameter to the &func-mmap;
 812 function not useful for applications. See <xref linkend="mmap" /> for details
 813           </entry>
 814           </row>
 815           <row>
 816             <entry></entry>
 817             <entry>unsigned long</entry>
 818             <entry><structfield>userptr</structfield></entry>
 819             <entry>For the single-planar API and when
 820 <structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
 821 this is a pointer to the buffer (casted to unsigned long type) in virtual
 822 memory, set by the application. See <xref linkend="userp" /> for details.
 823             </entry>
 824           </row>
 825           <row>
 826             <entry></entry>
 827             <entry>struct v4l2_plane</entry>
 828             <entry><structfield>*planes</structfield></entry>
 829             <entry>When using the multi-planar API, contains a userspace pointer
 830             to an array of &v4l2-plane;. The size of the array should be put
 831             in the <structfield>length</structfield> field of this
 832             <structname>v4l2_buffer</structname> structure.</entry>
 833           </row>
 834           <row>
 835             <entry></entry>
 836             <entry>int</entry>
 837             <entry><structfield>fd</structfield></entry>
 838             <entry>For the single-plane API and when
 839 <structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this
 840 is the file descriptor associated with a DMABUF buffer.</entry>
 841           </row>
 842           <row>
 843             <entry>__u32</entry>
 844             <entry><structfield>length</structfield></entry>
 845             <entry></entry>
 846             <entry>Size of the buffer (not the payload) in bytes for the
 847             single-planar API. For the multi-planar API the application sets
 848             this to the number of elements in the <structfield>planes</structfield>
 849             array. The driver will fill in the actual number of valid elements in
 850             that array.
 851             </entry>
 852           </row>
 853           <row>
 854             <entry>__u32</entry>
 855             <entry><structfield>reserved2</structfield></entry>
 856             <entry></entry>
 857             <entry>A place holder for future extensions. Applications
 858 should set this to 0.</entry>
 859           </row>
 860           <row>
 861             <entry>__u32</entry>
 862             <entry><structfield>reserved</structfield></entry>
 863             <entry></entry>
 864             <entry>A place holder for future extensions. Applications
 865 should set this to 0.</entry>
 866           </row>
 867         </tbody>
 868       </tgroup>
 869     </table>
 870
 871     <table frame="none" pgwide="1" id="v4l2-plane">
 872       <title>struct <structname>v4l2_plane</structname></title>
 873       <tgroup cols="4">
 874         &cs-ustr;
 875         <tbody valign="top">
 876           <row>
 877             <entry>__u32</entry>
 878             <entry><structfield>bytesused</structfield></entry>
 879             <entry></entry>
 880             <entry>The number of bytes occupied by data in the plane
 881             (its payload).</entry>
 882           </row>
 883           <row>
 884             <entry>__u32</entry>
 885             <entry><structfield>length</structfield></entry>
 886             <entry></entry>
 887             <entry>Size in bytes of the plane (not its payload).</entry>
 888           </row>
 889           <row>
 890             <entry>union</entry>
 891             <entry><structfield>m</structfield></entry>
 892             <entry></entry>
 893             <entry></entry>
 894           </row>
 895           <row>
 896             <entry></entry>
 897             <entry>__u32</entry>
 898             <entry><structfield>mem_offset</structfield></entry>
 899             <entry>When the memory type in the containing &v4l2-buffer; is
 900               <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
 901               should be passed to &func-mmap;, similar to the
 902               <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
 903           </row>
 904           <row>
 905             <entry></entry>
 906             <entry>__unsigned long</entry>
 907             <entry><structfield>userptr</structfield></entry>
 908             <entry>When the memory type in the containing &v4l2-buffer; is
 909               <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
 910               pointer to the memory allocated for this plane by an application.
 911               </entry>
 912           </row>
 913           <row>
 914             <entry></entry>
 915             <entry>int</entry>
 916             <entry><structfield>fd</structfield></entry>
 917             <entry>When the memory type in the containing &v4l2-buffer; is
 918                 <constant>V4L2_MEMORY_DMABUF</constant>, this is a file
 919                 descriptor associated with a DMABUF buffer, similar to the
 920                 <structfield>fd</structfield> field in &v4l2-buffer;.</entry>
 921           </row>
 922           <row>
 923             <entry>__u32</entry>
 924             <entry><structfield>data_offset</structfield></entry>
 925             <entry></entry>
 926             <entry>Offset in bytes to video data in the plane, if applicable.
 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>
 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         </tbody>
1007       </tgroup>
1008     </table>
1009
1010     <table frame="none" pgwide="1" id="buffer-flags">
1011       <title>Buffer Flags</title>
1012       <tgroup cols="3">
1013         &cs-def;
1014         <tbody valign="top">
1015           <row>
1016             <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
1017             <entry>0x0001</entry>
1018             <entry>The buffer resides in device memory and has been mapped
1019 into the application's address space, see <xref linkend="mmap" /> for details.
1020 Drivers set or clear this flag when the
1021 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1022           linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1023           linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
1024           </row>
1025           <row>
1026             <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
1027             <entry>0x0002</entry>
1028           <entry>Internally drivers maintain two buffer queues, an
1029 incoming and outgoing queue. When this flag is set, the buffer is
1030 currently on the incoming queue. It automatically moves to the
1031 outgoing queue after the buffer has been filled (capture devices) or
1032 displayed (output devices). Drivers set or clear this flag when the
1033 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
1034 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
1035 always set and after <constant>VIDIOC_DQBUF</constant> always
1036 cleared.</entry>
1037           </row>
1038           <row>
1039             <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
1040             <entry>0x0004</entry>
1041             <entry>When this flag is set, the buffer is currently on
1042 the outgoing queue, ready to be dequeued from the driver. Drivers set
1043 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
1044 is called. After calling the <constant>VIDIOC_QBUF</constant> or
1045 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
1046 buffer cannot be on both queues at the same time, the
1047 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
1048 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
1049 They can be both cleared however, then the buffer is in "dequeued"
1050 state, in the application domain to say so.</entry>
1051           </row>
1052           <row>
1053             <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
1054             <entry>0x0040</entry>
1055             <entry>When this flag is set, the buffer has been dequeued
1056             successfully, although the data might have been corrupted.
1057             This is recoverable, streaming may continue as normal and
1058             the buffer may be reused normally.
1059             Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
1060             ioctl is called.</entry>
1061           </row>
1062           <row>
1063             <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
1064             <entry>0x0008</entry>
1065           <entry>Drivers set or clear this flag when calling the
1066 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
1067 capture devices when the buffer contains a compressed image which is a
1068 key frame (or field), &ie; can be decompressed on its own.</entry>
1069           </row>
1070           <row>
1071             <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
1072             <entry>0x0010</entry>
1073             <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
1074 this flags predicted frames or fields which contain only differences to a
1075 previous key frame.</entry>
1076           </row>
1077           <row>
1078             <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
1079             <entry>0x0020</entry>
1080             <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
1081         this is a bidirectional predicted frame or field. [ooc tbd]</entry>
1082           </row>
1083           <row>
1084             <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
1085             <entry>0x0100</entry>
1086             <entry>The <structfield>timecode</structfield> field is valid.
1087 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
1088 ioctl is called.</entry>
1089           </row>
1090           <row>
1091             <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry>
1092             <entry>0x0400</entry>
1093             <entry>The buffer has been prepared for I/O and can be queued by the
1094 application. Drivers set or clear this flag when the
1095 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
1096           linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link
1097           linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
1098           linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry>
1099           </row>
1100           <row>
1101             <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry>
1102             <entry>0x0800</entry>
1103             <entry>Caches do not have to be invalidated for this buffer.
1104 Typically applications shall use this flag if the data captured in the buffer
1105 is not going to be touched by the CPU, instead the buffer will, probably, be
1106 passed on to a DMA-capable hardware unit for further processing or output.
1107 </entry>
1108           </row>
1109           <row>
1110             <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry>
1111             <entry>0x1000</entry>
1112             <entry>Caches do not have to be cleaned for this buffer.
1113 Typically applications shall use this flag for output buffers if the data
1114 in this buffer has not been created by the CPU but by some DMA-capable unit,
1115 in which case caches have not been used.</entry>
1116           </row>
1117         </tbody>
1118       </tgroup>
1119     </table>
1120
1121     <table pgwide="1" frame="none" id="v4l2-memory">
1122       <title>enum v4l2_memory</title>
1123       <tgroup cols="3">
1124         &cs-def;
1125         <tbody valign="top">
1126           <row>
1127             <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
1128             <entry>1</entry>
1129             <entry>The buffer is used for <link linkend="mmap">memory
1130 mapping</link> I/O.</entry>
1131           </row>
1132           <row>
1133             <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
1134             <entry>2</entry>
1135             <entry>The buffer is used for <link linkend="userp">user
1136 pointer</link> I/O.</entry>
1137           </row>
1138           <row>
1139             <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
1140             <entry>3</entry>
1141             <entry>[to do]</entry>
1142           </row>
1143           <row>
1144             <entry><constant>V4L2_MEMORY_DMABUF</constant></entry>
1145             <entry>4</entry>
1146             <entry>The buffer is used for <link linkend="dmabuf">DMA shared
1147 buffer</link> I/O.</entry>
1148           </row>
1149         </tbody>
1150       </tgroup>
1151     </table>
1152
1153     <section>
1154       <title>Timecodes</title>
1155
1156       <para>The <structname>v4l2_timecode</structname> structure is
1157 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
1158 (struct <structname>timeval</structname> timestamps are stored in
1159 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
1160
1161       <table frame="none" pgwide="1" id="v4l2-timecode">
1162         <title>struct <structname>v4l2_timecode</structname></title>
1163         <tgroup cols="3">
1164           &cs-str;
1165           <tbody valign="top">
1166             <row>
1167               <entry>__u32</entry>
1168               <entry><structfield>type</structfield></entry>
1169               <entry>Frame rate the timecodes are based on, see <xref
1170                   linkend="timecode-type" />.</entry>
1171             </row>
1172             <row>
1173               <entry>__u32</entry>
1174               <entry><structfield>flags</structfield></entry>
1175               <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
1176             </row>
1177             <row>
1178               <entry>__u8</entry>
1179               <entry><structfield>frames</structfield></entry>
1180               <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
1181             type of timecode.</entry>
1182             </row>
1183             <row>
1184               <entry>__u8</entry>
1185               <entry><structfield>seconds</structfield></entry>
1186               <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
1187             </row>
1188             <row>
1189               <entry>__u8</entry>
1190               <entry><structfield>minutes</structfield></entry>
1191               <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
1192             </row>
1193             <row>
1194               <entry>__u8</entry>
1195               <entry><structfield>hours</structfield></entry>
1196               <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
1197             </row>
1198             <row>
1199               <entry>__u8</entry>
1200               <entry><structfield>userbits</structfield>[4]</entry>
1201               <entry>The "user group" bits from the timecode.</entry>
1202             </row>
1203           </tbody>
1204         </tgroup>
1205       </table>
1206
1207       <table frame="none" pgwide="1" id="timecode-type">
1208         <title>Timecode Types</title>
1209         <tgroup cols="3">
1210         &cs-def;
1211           <tbody valign="top">
1212             <row>
1213               <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
1214               <entry>1</entry>
1215               <entry>24 frames per second, i.&nbsp;e. film.</entry>
1216             </row>
1217             <row>
1218               <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
1219               <entry>2</entry>
1220               <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
1221             </row>
1222             <row>
1223               <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
1224               <entry>3</entry>
1225               <entry>30 frames per second, &ie; NTSC video.</entry>
1226             </row>
1227             <row>
1228               <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
1229               <entry>4</entry>
1230               <entry></entry>
1231             </row>
1232             <row>
1233               <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
1234               <entry>5</entry>
1235               <entry></entry>
1236             </row>
1237           </tbody>
1238         </tgroup>
1239       </table>
1240
1241       <table frame="none" pgwide="1" id="timecode-flags">
1242         <title>Timecode Flags</title>
1243         <tgroup cols="3">
1244         &cs-def;
1245           <tbody valign="top">
1246             <row>
1247               <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
1248               <entry>0x0001</entry>
1249               <entry>Indicates "drop frame" semantics for counting frames
1250 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
1251 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
1252 count.</entry>
1253             </row>
1254             <row>
1255               <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
1256               <entry>0x0002</entry>
1257               <entry>The "color frame" flag.</entry>
1258             </row>
1259             <row>
1260               <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
1261               <entry>0x000C</entry>
1262               <entry>Field mask for the "binary group flags".</entry>
1263             </row>
1264             <row>
1265               <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
1266               <entry>0x0000</entry>
1267               <entry>Unspecified format.</entry>
1268             </row>
1269             <row>
1270               <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
1271               <entry>0x0008</entry>
1272               <entry>8-bit ISO characters.</entry>
1273             </row>
1274           </tbody>
1275         </tgroup>
1276       </table>
1277     </section>
1278   </section>
1279
1280   <section id="field-order">
1281     <title>Field Order</title>
1282
1283     <para>We have to distinguish between progressive and interlaced
1284 video. Progressive video transmits all lines of a video image
1285 sequentially. Interlaced video divides an image into two fields,
1286 containing only the odd and even lines of the image, respectively.
1287 Alternating the so called odd and even field are transmitted, and due
1288 to a small delay between fields a cathode ray TV displays the lines
1289 interleaved, yielding the original frame. This curious technique was
1290 invented because at refresh rates similar to film the image would
1291 fade out too quickly. Transmitting fields reduces the flicker without
1292 the necessity of doubling the frame rate and with it the bandwidth
1293 required for each channel.</para>
1294
1295     <para>It is important to understand a video camera does not expose
1296 one frame at a time, merely transmitting the frames separated into
1297 fields. The fields are in fact captured at two different instances in
1298 time. An object on screen may well move between one field and the
1299 next. For applications analysing motion it is of paramount importance
1300 to recognize which field of a frame is older, the <emphasis>temporal
1301 order</emphasis>.</para>
1302
1303     <para>When the driver provides or accepts images field by field
1304 rather than interleaved, it is also important applications understand
1305 how the fields combine to frames. We distinguish between top (aka odd) and
1306 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
1307 of the top field is the first line of an interlaced frame, the first
1308 line of the bottom field is the second line of that frame.</para>
1309
1310     <para>However because fields were captured one after the other,
1311 arguing whether a frame commences with the top or bottom field is
1312 pointless. Any two successive top and bottom, or bottom and top fields
1313 yield a valid frame. Only when the source was progressive to begin
1314 with, &eg; when transferring film to video, two fields may come from
1315 the same frame, creating a natural order.</para>
1316
1317     <para>Counter to intuition the top field is not necessarily the
1318 older field. Whether the older field contains the top or bottom lines
1319 is a convention determined by the video standard. Hence the
1320 distinction between temporal and spatial order of fields. The diagrams
1321 below should make this clearer.</para>
1322
1323     <para>All video capture and output devices must report the current
1324 field order. Some drivers may permit the selection of a different
1325 order, to this end applications initialize the
1326 <structfield>field</structfield> field of &v4l2-pix-format; before
1327 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
1328 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
1329
1330     <table frame="none" pgwide="1" id="v4l2-field">
1331       <title>enum v4l2_field</title>
1332       <tgroup cols="3">
1333         &cs-def;
1334         <tbody valign="top">
1335           <row>
1336             <entry><constant>V4L2_FIELD_ANY</constant></entry>
1337             <entry>0</entry>
1338             <entry>Applications request this field order when any
1339 one of the <constant>V4L2_FIELD_NONE</constant>,
1340 <constant>V4L2_FIELD_TOP</constant>,
1341 <constant>V4L2_FIELD_BOTTOM</constant>, or
1342 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
1343 Drivers choose depending on hardware capabilities or e.&nbsp;g. the
1344 requested image size, and return the actual field order. &v4l2-buffer;
1345 <structfield>field</structfield> can never be
1346 <constant>V4L2_FIELD_ANY</constant>.</entry>
1347           </row>
1348           <row>
1349             <entry><constant>V4L2_FIELD_NONE</constant></entry>
1350             <entry>1</entry>
1351             <entry>Images are in progressive format, not interlaced.
1352 The driver may also indicate this order when it cannot distinguish
1353 between <constant>V4L2_FIELD_TOP</constant> and
1354 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
1355           </row>
1356           <row>
1357             <entry><constant>V4L2_FIELD_TOP</constant></entry>
1358             <entry>2</entry>
1359             <entry>Images consist of the top (aka odd) field only.</entry>
1360           </row>
1361           <row>
1362             <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1363             <entry>3</entry>
1364             <entry>Images consist of the bottom (aka even) field only.
1365 Applications may wish to prevent a device from capturing interlaced
1366 images because they will have "comb" or "feathering" artefacts around
1367 moving objects.</entry>
1368           </row>
1369           <row>
1370             <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1371             <entry>4</entry>
1372             <entry>Images contain both fields, interleaved line by
1373 line. The temporal order of the fields (whether the top or bottom
1374 field is first transmitted) depends on the current video standard.
1375 M/NTSC transmits the bottom field first, all other standards the top
1376 field first.</entry>
1377           </row>
1378           <row>
1379             <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1380             <entry>5</entry>
1381             <entry>Images contain both fields, the top field lines
1382 are stored first in memory, immediately followed by the bottom field
1383 lines. Fields are always stored in temporal order, the older one first
1384 in memory. Image sizes refer to the frame, not fields.</entry>
1385           </row>
1386           <row>
1387             <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1388             <entry>6</entry>
1389             <entry>Images contain both fields, the bottom field
1390 lines are stored first in memory, immediately followed by the top
1391 field lines. Fields are always stored in temporal order, the older one
1392 first in memory. Image sizes refer to the frame, not fields.</entry>
1393           </row>
1394           <row>
1395             <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1396             <entry>7</entry>
1397             <entry>The two fields of a frame are passed in separate
1398 buffers, in temporal order, &ie; the older one first. To indicate the field
1399 parity (whether the current field is a top or bottom field) the driver
1400 or application, depending on data direction, must set &v4l2-buffer;
1401 <structfield>field</structfield> to
1402 <constant>V4L2_FIELD_TOP</constant> or
1403 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1404 to build a frame. If fields are successive, without any dropped fields
1405 between them (fields can drop individually), can be determined from
1406 the &v4l2-buffer; <structfield>sequence</structfield> field. Image
1407 sizes refer to the frame, not fields. This format cannot be selected
1408 when using the read/write I/O method.<!-- Where it's indistinguishable
1409 from V4L2_FIELD_SEQ_*. --></entry>
1410           </row>
1411           <row>
1412             <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1413             <entry>8</entry>
1414             <entry>Images contain both fields, interleaved line by
1415 line, top field first. The top field is transmitted first.</entry>
1416           </row>
1417           <row>
1418             <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1419             <entry>9</entry>
1420             <entry>Images contain both fields, interleaved line by
1421 line, top field first. The bottom field is transmitted first.</entry>
1422           </row>
1423         </tbody>
1424       </tgroup>
1425     </table>
1426
1427     <figure id="fieldseq-tb">
1428         <title>Field Order, Top Field First Transmitted</title>
1429         <mediaobject>
1430           <imageobject>
1431             <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1432           </imageobject>
1433           <imageobject>
1434             <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1435           </imageobject>
1436         </mediaobject>
1437     </figure>
1438
1439     <figure id="fieldseq-bt">
1440         <title>Field Order, Bottom Field First Transmitted</title>
1441         <mediaobject>
1442           <imageobject>
1443             <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1444           </imageobject>
1445           <imageobject>
1446             <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1447           </imageobject>
1448         </mediaobject>
1449     </figure>
1450   </section>