Documentation/DocBook/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. The <structfield>m.offset</structfield> and
 125 <structfield>length</structfield> returned in a &v4l2-buffer; are
 126 passed as sixth and second parameter to the
 127 <function>mmap()</function> function. The offset and length values
 128 must not be modified. Remember the buffers are allocated in physical
 129 memory, as opposed to virtual memory which can be swapped out to disk.
 130 Applications should free the buffers as soon as possible with the
 131 &func-munmap; function.</para>
 132
 133     <example>
 134       <title>Mapping buffers</title>
 135
 136       <programlisting>
 137 &v4l2-requestbuffers; reqbuf;
 138 struct {
 139         void *start;
 140         size_t length;
 141 } *buffers;
 142 unsigned int i;
 143
 144 memset (&amp;reqbuf, 0, sizeof (reqbuf));
 145 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 146 reqbuf.memory = V4L2_MEMORY_MMAP;
 147 reqbuf.count = 20;
 148
 149 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) {
 150         if (errno == EINVAL)
 151                 printf ("Video capturing or mmap-streaming is not supported\n");
 152         else
 153                 perror ("VIDIOC_REQBUFS");
 154
 155         exit (EXIT_FAILURE);
 156 }
 157
 158 /* We want at least five buffers. */
 159
 160 if (reqbuf.count &lt; 5) {
 161         /* You may need to free the buffers here. */
 162         printf ("Not enough buffer memory\n");
 163         exit (EXIT_FAILURE);
 164 }
 165
 166 buffers = calloc (reqbuf.count, sizeof (*buffers));
 167 assert (buffers != NULL);
 168
 169 for (i = 0; i &lt; reqbuf.count; i++) {
 170         &v4l2-buffer; buffer;
 171
 172         memset (&amp;buffer, 0, sizeof (buffer));
 173         buffer.type = reqbuf.type;
 174         buffer.memory = V4L2_MEMORY_MMAP;
 175         buffer.index = i;
 176
 177         if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) {
 178                 perror ("VIDIOC_QUERYBUF");
 179                 exit (EXIT_FAILURE);
 180         }
 181
 182         buffers[i].length = buffer.length; /* remember for munmap() */
 183
 184         buffers[i].start = mmap (NULL, buffer.length,
 185                                  PROT_READ | PROT_WRITE, /* recommended */
 186                                  MAP_SHARED,             /* recommended */
 187                                  fd, buffer.m.offset);
 188
 189         if (MAP_FAILED == buffers[i].start) {
 190                 /* If you do not exit here you should unmap() and free()
 191                    the buffers mapped so far. */
 192                 perror ("mmap");
 193                 exit (EXIT_FAILURE);
 194         }
 195 }
 196
 197 /* Cleanup. */
 198
 199 for (i = 0; i &lt; reqbuf.count; i++)
 200         munmap (buffers[i].start, buffers[i].length);
 201       </programlisting>
 202     </example>
 203
 204     <para>Conceptually streaming drivers maintain two buffer queues, an incoming
 205 and an outgoing queue. They separate the synchronous capture or output
 206 operation locked to a video clock from the application which is
 207 subject to random disk or network delays and preemption by
 208 other processes, thereby reducing the probability of data loss.
 209 The queues are organized as FIFOs, buffers will be
 210 output in the order enqueued in the incoming FIFO, and were
 211 captured in the order dequeued from the outgoing FIFO.</para>
 212
 213     <para>The driver may require a minimum number of buffers enqueued
 214 at all times to function, apart of this no limit exists on the number
 215 of buffers applications can enqueue in advance, or dequeue and
 216 process. They can also enqueue in a different order than buffers have
 217 been dequeued, and the driver can <emphasis>fill</emphasis> enqueued
 218 <emphasis>empty</emphasis> buffers in any order. <footnote>
 219         <para>Random enqueue order permits applications processing
 220 images out of order (such as video codecs) to return buffers earlier,
 221 reducing the probability of data loss. Random fill order allows
 222 drivers to reuse buffers on a LIFO-basis, taking advantage of caches
 223 holding scatter-gather lists and the like.</para>
 224       </footnote> The index number of a buffer (&v4l2-buffer;
 225 <structfield>index</structfield>) plays no role here, it only
 226 identifies the buffer.</para>
 227
 228     <para>Initially all mapped buffers are in dequeued state,
 229 inaccessible by the driver. For capturing applications it is customary
 230 to first enqueue all mapped buffers, then to start capturing and enter
 231 the read loop. Here the application waits until a filled buffer can be
 232 dequeued, and re-enqueues the buffer when the data is no longer
 233 needed. Output applications fill and enqueue buffers, when enough
 234 buffers are stacked up the output is started with
 235 <constant>VIDIOC_STREAMON</constant>. In the write loop, when
 236 the application runs out of free buffers, it must wait until an empty
 237 buffer can be dequeued and reused.</para>
 238
 239     <para>To enqueue and dequeue a buffer applications use the
 240 &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
 241 mapped, enqueued, full or empty can be determined at any time using the
 242 &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
 243 application until one or more buffers can be dequeued. By default
 244 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
 245 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
 246 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
 247 returns immediately with an &EAGAIN; when no buffer is available. The
 248 &func-select; or &func-poll; function are always available.</para>
 249
 250     <para>To start and stop capturing or output applications call the
 251 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
 252 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
 253 queues as a side effect. Since there is no notion of doing anything
 254 "now" on a multitasking system, if an application needs to synchronize
 255 with another event it should examine the &v4l2-buffer;
 256 <structfield>timestamp</structfield> of captured buffers, or set the
 257 field before enqueuing buffers for output.</para>
 258
 259     <para>Drivers implementing memory mapping I/O must
 260 support the <constant>VIDIOC_REQBUFS</constant>,
 261 <constant>VIDIOC_QUERYBUF</constant>,
 262 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
 263 <constant>VIDIOC_STREAMON</constant> and
 264 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
 265 <function>mmap()</function>, <function>munmap()</function>,
 266 <function>select()</function> and <function>poll()</function>
 267 function.<footnote>
 268         <para>At the driver level <function>select()</function> and
 269 <function>poll()</function> are the same, and
 270 <function>select()</function> is too important to be optional. The
 271 rest should be evident.</para>
 272       </footnote></para>
 273
 274     <para>[capture example]</para>
 275
 276   </section>
 277
 278   <section id="userp">
 279     <title>Streaming I/O (User Pointers)</title>
 280
 281     <para>Input and output devices support this I/O method when the
 282 <constant>V4L2_CAP_STREAMING</constant> flag in the
 283 <structfield>capabilities</structfield> field of &v4l2-capability;
 284 returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
 285 pointer method (not only memory mapping) is supported must be
 286 determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
 287
 288     <para>This I/O method combines advantages of the read/write and
 289 memory mapping methods. Buffers are allocated by the application
 290 itself, and can reside for example in virtual or shared memory. Only
 291 pointers to data are exchanged, these pointers and meta-information
 292 are passed in &v4l2-buffer;. The driver must be switched
 293 into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the
 294 desired buffer type. No buffers are allocated beforehands,
 295 consequently they are not indexed and cannot be queried like mapped
 296 buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
 297
 298     <example>
 299       <title>Initiating streaming I/O with user pointers</title>
 300
 301       <programlisting>
 302 &v4l2-requestbuffers; reqbuf;
 303
 304 memset (&amp;reqbuf, 0, sizeof (reqbuf));
 305 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
 306 reqbuf.memory = V4L2_MEMORY_USERPTR;
 307
 308 if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
 309         if (errno == EINVAL)
 310                 printf ("Video capturing or user pointer streaming is not supported\n");
 311         else
 312                 perror ("VIDIOC_REQBUFS");
 313
 314         exit (EXIT_FAILURE);
 315 }
 316       </programlisting>
 317     </example>
 318
 319     <para>Buffer addresses and sizes are passed on the fly with the
 320 &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
 321 applications can pass different addresses and sizes at each
 322 <constant>VIDIOC_QBUF</constant> call. If required by the hardware the
 323 driver swaps memory pages within physical memory to create a
 324 continuous area of memory. This happens transparently to the
 325 application in the virtual memory subsystem of the kernel. When buffer
 326 pages have been swapped out to disk they are brought back and finally
 327 locked in physical memory for DMA.<footnote>
 328         <para>We expect that frequently used buffers are typically not
 329 swapped out. Anyway, the process of swapping, locking or generating
 330 scatter-gather lists may be time consuming. The delay can be masked by
 331 the depth of the incoming buffer queue, and perhaps by maintaining
 332 caches assuming a buffer will be soon enqueued again. On the other
 333 hand, to optimize memory usage drivers can limit the number of buffers
 334 locked in advance and recycle the most recently used buffers first. Of
 335 course, the pages of empty buffers in the incoming queue need not be
 336 saved to disk. Output buffers must be saved on the incoming and
 337 outgoing queue because an application may share them with other
 338 processes.</para>
 339       </footnote></para>
 340
 341     <para>Filled or displayed buffers are dequeued with the
 342 &VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any
 343 time between the completion of the DMA and this ioctl. The memory is
 344 also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
 345 when the device is closed. Applications must take care not to free
 346 buffers without dequeuing. For once, the buffers remain locked until
 347 further, wasting physical memory. Second the driver will not be
 348 notified when the memory is returned to the application's free list
 349 and subsequently reused for other purposes, possibly completing the
 350 requested DMA and overwriting valuable data.</para>
 351
 352     <para>For capturing applications it is customary to enqueue a
 353 number of empty buffers, to start capturing and enter the read loop.
 354 Here the application waits until a filled buffer can be dequeued, and
 355 re-enqueues the buffer when the data is no longer needed. Output
 356 applications fill and enqueue buffers, when enough buffers are stacked
 357 up output is started. In the write loop, when the application
 358 runs out of free buffers it must wait until an empty buffer can be
 359 dequeued and reused. Two methods exist to suspend execution of the
 360 application until one or more buffers can be dequeued. By default
 361 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
 362 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
 363 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
 364 returns immediately with an &EAGAIN; when no buffer is available. The
 365 &func-select; or &func-poll; function are always available.</para>
 366
 367     <para>To start and stop capturing or output applications call the
 368 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
 369 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
 370 queues and unlocks all buffers as a side effect. Since there is no
 371 notion of doing anything "now" on a multitasking system, if an
 372 application needs to synchronize with another event it should examine
 373 the &v4l2-buffer; <structfield>timestamp</structfield> of captured
 374 buffers, or set the field before enqueuing buffers for output.</para>
 375
 376     <para>Drivers implementing user pointer I/O must
 377 support the <constant>VIDIOC_REQBUFS</constant>,
 378 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
 379 <constant>VIDIOC_STREAMON</constant> and
 380 <constant>VIDIOC_STREAMOFF</constant> ioctl, the
 381 <function>select()</function> and <function>poll()</function> function.<footnote>
 382         <para>At the driver level <function>select()</function> and
 383 <function>poll()</function> are the same, and
 384 <function>select()</function> is too important to be optional. The
 385 rest should be evident.</para>
 386       </footnote></para>
 387   </section>
 388
 389   <section id="async">
 390     <title>Asynchronous I/O</title>
 391
 392     <para>This method is not defined yet.</para>
 393   </section>
 394
 395   <section id="buffer">
 396     <title>Buffers</title>
 397
 398     <para>A buffer contains data exchanged by application and
 399 driver using one of the Streaming I/O methods. Only pointers to
 400 buffers are exchanged, the data itself is not copied. These pointers,
 401 together with meta-information like timestamps or field parity, are
 402 stored in a struct <structname>v4l2_buffer</structname>, argument to
 403 the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para>
 404
 405       <para>Nominally timestamps refer to the first data byte transmitted.
 406 In practice however the wide range of hardware covered by the V4L2 API
 407 limits timestamp accuracy. Often an interrupt routine will
 408 sample the system clock shortly after the field or frame was stored
 409 completely in memory. So applications must expect a constant
 410 difference up to one field or frame period plus a small (few scan
 411 lines) random error. The delay and error can be much
 412 larger due to compression or transmission over an external bus when
 413 the frames are not properly stamped by the sender. This is frequently
 414 the case with USB cameras. Here timestamps refer to the instant the
 415 field or frame was received by the driver, not the capture time. These
 416 devices identify by not enumerating any video standards, see <xref
 417 linkend="standard" />.</para>
 418
 419       <para>Similar limitations apply to output timestamps. Typically
 420 the video hardware locks to a clock controlling the video timing, the
 421 horizontal and vertical synchronization pulses. At some point in the
 422 line sequence, possibly the vertical blanking, an interrupt routine
 423 samples the system clock, compares against the timestamp and programs
 424 the hardware to repeat the previous field or frame, or to display the
 425 buffer contents.</para>
 426
 427       <para>Apart of limitations of the video device and natural
 428 inaccuracies of all clocks, it should be noted system time itself is
 429 not perfectly stable. It can be affected by power saving cycles,
 430 warped to insert leap seconds, or even turned back or forth by the
 431 system administrator affecting long term measurements. <footnote>
 432           <para>Since no other Linux multimedia
 433 API supports unadjusted time it would be foolish to introduce here. We
 434 must use a universally supported clock to synchronize different media,
 435 hence time of day.</para>
 436         </footnote></para>
 437
 438     <table frame="none" pgwide="1" id="v4l2-buffer">
 439       <title>struct <structname>v4l2_buffer</structname></title>
 440       <tgroup cols="4">
 441         &cs-ustr;
 442         <tbody valign="top">
 443           <row>
 444             <entry>__u32</entry>
 445             <entry><structfield>index</structfield></entry>
 446             <entry></entry>
 447             <entry>Number of the buffer, set by the application. This
 448 field is only used for <link linkend="mmap">memory mapping</link> I/O
 449 and can range from zero to the number of buffers allocated
 450 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
 451           </row>
 452           <row>
 453             <entry>&v4l2-buf-type;</entry>
 454             <entry><structfield>type</structfield></entry>
 455             <entry></entry>
 456             <entry>Type of the buffer, same as &v4l2-format;
 457 <structfield>type</structfield> or &v4l2-requestbuffers;
 458 <structfield>type</structfield>, set by the application.</entry>
 459           </row>
 460           <row>
 461             <entry>__u32</entry>
 462             <entry><structfield>bytesused</structfield></entry>
 463             <entry></entry>
 464             <entry>The number of bytes occupied by the data in the
 465 buffer. It depends on the negotiated data format and may change with
 466 each buffer for compressed variable size data like JPEG images.
 467 Drivers must set this field when <structfield>type</structfield>
 468 refers to an input stream, applications when an output stream.</entry>
 469           </row>
 470           <row>
 471             <entry>__u32</entry>
 472             <entry><structfield>flags</structfield></entry>
 473             <entry></entry>
 474             <entry>Flags set by the application or driver, see <xref
 475 linkend="buffer-flags" />.</entry>
 476           </row>
 477           <row>
 478             <entry>&v4l2-field;</entry>
 479             <entry><structfield>field</structfield></entry>
 480             <entry></entry>
 481             <entry>Indicates the field order of the image in the
 482 buffer, see <xref linkend="v4l2-field" />. This field is not used when
 483 the buffer contains VBI data. Drivers must set it when
 484 <structfield>type</structfield> refers to an input stream,
 485 applications when an output stream.</entry>
 486           </row>
 487           <row>
 488             <entry>struct timeval</entry>
 489             <entry><structfield>timestamp</structfield></entry>
 490             <entry></entry>
 491             <entry><para>For input streams this is the
 492 system time (as returned by the <function>gettimeofday()</function>
 493 function) when the first data byte was captured. For output streams
 494 the data will not be displayed before this time, secondary to the
 495 nominal frame rate determined by the current video standard in
 496 enqueued order. Applications can for example zero this field to
 497 display frames as soon as possible. The driver stores the time at
 498 which the first data byte was actually sent out in the
 499 <structfield>timestamp</structfield> field. This permits
 500 applications to monitor the drift between the video and system
 501 clock.</para></entry>
 502           </row>
 503           <row>
 504             <entry>&v4l2-timecode;</entry>
 505             <entry><structfield>timecode</structfield></entry>
 506             <entry></entry>
 507             <entry>When <structfield>type</structfield> is
 508 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
 509 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
 510 <structfield>flags</structfield>, this structure contains a frame
 511 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
 512 mode the top and bottom field contain the same timecode.
 513 Timecodes are intended to help video editing and are typically recorded on
 514 video tapes, but also embedded in compressed formats like MPEG. This
 515 field is independent of the <structfield>timestamp</structfield> and
 516 <structfield>sequence</structfield> fields.</entry>
 517           </row>
 518           <row>
 519             <entry>__u32</entry>
 520             <entry><structfield>sequence</structfield></entry>
 521             <entry></entry>
 522             <entry>Set by the driver, counting the frames in the
 523 sequence.</entry>
 524           </row>
 525           <row>
 526             <entry spanname="hspan"><para>In <link
 527 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
 528 bottom field have the same sequence number. The count starts at zero
 529 and includes dropped or repeated frames. A dropped frame was received
 530 by an input device but could not be stored due to lack of free buffer
 531 space. A repeated frame was displayed again by an output device
 532 because the application did not pass new data in
 533 time.</para><para>Note this may count the frames received
 534 e.g. over USB, without taking into account the frames dropped by the
 535 remote hardware due to limited compression throughput or bus
 536 bandwidth. These devices identify by not enumerating any video
 537 standards, see <xref linkend="standard" />.</para></entry>
 538           </row>
 539           <row>
 540             <entry>&v4l2-memory;</entry>
 541             <entry><structfield>memory</structfield></entry>
 542             <entry></entry>
 543             <entry>This field must be set by applications and/or drivers
 544 in accordance with the selected I/O method.</entry>
 545           </row>
 546           <row>
 547             <entry>union</entry>
 548             <entry><structfield>m</structfield></entry>
 549           </row>
 550           <row>
 551             <entry></entry>
 552             <entry>__u32</entry>
 553             <entry><structfield>offset</structfield></entry>
 554             <entry>When <structfield>memory</structfield> is
 555 <constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer
 556 from the start of the device memory. The value is returned by the
 557 driver and apart of serving as parameter to the &func-mmap; function
 558 not useful for applications. See <xref linkend="mmap" /> for details.</entry>
 559           </row>
 560           <row>
 561             <entry></entry>
 562             <entry>unsigned long</entry>
 563             <entry><structfield>userptr</structfield></entry>
 564             <entry>When <structfield>memory</structfield> is
 565 <constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the
 566 buffer (casted to unsigned long type) in virtual memory, set by the
 567 application. See <xref linkend="userp" /> for details.</entry>
 568           </row>
 569           <row>
 570             <entry>__u32</entry>
 571             <entry><structfield>length</structfield></entry>
 572             <entry></entry>
 573             <entry>Size of the buffer (not the payload) in bytes.</entry>
 574           </row>
 575           <row>
 576             <entry>__u32</entry>
 577             <entry><structfield>input</structfield></entry>
 578             <entry></entry>
 579             <entry>Some video capture drivers support rapid and
 580 synchronous video input changes, a function useful for example in
 581 video surveillance applications. For this purpose applications set the
 582 <constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the
 583 number of a video input as in &v4l2-input; field
 584 <structfield>index</structfield>.</entry>
 585           </row>
 586           <row>
 587             <entry>__u32</entry>
 588             <entry><structfield>reserved</structfield></entry>
 589             <entry></entry>
 590             <entry>A place holder for future extensions and custom
 591 (driver defined) buffer types
 592 <constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications
 593 should set this to 0.</entry>
 594           </row>
 595         </tbody>
 596       </tgroup>
 597     </table>
 598
 599     <table frame="none" pgwide="1" id="v4l2-buf-type">
 600       <title>enum v4l2_buf_type</title>
 601       <tgroup cols="3">
 602         &cs-def;
 603         <tbody valign="top">
 604           <row>
 605             <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
 606             <entry>1</entry>
 607             <entry>Buffer of a video capture stream, see <xref
 608                 linkend="capture" />.</entry>
 609           </row>
 610           <row>
 611             <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
 612             <entry>2</entry>
 613             <entry>Buffer of a video output stream, see <xref
 614                 linkend="output" />.</entry>
 615           </row>
 616           <row>
 617             <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
 618             <entry>3</entry>
 619             <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
 620           </row>
 621           <row>
 622             <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
 623             <entry>4</entry>
 624             <entry>Buffer of a raw VBI capture stream, see <xref
 625                 linkend="raw-vbi" />.</entry>
 626           </row>
 627           <row>
 628             <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
 629             <entry>5</entry>
 630             <entry>Buffer of a raw VBI output stream, see <xref
 631                 linkend="raw-vbi" />.</entry>
 632           </row>
 633           <row>
 634             <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
 635             <entry>6</entry>
 636             <entry>Buffer of a sliced VBI capture stream, see <xref
 637                 linkend="sliced" />.</entry>
 638           </row>
 639           <row>
 640             <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
 641             <entry>7</entry>
 642             <entry>Buffer of a sliced VBI output stream, see <xref
 643                 linkend="sliced" />.</entry>
 644           </row>
 645           <row>
 646             <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
 647             <entry>8</entry>
 648             <entry>Buffer for video output overlay (OSD), see <xref
 649                 linkend="osd" />. Status: <link
 650 linkend="experimental">Experimental</link>.</entry>
 651           </row>
 652           <row>
 653             <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
 654             <entry>0x80</entry>
 655           <entry>This and higher values are reserved for custom
 656 (driver defined) buffer types.</entry>
 657           </row>
 658         </tbody>
 659       </tgroup>
 660     </table>
 661
 662     <table frame="none" pgwide="1" id="buffer-flags">
 663       <title>Buffer Flags</title>
 664       <tgroup cols="3">
 665         &cs-def;
 666         <tbody valign="top">
 667           <row>
 668             <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
 669             <entry>0x0001</entry>
 670             <entry>The buffer resides in device memory and has been mapped
 671 into the application's address space, see <xref linkend="mmap" /> for details.
 672 Drivers set or clear this flag when the
 673 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
 674           linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
 675           linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
 676           </row>
 677           <row>
 678             <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
 679             <entry>0x0002</entry>
 680           <entry>Internally drivers maintain two buffer queues, an
 681 incoming and outgoing queue. When this flag is set, the buffer is
 682 currently on the incoming queue. It automatically moves to the
 683 outgoing queue after the buffer has been filled (capture devices) or
 684 displayed (output devices). Drivers set or clear this flag when the
 685 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
 686 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
 687 always set and after <constant>VIDIOC_DQBUF</constant> always
 688 cleared.</entry>
 689           </row>
 690           <row>
 691             <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
 692             <entry>0x0004</entry>
 693             <entry>When this flag is set, the buffer is currently on
 694 the outgoing queue, ready to be dequeued from the driver. Drivers set
 695 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
 696 is called. After calling the <constant>VIDIOC_QBUF</constant> or
 697 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
 698 buffer cannot be on both queues at the same time, the
 699 <constant>V4L2_BUF_FLAG_QUEUED</constant> and
 700 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
 701 They can be both cleared however, then the buffer is in "dequeued"
 702 state, in the application domain to say so.</entry>
 703           </row>
 704           <row>
 705             <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
 706             <entry>0x0008</entry>
 707           <entry>Drivers set or clear this flag when calling the
 708 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
 709 capture devices when the buffer contains a compressed image which is a
 710 key frame (or field), &ie; can be decompressed on its own.</entry>
 711           </row>
 712           <row>
 713             <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
 714             <entry>0x0010</entry>
 715             <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
 716 this flags predicted frames or fields which contain only differences to a
 717 previous key frame.</entry>
 718           </row>
 719           <row>
 720             <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
 721             <entry>0x0020</entry>
 722             <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
 723         this is a bidirectional predicted frame or field. [ooc tbd]</entry>
 724           </row>
 725           <row>
 726             <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
 727             <entry>0x0100</entry>
 728             <entry>The <structfield>timecode</structfield> field is valid.
 729 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
 730 ioctl is called.</entry>
 731           </row>
 732           <row>
 733             <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry>
 734             <entry>0x0200</entry>
 735             <entry>The <structfield>input</structfield> field is valid.
 736 Applications set or clear this flag before calling the
 737 <constant>VIDIOC_QBUF</constant> ioctl.</entry>
 738           </row>
 739         </tbody>
 740       </tgroup>
 741     </table>
 742
 743     <table pgwide="1" frame="none" id="v4l2-memory">
 744       <title>enum v4l2_memory</title>
 745       <tgroup cols="3">
 746         &cs-def;
 747         <tbody valign="top">
 748           <row>
 749             <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
 750             <entry>1</entry>
 751             <entry>The buffer is used for <link linkend="mmap">memory
 752 mapping</link> I/O.</entry>
 753           </row>
 754           <row>
 755             <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
 756             <entry>2</entry>
 757             <entry>The buffer is used for <link linkend="userp">user
 758 pointer</link> I/O.</entry>
 759           </row>
 760           <row>
 761             <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
 762             <entry>3</entry>
 763             <entry>[to do]</entry>
 764           </row>
 765         </tbody>
 766       </tgroup>
 767     </table>
 768
 769     <section>
 770       <title>Timecodes</title>
 771
 772       <para>The <structname>v4l2_timecode</structname> structure is
 773 designed to hold a <xref linkend="smpte12m" /> or similar timecode.
 774 (struct <structname>timeval</structname> timestamps are stored in
 775 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
 776
 777       <table frame="none" pgwide="1" id="v4l2-timecode">
 778         <title>struct <structname>v4l2_timecode</structname></title>
 779         <tgroup cols="3">
 780           &cs-str;
 781           <tbody valign="top">
 782             <row>
 783               <entry>__u32</entry>
 784               <entry><structfield>type</structfield></entry>
 785               <entry>Frame rate the timecodes are based on, see <xref
 786                   linkend="timecode-type" />.</entry>
 787             </row>
 788             <row>
 789               <entry>__u32</entry>
 790               <entry><structfield>flags</structfield></entry>
 791               <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
 792             </row>
 793             <row>
 794               <entry>__u8</entry>
 795               <entry><structfield>frames</structfield></entry>
 796               <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
 797             type of timecode.</entry>
 798             </row>
 799             <row>
 800               <entry>__u8</entry>
 801               <entry><structfield>seconds</structfield></entry>
 802               <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
 803             </row>
 804             <row>
 805               <entry>__u8</entry>
 806               <entry><structfield>minutes</structfield></entry>
 807               <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
 808             </row>
 809             <row>
 810               <entry>__u8</entry>
 811               <entry><structfield>hours</structfield></entry>
 812               <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
 813             </row>
 814             <row>
 815               <entry>__u8</entry>
 816               <entry><structfield>userbits</structfield>[4]</entry>
 817               <entry>The "user group" bits from the timecode.</entry>
 818             </row>
 819           </tbody>
 820         </tgroup>
 821       </table>
 822
 823       <table frame="none" pgwide="1" id="timecode-type">
 824         <title>Timecode Types</title>
 825         <tgroup cols="3">
 826         &cs-def;
 827           <tbody valign="top">
 828             <row>
 829               <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
 830               <entry>1</entry>
 831               <entry>24 frames per second, i.&nbsp;e. film.</entry>
 832             </row>
 833             <row>
 834               <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
 835               <entry>2</entry>
 836               <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
 837             </row>
 838             <row>
 839               <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
 840               <entry>3</entry>
 841               <entry>30 frames per second, &ie; NTSC video.</entry>
 842             </row>
 843             <row>
 844               <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
 845               <entry>4</entry>
 846               <entry></entry>
 847             </row>
 848             <row>
 849               <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
 850               <entry>5</entry>
 851               <entry></entry>
 852             </row>
 853           </tbody>
 854         </tgroup>
 855       </table>
 856
 857       <table frame="none" pgwide="1" id="timecode-flags">
 858         <title>Timecode Flags</title>
 859         <tgroup cols="3">
 860         &cs-def;
 861           <tbody valign="top">
 862             <row>
 863               <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
 864               <entry>0x0001</entry>
 865               <entry>Indicates "drop frame" semantics for counting frames
 866 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
 867 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
 868 count.</entry>
 869             </row>
 870             <row>
 871               <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
 872               <entry>0x0002</entry>
 873               <entry>The "color frame" flag.</entry>
 874             </row>
 875             <row>
 876               <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
 877               <entry>0x000C</entry>
 878               <entry>Field mask for the "binary group flags".</entry>
 879             </row>
 880             <row>
 881               <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
 882               <entry>0x0000</entry>
 883               <entry>Unspecified format.</entry>
 884             </row>
 885             <row>
 886               <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
 887               <entry>0x0008</entry>
 888               <entry>8-bit ISO characters.</entry>
 889             </row>
 890           </tbody>
 891         </tgroup>
 892       </table>
 893     </section>
 894   </section>
 895
 896   <section id="field-order">
 897     <title>Field Order</title>
 898
 899     <para>We have to distinguish between progressive and interlaced
 900 video. Progressive video transmits all lines of a video image
 901 sequentially. Interlaced video divides an image into two fields,
 902 containing only the odd and even lines of the image, respectively.
 903 Alternating the so called odd and even field are transmitted, and due
 904 to a small delay between fields a cathode ray TV displays the lines
 905 interleaved, yielding the original frame. This curious technique was
 906 invented because at refresh rates similar to film the image would
 907 fade out too quickly. Transmitting fields reduces the flicker without
 908 the necessity of doubling the frame rate and with it the bandwidth
 909 required for each channel.</para>
 910
 911     <para>It is important to understand a video camera does not expose
 912 one frame at a time, merely transmitting the frames separated into
 913 fields. The fields are in fact captured at two different instances in
 914 time. An object on screen may well move between one field and the
 915 next. For applications analysing motion it is of paramount importance
 916 to recognize which field of a frame is older, the <emphasis>temporal
 917 order</emphasis>.</para>
 918
 919     <para>When the driver provides or accepts images field by field
 920 rather than interleaved, it is also important applications understand
 921 how the fields combine to frames. We distinguish between top and
 922 bottom fields, the <emphasis>spatial order</emphasis>: The first line
 923 of the top field is the first line of an interlaced frame, the first
 924 line of the bottom field is the second line of that frame.</para>
 925
 926     <para>However because fields were captured one after the other,
 927 arguing whether a frame commences with the top or bottom field is
 928 pointless. Any two successive top and bottom, or bottom and top fields
 929 yield a valid frame. Only when the source was progressive to begin
 930 with, &eg; when transferring film to video, two fields may come from
 931 the same frame, creating a natural order.</para>
 932
 933     <para>Counter to intuition the top field is not necessarily the
 934 older field. Whether the older field contains the top or bottom lines
 935 is a convention determined by the video standard. Hence the
 936 distinction between temporal and spatial order of fields. The diagrams
 937 below should make this clearer.</para>
 938
 939     <para>All video capture and output devices must report the current
 940 field order. Some drivers may permit the selection of a different
 941 order, to this end applications initialize the
 942 <structfield>field</structfield> field of &v4l2-pix-format; before
 943 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
 944 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
 945
 946     <table frame="none" pgwide="1" id="v4l2-field">
 947       <title>enum v4l2_field</title>
 948       <tgroup cols="3">
 949         &cs-def;
 950         <tbody valign="top">
 951           <row>
 952             <entry><constant>V4L2_FIELD_ANY</constant></entry>
 953             <entry>0</entry>
 954             <entry>Applications request this field order when any
 955 one of the <constant>V4L2_FIELD_NONE</constant>,
 956 <constant>V4L2_FIELD_TOP</constant>,
 957 <constant>V4L2_FIELD_BOTTOM</constant>, or
 958 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
 959 Drivers choose depending on hardware capabilities or e.&nbsp;g. the
 960 requested image size, and return the actual field order. &v4l2-buffer;
 961 <structfield>field</structfield> can never be
 962 <constant>V4L2_FIELD_ANY</constant>.</entry>
 963           </row>
 964           <row>
 965             <entry><constant>V4L2_FIELD_NONE</constant></entry>
 966             <entry>1</entry>
 967             <entry>Images are in progressive format, not interlaced.
 968 The driver may also indicate this order when it cannot distinguish
 969 between <constant>V4L2_FIELD_TOP</constant> and
 970 <constant>V4L2_FIELD_BOTTOM</constant>.</entry>
 971           </row>
 972           <row>
 973             <entry><constant>V4L2_FIELD_TOP</constant></entry>
 974             <entry>2</entry>
 975             <entry>Images consist of the top field only.</entry>
 976           </row>
 977           <row>
 978             <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
 979             <entry>3</entry>
 980             <entry>Images consist of the bottom field only.
 981 Applications may wish to prevent a device from capturing interlaced
 982 images because they will have "comb" or "feathering" artefacts around
 983 moving objects.</entry>
 984           </row>
 985           <row>
 986             <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
 987             <entry>4</entry>
 988             <entry>Images contain both fields, interleaved line by
 989 line. The temporal order of the fields (whether the top or bottom
 990 field is first transmitted) depends on the current video standard.
 991 M/NTSC transmits the bottom field first, all other standards the top
 992 field first.</entry>
 993           </row>
 994           <row>
 995             <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
 996             <entry>5</entry>
 997             <entry>Images contain both fields, the top field lines
 998 are stored first in memory, immediately followed by the bottom field
 999 lines. Fields are always stored in temporal order, the older one first
1000 in memory. Image sizes refer to the frame, not fields.</entry>
1001           </row>
1002           <row>
1003             <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1004             <entry>6</entry>
1005             <entry>Images contain both fields, the bottom field
1006 lines are stored first in memory, immediately followed by the top
1007 field lines. Fields are always stored in temporal order, the older one
1008 first in memory. Image sizes refer to the frame, not fields.</entry>
1009           </row>
1010           <row>
1011             <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1012             <entry>7</entry>
1013             <entry>The two fields of a frame are passed in separate
1014 buffers, in temporal order, &ie; the older one first. To indicate the field
1015 parity (whether the current field is a top or bottom field) the driver
1016 or application, depending on data direction, must set &v4l2-buffer;
1017 <structfield>field</structfield> to
1018 <constant>V4L2_FIELD_TOP</constant> or
1019 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1020 to build a frame. If fields are successive, without any dropped fields
1021 between them (fields can drop individually), can be determined from
1022 the &v4l2-buffer; <structfield>sequence</structfield> field. Image
1023 sizes refer to the frame, not fields. This format cannot be selected
1024 when using the read/write I/O method.<!-- Where it's indistinguishable
1025 from V4L2_FIELD_SEQ_*. --></entry>
1026           </row>
1027           <row>
1028             <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1029             <entry>8</entry>
1030             <entry>Images contain both fields, interleaved line by
1031 line, top field first. The top field is transmitted first.</entry>
1032           </row>
1033           <row>
1034             <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1035             <entry>9</entry>
1036             <entry>Images contain both fields, interleaved line by
1037 line, top field first. The bottom field is transmitted first.</entry>
1038           </row>
1039         </tbody>
1040       </tgroup>
1041     </table>
1042
1043     <figure id="fieldseq-tb">
1044         <title>Field Order, Top Field First Transmitted</title>
1045         <mediaobject>
1046           <imageobject>
1047             <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1048           </imageobject>
1049           <imageobject>
1050             <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1051           </imageobject>
1052         </mediaobject>
1053     </figure>
1054
1055     <figure id="fieldseq-bt">
1056         <title>Field Order, Bottom Field First Transmitted</title>
1057         <mediaobject>
1058           <imageobject>
1059             <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1060           </imageobject>
1061           <imageobject>
1062             <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1063           </imageobject>
1064         </mediaobject>
1065     </figure>
1066   </section>
1067
1068   <!--
1069 Local Variables:
1070 mode: sgml
1071 sgml-parent-document: "v4l2.sgml"
1072 indent-tabs-mode: nil
1073 End:
1074   -->