1 <title>Input/Output</title> 2 3 <para>The V4L2 API defines several different methods to read from or 4write to a device. All drivers exchanging data with applications must 5support at least one of them.</para> 6 7 <para>The classic I/O method using the <function>read()</function> 8and <function>write()</function> function is automatically selected 9after opening a V4L2 device. When the driver does not support this 10method 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 13method with memory mapped or user buffers applications call the 14&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined 15yet.</para> 16 17 <para>Video overlay can be considered another I/O method, although 18the application does not directly receive the image data. It is 19selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. 20For more information see <xref linkend="overlay" />.</para> 21 22 <para>Generally exactly one I/O method, including overlay, is 23associated with each file descriptor. The only exceptions are 24applications not exchanging data with a driver ("panel applications", 25see <xref linkend="open" />) and drivers permitting simultaneous video capturing 26and overlay using the same file descriptor, for compatibility with V4L 27and 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, 31but for simplicity drivers need not support switching the I/O method 32(after first switching away from read/write) other than by closing 33and reopening the device.</para> 34 35 <para>The following sections describe the various I/O methods in 36more 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, 43respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in 44the <structfield>capabilities</structfield> field of &v4l2-capability; 45returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> 46 47 <para>Drivers may need the CPU to copy the data, but they may also 48support DMA to or from user memory, so this I/O method is not 49necessarily less efficient than other methods merely exchanging buffer 50pointers. It is considered inferior though because no meta-information 51like frame counters or timestamps are passed. This information is 52necessary to recognize frame dropping and to synchronize with other 53data streams. However this is also the simplest I/O method, requiring 54little or no setup to exchange data. It permits command line stunts 55like this (the <application>vidctrl</application> tool is 56fictitious):</para> 57 58 <informalexample> 59 <screen> 60> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 61> dd if=/dev/video of=myimage.422 bs=202752 count=1 62</screen> 63 </informalexample> 64 65 <para>To read from the device applications use the 66&func-read; function, to write the &func-write; function. 67Drivers must implement one I/O method if they 68exchange data with applications, but it need not be this.<footnote> 69 <para>It would be desirable if applications could depend on 70drivers supporting all I/O interfaces, but as much as the complex 71memory mapping I/O can be inadequate for some devices we have no 72reason to require this interface, which is most useful for simple 73applications capturing still images.</para> 74 </footnote> When reading or writing is supported, the driver 75must also support the &func-select; and &func-poll; 76function.<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; 89returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two 90streaming methods, to determine if the memory mapping flavor is 91supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> 92 93 <para>Streaming is an I/O method where only pointers to buffers 94are exchanged between application and driver, the data itself is not 95copied. Memory mapping is primarily intended to map buffers in device 96memory into the application's address space. Device memory can be for 97example the video memory on a graphics card with a video capture 98add-on. However, being the most efficient I/O method available for a 99long time, many other drivers support streaming as well, allocating 100buffers in DMA-able main memory.</para> 101 102 <para>A driver can support many sets of buffers. Each set is 103identified by a unique buffer type value. The sets are independent and 104each set can hold a different type of data. To access different sets 105at the same time different file descriptors must be used.<footnote> 106 <para>One could use one file descriptor and set the buffer 107type field accordingly when calling &VIDIOC-QBUF; etc., but it makes 108the <function>select()</function> function ambiguous. We also like the 109clean approach of one file descriptor per logical stream. Video 110overlay for example is also a logical stream, although the CPU is not 111needed 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 116type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. 117This ioctl can also be used to change the number of buffers or to free 118the allocated memory, provided none of the buffers are still 119mapped.</para> 120 121 <para>Before applications can access the buffers they must map 122them into their address space with the &func-mmap; function. The 123location 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> 126returned in a &v4l2-buffer; are passed as sixth and second parameter to the 127<function>mmap()</function> function. When using the multi-planar API, 128struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each 129containing its own <structfield>m.offset</structfield> and 130<structfield>length</structfield>. When using the multi-planar API, every 131plane of every buffer has to be mapped separately, so the number of 132calls to &func-mmap; should be equal to number of buffers times number of 133planes in each buffer. The offset and length values must not be modified. 134Remember, the buffers are allocated in physical memory, as opposed to virtual 135memory, which can be swapped out to disk. Applications should free the buffers 136as 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; 142struct { 143 void *start; 144 size_t length; 145} *buffers; 146unsigned int i; 147 148memset(&reqbuf, 0, sizeof(reqbuf)); 149reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 150reqbuf.memory = V4L2_MEMORY_MMAP; 151reqbuf.count = 20; 152 153if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { 154 if (errno == EINVAL) 155 printf("Video capturing or mmap-streaming is not supported\n"); 156 else 157 perror("VIDIOC_REQBUFS"); 158 159 exit(EXIT_FAILURE); 160} 161 162/* We want at least five buffers. */ 163 164if (reqbuf.count < 5) { 165 /* You may need to free the buffers here. */ 166 printf("Not enough buffer memory\n"); 167 exit(EXIT_FAILURE); 168} 169 170buffers = calloc(reqbuf.count, sizeof(*buffers)); 171assert(buffers != NULL); 172 173for (i = 0; i < reqbuf.count; i++) { 174 &v4l2-buffer; buffer; 175 176 memset(&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;, &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 203for (i = 0; i < 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 215struct { 216 void *start[FMT_NUM_PLANES]; 217 size_t length[FMT_NUM_PLANES]; 218} *buffers; 219unsigned int i, j; 220 221memset(&reqbuf, 0, sizeof(reqbuf)); 222reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; 223reqbuf.memory = V4L2_MEMORY_MMAP; 224reqbuf.count = 20; 225 226if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) < 0) { 227 if (errno == EINVAL) 228 printf("Video capturing or mmap-streaming is not supported\n"); 229 else 230 perror("VIDIOC_REQBUFS"); 231 232 exit(EXIT_FAILURE); 233} 234 235/* We want at least five buffers. */ 236 237if (reqbuf.count < 5) { 238 /* You may need to free the buffers here. */ 239 printf("Not enough buffer memory\n"); 240 exit(EXIT_FAILURE); 241} 242 243buffers = calloc(reqbuf.count, sizeof(*buffers)); 244assert(buffers != NULL); 245 246for (i = 0; i < reqbuf.count; i++) { 247 &v4l2-buffer; buffer; 248 &v4l2-plane; planes[FMT_NUM_PLANES]; 249 250 memset(&buffer, 0, sizeof(buffer)); 251 buffer.type = reqbuf.type; 252 buffer.memory = V4L2_MEMORY_MMAP; 253 buffer.index = i; 254 /* length in struct v4l2_buffer in multi-planar API stores the size 255 * of planes array. */ 256 buffer.length = FMT_NUM_PLANES; 257 buffer.m.planes = planes; 258 259 if (ioctl(fd, &VIDIOC-QUERYBUF;, &buffer) < 0) { 260 perror("VIDIOC_QUERYBUF"); 261 exit(EXIT_FAILURE); 262 } 263 264 /* Every plane has to be mapped separately */ 265 for (j = 0; j < FMT_NUM_PLANES; j++) { 266 buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ 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 284for (i = 0; i < reqbuf.count; i++) 285 for (j = 0; j < FMT_NUM_PLANES; j++) 286 munmap(buffers[i].start[j], buffers[i].length[j]); 287 </programlisting> 288 </example> 289 290 <para>Conceptually streaming drivers maintain two buffer queues, an incoming 291and an outgoing queue. They separate the synchronous capture or output 292operation locked to a video clock from the application which is 293subject to random disk or network delays and preemption by 294other processes, thereby reducing the probability of data loss. 295The queues are organized as FIFOs, buffers will be 296output in the order enqueued in the incoming FIFO, and were 297captured in the order dequeued from the outgoing FIFO.</para> 298 299 <para>The driver may require a minimum number of buffers enqueued 300at all times to function, apart of this no limit exists on the number 301of buffers applications can enqueue in advance, or dequeue and 302process. They can also enqueue in a different order than buffers have 303been 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 306images out of order (such as video codecs) to return buffers earlier, 307reducing the probability of data loss. Random fill order allows 308drivers to reuse buffers on a LIFO-basis, taking advantage of caches 309holding 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 312identifies the buffer.</para> 313 314 <para>Initially all mapped buffers are in dequeued state, 315inaccessible by the driver. For capturing applications it is customary 316to first enqueue all mapped buffers, then to start capturing and enter 317the read loop. Here the application waits until a filled buffer can be 318dequeued, and re-enqueues the buffer when the data is no longer 319needed. Output applications fill and enqueue buffers, when enough 320buffers are stacked up the output is started with 321<constant>VIDIOC_STREAMON</constant>. In the write loop, when 322the application runs out of free buffers, it must wait until an empty 323buffer 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 327mapped, enqueued, full or empty can be determined at any time using the 328&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the 329application until one or more buffers can be dequeued. By default 330<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 331outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 332given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 333returns 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 339queues as a side effect. Since there is no notion of doing anything 340"now" on a multitasking system, if an application needs to synchronize 341with another event it should examine the &v4l2-buffer; 342<structfield>timestamp</structfield> of captured buffers, or set the 343field before enqueuing buffers for output.</para> 344 345 <para>Drivers implementing memory mapping I/O must 346support 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> 353function.<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 357rest 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; 370returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user 371pointer method (not only memory mapping) is supported must be 372determined by calling the &VIDIOC-REQBUFS; ioctl.</para> 373 374 <para>This I/O method combines advantages of the read/write and 375memory mapping methods. Buffers (planes) are allocated by the application 376itself, and can reside for example in virtual or shared memory. Only 377pointers to data are exchanged, these pointers and meta-information 378are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). 379The 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 381beforehand, consequently they are not indexed and cannot be queried like mapped 382buffers 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 390memset (&reqbuf, 0, sizeof (reqbuf)); 391reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 392reqbuf.memory = V4L2_MEMORY_USERPTR; 393 394if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { 395 if (errno == EINVAL) 396 printf ("Video capturing or user pointer streaming is not supported\n"); 397 else 398 perror ("VIDIOC_REQBUFS"); 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, 407applications can pass different addresses and sizes at each 408<constant>VIDIOC_QBUF</constant> call. If required by the hardware the 409driver swaps memory pages within physical memory to create a 410continuous area of memory. This happens transparently to the 411application in the virtual memory subsystem of the kernel. When buffer 412pages have been swapped out to disk they are brought back and finally 413locked in physical memory for DMA.<footnote> 414 <para>We expect that frequently used buffers are typically not 415swapped out. Anyway, the process of swapping, locking or generating 416scatter-gather lists may be time consuming. The delay can be masked by 417the depth of the incoming buffer queue, and perhaps by maintaining 418caches assuming a buffer will be soon enqueued again. On the other 419hand, to optimize memory usage drivers can limit the number of buffers 420locked in advance and recycle the most recently used buffers first. Of 421course, the pages of empty buffers in the incoming queue need not be 422saved to disk. Output buffers must be saved on the incoming and 423outgoing queue because an application may share them with other 424processes.</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 429time between the completion of the DMA and this ioctl. The memory is 430also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or 431when the device is closed. Applications must take care not to free 432buffers without dequeuing. For once, the buffers remain locked until 433further, wasting physical memory. Second the driver will not be 434notified when the memory is returned to the application's free list 435and subsequently reused for other purposes, possibly completing the 436requested DMA and overwriting valuable data.</para> 437 438 <para>For capturing applications it is customary to enqueue a 439number of empty buffers, to start capturing and enter the read loop. 440Here the application waits until a filled buffer can be dequeued, and 441re-enqueues the buffer when the data is no longer needed. Output 442applications fill and enqueue buffers, when enough buffers are stacked 443up output is started. In the write loop, when the application 444runs out of free buffers it must wait until an empty buffer can be 445dequeued and reused. Two methods exist to suspend execution of the 446application until one or more buffers can be dequeued. By default 447<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 448outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 449given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 450returns 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 456queues and unlocks all buffers as a side effect. Since there is no 457notion of doing anything "now" on a multitasking system, if an 458application needs to synchronize with another event it should examine 459the &v4l2-buffer; <structfield>timestamp</structfield> of captured 460buffers, or set the field before enqueuing buffers for output.</para> 461 462 <para>Drivers implementing user pointer I/O must 463support 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 471rest 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 485between multiple devices. Device drivers that support DMABUF can export a DMA 486buffer to userspace as a file descriptor (known as the exporter role), import a 487DMA buffer from userspace using a file descriptor previously exported for a 488different or the same device (known as the importer role), or both. This 489section describes the DMABUF importer role API in V4L2.</para> 490 491 <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for 492details 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 497the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through 498DMABUF 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 503devices, which may be V4L devices or other video-related devices (e.g. DRM). 504Buffers (planes) are allocated by a driver on behalf of an application. Next, 505these buffers are exported to the application as file descriptors using an API 506which is specific for an allocator driver. Only such file descriptor are 507exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or 508in &v4l2-plane; in the multi-planar API case). The driver must be switched 509into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer 510type.</para> 511 512 <example> 513 <title>Initiating streaming I/O with DMABUF file descriptors</title> 514 515 <programlisting> 516&v4l2-requestbuffers; reqbuf; 517 518memset(&reqbuf, 0, sizeof (reqbuf)); 519reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 520reqbuf.memory = V4L2_MEMORY_DMABUF; 521reqbuf.count = 1; 522 523if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { 524 if (errno == EINVAL) 525 printf("Video capturing or DMABUF streaming is not supported\n"); 526 else 527 perror("VIDIOC_REQBUFS"); 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 536associated with a different DMABUF descriptor. Although buffers are commonly 537cycled, 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> 544int buffer_queue(int v4lfd, int index, int dmafd) 545{ 546 &v4l2-buffer; buf; 547 548 memset(&buf, 0, sizeof buf); 549 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 550 buf.memory = V4L2_MEMORY_DMABUF; 551 buf.index = index; 552 buf.m.fd = dmafd; 553 554 if (ioctl(v4lfd, &VIDIOC-QBUF;, &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> 568int 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(&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(&planes, 0, sizeof planes); 582 583 for (i = 0; i < n_planes; ++i) 584 buf.m.planes[i].m.fd = dmafd[i]; 585 586 if (ioctl(v4lfd, &VIDIOC-QBUF;, &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 598time between the completion of the DMA and this ioctl. The memory is 599also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or 600when the device is closed.</para> 601 602 <para>For capturing applications it is customary to enqueue a 603number of empty buffers, to start capturing and enter the read loop. 604Here the application waits until a filled buffer can be dequeued, and 605re-enqueues the buffer when the data is no longer needed. Output 606applications fill and enqueue buffers, when enough buffers are stacked 607up output is started. In the write loop, when the application 608runs out of free buffers it must wait until an empty buffer can be 609dequeued and reused. Two methods exist to suspend execution of the 610application until one or more buffers can be dequeued. By default 611<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 612outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 613given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 614returns 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 620unlocks all buffers as a side effect. Since there is no notion of doing 621anything "now" on a multitasking system, if an application needs to synchronize 622with another event it should examine the &v4l2-buffer; 623<structfield>timestamp</structfield> of captured buffers, or set the field 624before 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 644driver using one of the Streaming I/O methods. In the multi-planar API, the 645data is held in planes, while the buffer structure acts as a container 646for the planes. Only pointers to buffers (planes) are exchanged, the data 647itself is not copied. These pointers, together with meta-information like 648timestamps or field parity, are stored in a struct 649<structname>v4l2_buffer</structname>, argument to 650the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. 651In the multi-planar API, some plane-specific members of struct 652<structname>v4l2_buffer</structname>, such as pointers and sizes for each 653plane, are stored in struct <structname>v4l2_plane</structname> instead. 654In that case, struct <structname>v4l2_buffer</structname> contains an array of 655plane structures.</para> 656 657 <para>Nominally timestamps refer to the first data byte transmitted. 658In practice however the wide range of hardware covered by the V4L2 API 659limits timestamp accuracy. Often an interrupt routine will 660sample the system clock shortly after the field or frame was stored 661completely in memory. So applications must expect a constant 662difference up to one field or frame period plus a small (few scan 663lines) random error. The delay and error can be much 664larger due to compression or transmission over an external bus when 665the frames are not properly stamped by the sender. This is frequently 666the case with USB cameras. Here timestamps refer to the instant the 667field or frame was received by the driver, not the capture time. These 668devices identify by not enumerating any video standards, see <xref 669linkend="standard" />.</para> 670 671 <para>Similar limitations apply to output timestamps. Typically 672the video hardware locks to a clock controlling the video timing, the 673horizontal and vertical synchronization pulses. At some point in the 674line sequence, possibly the vertical blanking, an interrupt routine 675samples the system clock, compares against the timestamp and programs 676the hardware to repeat the previous field or frame, or to display the 677buffer contents.</para> 678 679 <para>Apart of limitations of the video device and natural 680inaccuracies of all clocks, it should be noted system time itself is 681not perfectly stable. It can be affected by power saving cycles, 682warped to insert leap seconds, or even turned back or forth by the 683system administrator affecting long term measurements. <footnote> 684 <para>Since no other Linux multimedia 685API supports unadjusted time it would be foolish to introduce here. We 686must use a universally supported clock to synchronize different media, 687hence 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 700field is only used for <link linkend="mmap">memory mapping</link> I/O 701and can range from zero to the number of buffers allocated 702with 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 711linkend="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 718buffer. It depends on the negotiated data format and may change with 719each buffer for compressed variable size data like JPEG images. 720Drivers must set this field when <structfield>type</structfield> 721refers 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 728linkend="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 735buffer, see <xref linkend="v4l2-field" />. This field is not used when 736the buffer contains VBI data. Drivers must set it when 737<structfield>type</structfield> refers to an input stream, 738applications 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 time when the first data 745 byte was captured, as returned by the 746 <function>clock_gettime()</function> function for the relevant 747 clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in 748 <xref linkend="buffer-flags" />. For output streams the data 749 will not be displayed before this time, secondary to the nominal 750 frame rate determined by the current video standard in enqueued 751 order. Applications can for example zero this field to display 752 frames as soon as possible. The driver stores the time at which 753 the first data byte was actually sent out in the 754 <structfield>timestamp</structfield> field. This permits 755 applications to monitor the drift between the video and system 756 clock.</para></entry> 757 </row> 758 <row> 759 <entry>&v4l2-timecode;</entry> 760 <entry><structfield>timecode</structfield></entry> 761 <entry></entry> 762 <entry>When <structfield>type</structfield> is 763<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the 764<constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in 765<structfield>flags</structfield>, this structure contains a frame 766timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> 767mode the top and bottom field contain the same timecode. 768Timecodes are intended to help video editing and are typically recorded on 769video tapes, but also embedded in compressed formats like MPEG. This 770field is independent of the <structfield>timestamp</structfield> and 771<structfield>sequence</structfield> fields.</entry> 772 </row> 773 <row> 774 <entry>__u32</entry> 775 <entry><structfield>sequence</structfield></entry> 776 <entry></entry> 777 <entry>Set by the driver, counting the frames (not fields!) in 778sequence. This field is set for both input and output devices.</entry> 779 </row> 780 <row> 781 <entry spanname="hspan"><para>In <link 782linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and 783bottom field have the same sequence number. The count starts at zero 784and includes dropped or repeated frames. A dropped frame was received 785by an input device but could not be stored due to lack of free buffer 786space. A repeated frame was displayed again by an output device 787because the application did not pass new data in 788time.</para><para>Note this may count the frames received 789e.g. over USB, without taking into account the frames dropped by the 790remote hardware due to limited compression throughput or bus 791bandwidth. These devices identify by not enumerating any video 792standards, see <xref linkend="standard" />.</para></entry> 793 </row> 794 <row> 795 <entry>__u32</entry> 796 <entry><structfield>memory</structfield></entry> 797 <entry></entry> 798 <entry>This field must be set by applications and/or drivers 799in accordance with the selected I/O method. See <xref linkend="v4l2-memory" 800 /></entry> 801 </row> 802 <row> 803 <entry>union</entry> 804 <entry><structfield>m</structfield></entry> 805 </row> 806 <row> 807 <entry></entry> 808 <entry>__u32</entry> 809 <entry><structfield>offset</structfield></entry> 810 <entry>For the single-planar API and when 811<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this 812is the offset of the buffer from the start of the device memory. The value is 813returned by the driver and apart of serving as parameter to the &func-mmap; 814function not useful for applications. See <xref linkend="mmap" /> for details 815 </entry> 816 </row> 817 <row> 818 <entry></entry> 819 <entry>unsigned long</entry> 820 <entry><structfield>userptr</structfield></entry> 821 <entry>For the single-planar API and when 822<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant> 823this is a pointer to the buffer (casted to unsigned long type) in virtual 824memory, set by the application. See <xref linkend="userp" /> for details. 825 </entry> 826 </row> 827 <row> 828 <entry></entry> 829 <entry>struct v4l2_plane</entry> 830 <entry><structfield>*planes</structfield></entry> 831 <entry>When using the multi-planar API, contains a userspace pointer 832 to an array of &v4l2-plane;. The size of the array should be put 833 in the <structfield>length</structfield> field of this 834 <structname>v4l2_buffer</structname> structure.</entry> 835 </row> 836 <row> 837 <entry></entry> 838 <entry>int</entry> 839 <entry><structfield>fd</structfield></entry> 840 <entry>For the single-plane API and when 841<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this 842is the file descriptor associated with a DMABUF buffer.</entry> 843 </row> 844 <row> 845 <entry>__u32</entry> 846 <entry><structfield>length</structfield></entry> 847 <entry></entry> 848 <entry>Size of the buffer (not the payload) in bytes for the 849 single-planar API. For the multi-planar API the application sets 850 this to the number of elements in the <structfield>planes</structfield> 851 array. The driver will fill in the actual number of valid elements in 852 that array. 853 </entry> 854 </row> 855 <row> 856 <entry>__u32</entry> 857 <entry><structfield>reserved2</structfield></entry> 858 <entry></entry> 859 <entry>A place holder for future extensions. Applications 860should set this to 0.</entry> 861 </row> 862 <row> 863 <entry>__u32</entry> 864 <entry><structfield>reserved</structfield></entry> 865 <entry></entry> 866 <entry>A place holder for future extensions. Applications 867should set this to 0.</entry> 868 </row> 869 </tbody> 870 </tgroup> 871 </table> 872 873 <table frame="none" pgwide="1" id="v4l2-plane"> 874 <title>struct <structname>v4l2_plane</structname></title> 875 <tgroup cols="4"> 876 &cs-ustr; 877 <tbody valign="top"> 878 <row> 879 <entry>__u32</entry> 880 <entry><structfield>bytesused</structfield></entry> 881 <entry></entry> 882 <entry>The number of bytes occupied by data in the plane 883 (its payload).</entry> 884 </row> 885 <row> 886 <entry>__u32</entry> 887 <entry><structfield>length</structfield></entry> 888 <entry></entry> 889 <entry>Size in bytes of the plane (not its payload).</entry> 890 </row> 891 <row> 892 <entry>union</entry> 893 <entry><structfield>m</structfield></entry> 894 <entry></entry> 895 <entry></entry> 896 </row> 897 <row> 898 <entry></entry> 899 <entry>__u32</entry> 900 <entry><structfield>mem_offset</structfield></entry> 901 <entry>When the memory type in the containing &v4l2-buffer; is 902 <constant>V4L2_MEMORY_MMAP</constant>, this is the value that 903 should be passed to &func-mmap;, similar to the 904 <structfield>offset</structfield> field in &v4l2-buffer;.</entry> 905 </row> 906 <row> 907 <entry></entry> 908 <entry>unsigned long</entry> 909 <entry><structfield>userptr</structfield></entry> 910 <entry>When the memory type in the containing &v4l2-buffer; is 911 <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace 912 pointer to the memory allocated for this plane by an application. 913 </entry> 914 </row> 915 <row> 916 <entry></entry> 917 <entry>int</entry> 918 <entry><structfield>fd</structfield></entry> 919 <entry>When the memory type in the containing &v4l2-buffer; is 920 <constant>V4L2_MEMORY_DMABUF</constant>, this is a file 921 descriptor associated with a DMABUF buffer, similar to the 922 <structfield>fd</structfield> field in &v4l2-buffer;.</entry> 923 </row> 924 <row> 925 <entry>__u32</entry> 926 <entry><structfield>data_offset</structfield></entry> 927 <entry></entry> 928 <entry>Offset in bytes to video data in the plane, if applicable. 929 </entry> 930 </row> 931 <row> 932 <entry>__u32</entry> 933 <entry><structfield>reserved[11]</structfield></entry> 934 <entry></entry> 935 <entry>Reserved for future use. Should be zeroed by an 936 application.</entry> 937 </row> 938 </tbody> 939 </tgroup> 940 </table> 941 942 <table frame="none" pgwide="1" id="v4l2-buf-type"> 943 <title>enum v4l2_buf_type</title> 944 <tgroup cols="3"> 945 &cs-def; 946 <tbody valign="top"> 947 <row> 948 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> 949 <entry>1</entry> 950 <entry>Buffer of a single-planar video capture stream, see <xref 951 linkend="capture" />.</entry> 952 </row> 953 <row> 954 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> 955 </entry> 956 <entry>9</entry> 957 <entry>Buffer of a multi-planar video capture stream, see <xref 958 linkend="capture" />.</entry> 959 </row> 960 <row> 961 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> 962 <entry>2</entry> 963 <entry>Buffer of a single-planar video output stream, see <xref 964 linkend="output" />.</entry> 965 </row> 966 <row> 967 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> 968 </entry> 969 <entry>10</entry> 970 <entry>Buffer of a multi-planar video output stream, see <xref 971 linkend="output" />.</entry> 972 </row> 973 <row> 974 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> 975 <entry>3</entry> 976 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> 977 </row> 978 <row> 979 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> 980 <entry>4</entry> 981 <entry>Buffer of a raw VBI capture stream, see <xref 982 linkend="raw-vbi" />.</entry> 983 </row> 984 <row> 985 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> 986 <entry>5</entry> 987 <entry>Buffer of a raw VBI output stream, see <xref 988 linkend="raw-vbi" />.</entry> 989 </row> 990 <row> 991 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> 992 <entry>6</entry> 993 <entry>Buffer of a sliced VBI capture stream, see <xref 994 linkend="sliced" />.</entry> 995 </row> 996 <row> 997 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> 998 <entry>7</entry> 999 <entry>Buffer of a sliced VBI output stream, see <xref 1000 linkend="sliced" />.</entry> 1001 </row> 1002 <row> 1003 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> 1004 <entry>8</entry> 1005 <entry>Buffer for video output overlay (OSD), see <xref 1006 linkend="osd" />.</entry> 1007 </row> 1008 </tbody> 1009 </tgroup> 1010 </table> 1011 1012 <table frame="none" pgwide="1" id="buffer-flags"> 1013 <title>Buffer Flags</title> 1014 <tgroup cols="3"> 1015 &cs-def; 1016 <tbody valign="top"> 1017 <row> 1018 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> 1019 <entry>0x0001</entry> 1020 <entry>The buffer resides in device memory and has been mapped 1021into the application's address space, see <xref linkend="mmap" /> for details. 1022Drivers set or clear this flag when the 1023<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link 1024 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link 1025 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> 1026 </row> 1027 <row> 1028 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> 1029 <entry>0x0002</entry> 1030 <entry>Internally drivers maintain two buffer queues, an 1031incoming and outgoing queue. When this flag is set, the buffer is 1032currently on the incoming queue. It automatically moves to the 1033outgoing queue after the buffer has been filled (capture devices) or 1034displayed (output devices). Drivers set or clear this flag when the 1035<constant>VIDIOC_QUERYBUF</constant> ioctl is called. After 1036(successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is 1037always set and after <constant>VIDIOC_DQBUF</constant> always 1038cleared.</entry> 1039 </row> 1040 <row> 1041 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> 1042 <entry>0x0004</entry> 1043 <entry>When this flag is set, the buffer is currently on 1044the outgoing queue, ready to be dequeued from the driver. Drivers set 1045or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl 1046is called. After calling the <constant>VIDIOC_QBUF</constant> or 1047<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a 1048buffer cannot be on both queues at the same time, the 1049<constant>V4L2_BUF_FLAG_QUEUED</constant> and 1050<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. 1051They can be both cleared however, then the buffer is in "dequeued" 1052state, in the application domain to say so.</entry> 1053 </row> 1054 <row> 1055 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry> 1056 <entry>0x0040</entry> 1057 <entry>When this flag is set, the buffer has been dequeued 1058 successfully, although the data might have been corrupted. 1059 This is recoverable, streaming may continue as normal and 1060 the buffer may be reused normally. 1061 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant> 1062 ioctl is called.</entry> 1063 </row> 1064 <row> 1065 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> 1066 <entry>0x0008</entry> 1067 <entry>Drivers set or clear this flag when calling the 1068<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video 1069capture devices when the buffer contains a compressed image which is a 1070key frame (or field), &ie; can be decompressed on its own.</entry> 1071 </row> 1072 <row> 1073 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> 1074 <entry>0x0010</entry> 1075 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> 1076this flags predicted frames or fields which contain only differences to a 1077previous key frame.</entry> 1078 </row> 1079 <row> 1080 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> 1081 <entry>0x0020</entry> 1082 <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant> 1083 this is a bidirectional predicted frame or field. [ooc tbd]</entry> 1084 </row> 1085 <row> 1086 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> 1087 <entry>0x0100</entry> 1088 <entry>The <structfield>timecode</structfield> field is valid. 1089Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> 1090ioctl is called.</entry> 1091 </row> 1092 <row> 1093 <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> 1094 <entry>0x0400</entry> 1095 <entry>The buffer has been prepared for I/O and can be queued by the 1096application. Drivers set or clear this flag when the 1097<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link 1098 linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link 1099 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link 1100 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry> 1101 </row> 1102 <row> 1103 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> 1104 <entry>0x0800</entry> 1105 <entry>Caches do not have to be invalidated for this buffer. 1106Typically applications shall use this flag if the data captured in the buffer 1107is not going to be touched by the CPU, instead the buffer will, probably, be 1108passed on to a DMA-capable hardware unit for further processing or output. 1109</entry> 1110 </row> 1111 <row> 1112 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> 1113 <entry>0x1000</entry> 1114 <entry>Caches do not have to be cleaned for this buffer. 1115Typically applications shall use this flag for output buffers if the data 1116in this buffer has not been created by the CPU but by some DMA-capable unit, 1117in which case caches have not been used.</entry> 1118 </row> 1119 <row> 1120 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry> 1121 <entry>0xe000</entry> 1122 <entry>Mask for timestamp types below. To test the 1123 timestamp type, mask out bits not belonging to timestamp 1124 type by performing a logical and operation with buffer 1125 flags and timestamp mask.</entry> 1126 </row> 1127 <row> 1128 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry> 1129 <entry>0x0000</entry> 1130 <entry>Unknown timestamp type. This type is used by 1131 drivers before Linux 3.9 and may be either monotonic (see 1132 below) or realtime (wall clock). Monotonic clock has been 1133 favoured in embedded systems whereas most of the drivers 1134 use the realtime clock. Either kinds of timestamps are 1135 available in user space via 1136 <function>clock_gettime(2)</function> using clock IDs 1137 <constant>CLOCK_MONOTONIC</constant> and 1138 <constant>CLOCK_REALTIME</constant>, respectively.</entry> 1139 </row> 1140 <row> 1141 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry> 1142 <entry>0x2000</entry> 1143 <entry>The buffer timestamp has been taken from the 1144 <constant>CLOCK_MONOTONIC</constant> clock. To access the 1145 same clock outside V4L2, use 1146 <function>clock_gettime(2)</function> .</entry> 1147 </row> 1148 <row> 1149 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry> 1150 <entry>0x4000</entry> 1151 <entry>The CAPTURE buffer timestamp has been taken from the 1152 corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry> 1153 </row> 1154 </tbody> 1155 </tgroup> 1156 </table> 1157 1158 <table pgwide="1" frame="none" id="v4l2-memory"> 1159 <title>enum v4l2_memory</title> 1160 <tgroup cols="3"> 1161 &cs-def; 1162 <tbody valign="top"> 1163 <row> 1164 <entry><constant>V4L2_MEMORY_MMAP</constant></entry> 1165 <entry>1</entry> 1166 <entry>The buffer is used for <link linkend="mmap">memory 1167mapping</link> I/O.</entry> 1168 </row> 1169 <row> 1170 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> 1171 <entry>2</entry> 1172 <entry>The buffer is used for <link linkend="userp">user 1173pointer</link> I/O.</entry> 1174 </row> 1175 <row> 1176 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> 1177 <entry>3</entry> 1178 <entry>[to do]</entry> 1179 </row> 1180 <row> 1181 <entry><constant>V4L2_MEMORY_DMABUF</constant></entry> 1182 <entry>4</entry> 1183 <entry>The buffer is used for <link linkend="dmabuf">DMA shared 1184buffer</link> I/O.</entry> 1185 </row> 1186 </tbody> 1187 </tgroup> 1188 </table> 1189 1190 <section> 1191 <title>Timecodes</title> 1192 1193 <para>The <structname>v4l2_timecode</structname> structure is 1194designed to hold a <xref linkend="smpte12m" /> or similar timecode. 1195(struct <structname>timeval</structname> timestamps are stored in 1196&v4l2-buffer; field <structfield>timestamp</structfield>.)</para> 1197 1198 <table frame="none" pgwide="1" id="v4l2-timecode"> 1199 <title>struct <structname>v4l2_timecode</structname></title> 1200 <tgroup cols="3"> 1201 &cs-str; 1202 <tbody valign="top"> 1203 <row> 1204 <entry>__u32</entry> 1205 <entry><structfield>type</structfield></entry> 1206 <entry>Frame rate the timecodes are based on, see <xref 1207 linkend="timecode-type" />.</entry> 1208 </row> 1209 <row> 1210 <entry>__u32</entry> 1211 <entry><structfield>flags</structfield></entry> 1212 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> 1213 </row> 1214 <row> 1215 <entry>__u8</entry> 1216 <entry><structfield>frames</structfield></entry> 1217 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the 1218 type of timecode.</entry> 1219 </row> 1220 <row> 1221 <entry>__u8</entry> 1222 <entry><structfield>seconds</structfield></entry> 1223 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> 1224 </row> 1225 <row> 1226 <entry>__u8</entry> 1227 <entry><structfield>minutes</structfield></entry> 1228 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> 1229 </row> 1230 <row> 1231 <entry>__u8</entry> 1232 <entry><structfield>hours</structfield></entry> 1233 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> 1234 </row> 1235 <row> 1236 <entry>__u8</entry> 1237 <entry><structfield>userbits</structfield>[4]</entry> 1238 <entry>The "user group" bits from the timecode.</entry> 1239 </row> 1240 </tbody> 1241 </tgroup> 1242 </table> 1243 1244 <table frame="none" pgwide="1" id="timecode-type"> 1245 <title>Timecode Types</title> 1246 <tgroup cols="3"> 1247 &cs-def; 1248 <tbody valign="top"> 1249 <row> 1250 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> 1251 <entry>1</entry> 1252 <entry>24 frames per second, i. e. film.</entry> 1253 </row> 1254 <row> 1255 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> 1256 <entry>2</entry> 1257 <entry>25 frames per second, &ie; PAL or SECAM video.</entry> 1258 </row> 1259 <row> 1260 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> 1261 <entry>3</entry> 1262 <entry>30 frames per second, &ie; NTSC video.</entry> 1263 </row> 1264 <row> 1265 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> 1266 <entry>4</entry> 1267 <entry></entry> 1268 </row> 1269 <row> 1270 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> 1271 <entry>5</entry> 1272 <entry></entry> 1273 </row> 1274 </tbody> 1275 </tgroup> 1276 </table> 1277 1278 <table frame="none" pgwide="1" id="timecode-flags"> 1279 <title>Timecode Flags</title> 1280 <tgroup cols="3"> 1281 &cs-def; 1282 <tbody valign="top"> 1283 <row> 1284 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> 1285 <entry>0x0001</entry> 1286 <entry>Indicates "drop frame" semantics for counting frames 1287in 29.97 fps material. When set, frame numbers 0 and 1 at the start of 1288each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the 1289count.</entry> 1290 </row> 1291 <row> 1292 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> 1293 <entry>0x0002</entry> 1294 <entry>The "color frame" flag.</entry> 1295 </row> 1296 <row> 1297 <entry><constant>V4L2_TC_USERBITS_field</constant></entry> 1298 <entry>0x000C</entry> 1299 <entry>Field mask for the "binary group flags".</entry> 1300 </row> 1301 <row> 1302 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> 1303 <entry>0x0000</entry> 1304 <entry>Unspecified format.</entry> 1305 </row> 1306 <row> 1307 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> 1308 <entry>0x0008</entry> 1309 <entry>8-bit ISO characters.</entry> 1310 </row> 1311 </tbody> 1312 </tgroup> 1313 </table> 1314 </section> 1315 </section> 1316 1317 <section id="field-order"> 1318 <title>Field Order</title> 1319 1320 <para>We have to distinguish between progressive and interlaced 1321video. Progressive video transmits all lines of a video image 1322sequentially. Interlaced video divides an image into two fields, 1323containing only the odd and even lines of the image, respectively. 1324Alternating the so called odd and even field are transmitted, and due 1325to a small delay between fields a cathode ray TV displays the lines 1326interleaved, yielding the original frame. This curious technique was 1327invented because at refresh rates similar to film the image would 1328fade out too quickly. Transmitting fields reduces the flicker without 1329the necessity of doubling the frame rate and with it the bandwidth 1330required for each channel.</para> 1331 1332 <para>It is important to understand a video camera does not expose 1333one frame at a time, merely transmitting the frames separated into 1334fields. The fields are in fact captured at two different instances in 1335time. An object on screen may well move between one field and the 1336next. For applications analysing motion it is of paramount importance 1337to recognize which field of a frame is older, the <emphasis>temporal 1338order</emphasis>.</para> 1339 1340 <para>When the driver provides or accepts images field by field 1341rather than interleaved, it is also important applications understand 1342how the fields combine to frames. We distinguish between top (aka odd) and 1343bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line 1344of the top field is the first line of an interlaced frame, the first 1345line of the bottom field is the second line of that frame.</para> 1346 1347 <para>However because fields were captured one after the other, 1348arguing whether a frame commences with the top or bottom field is 1349pointless. Any two successive top and bottom, or bottom and top fields 1350yield a valid frame. Only when the source was progressive to begin 1351with, ⪚ when transferring film to video, two fields may come from 1352the same frame, creating a natural order.</para> 1353 1354 <para>Counter to intuition the top field is not necessarily the 1355older field. Whether the older field contains the top or bottom lines 1356is a convention determined by the video standard. Hence the 1357distinction between temporal and spatial order of fields. The diagrams 1358below should make this clearer.</para> 1359 1360 <para>All video capture and output devices must report the current 1361field order. Some drivers may permit the selection of a different 1362order, to this end applications initialize the 1363<structfield>field</structfield> field of &v4l2-pix-format; before 1364calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should 1365have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> 1366 1367 <table frame="none" pgwide="1" id="v4l2-field"> 1368 <title>enum v4l2_field</title> 1369 <tgroup cols="3"> 1370 &cs-def; 1371 <tbody valign="top"> 1372 <row> 1373 <entry><constant>V4L2_FIELD_ANY</constant></entry> 1374 <entry>0</entry> 1375 <entry>Applications request this field order when any 1376one of the <constant>V4L2_FIELD_NONE</constant>, 1377<constant>V4L2_FIELD_TOP</constant>, 1378<constant>V4L2_FIELD_BOTTOM</constant>, or 1379<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. 1380Drivers choose depending on hardware capabilities or e. g. the 1381requested image size, and return the actual field order. &v4l2-buffer; 1382<structfield>field</structfield> can never be 1383<constant>V4L2_FIELD_ANY</constant>.</entry> 1384 </row> 1385 <row> 1386 <entry><constant>V4L2_FIELD_NONE</constant></entry> 1387 <entry>1</entry> 1388 <entry>Images are in progressive format, not interlaced. 1389The driver may also indicate this order when it cannot distinguish 1390between <constant>V4L2_FIELD_TOP</constant> and 1391<constant>V4L2_FIELD_BOTTOM</constant>.</entry> 1392 </row> 1393 <row> 1394 <entry><constant>V4L2_FIELD_TOP</constant></entry> 1395 <entry>2</entry> 1396 <entry>Images consist of the top (aka odd) field only.</entry> 1397 </row> 1398 <row> 1399 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> 1400 <entry>3</entry> 1401 <entry>Images consist of the bottom (aka even) field only. 1402Applications may wish to prevent a device from capturing interlaced 1403images because they will have "comb" or "feathering" artefacts around 1404moving objects.</entry> 1405 </row> 1406 <row> 1407 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> 1408 <entry>4</entry> 1409 <entry>Images contain both fields, interleaved line by 1410line. The temporal order of the fields (whether the top or bottom 1411field is first transmitted) depends on the current video standard. 1412M/NTSC transmits the bottom field first, all other standards the top 1413field first.</entry> 1414 </row> 1415 <row> 1416 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> 1417 <entry>5</entry> 1418 <entry>Images contain both fields, the top field lines 1419are stored first in memory, immediately followed by the bottom field 1420lines. Fields are always stored in temporal order, the older one first 1421in memory. Image sizes refer to the frame, not fields.</entry> 1422 </row> 1423 <row> 1424 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> 1425 <entry>6</entry> 1426 <entry>Images contain both fields, the bottom field 1427lines are stored first in memory, immediately followed by the top 1428field lines. Fields are always stored in temporal order, the older one 1429first in memory. Image sizes refer to the frame, not fields.</entry> 1430 </row> 1431 <row> 1432 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> 1433 <entry>7</entry> 1434 <entry>The two fields of a frame are passed in separate 1435buffers, in temporal order, &ie; the older one first. To indicate the field 1436parity (whether the current field is a top or bottom field) the driver 1437or application, depending on data direction, must set &v4l2-buffer; 1438<structfield>field</structfield> to 1439<constant>V4L2_FIELD_TOP</constant> or 1440<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair 1441to build a frame. If fields are successive, without any dropped fields 1442between them (fields can drop individually), can be determined from 1443the &v4l2-buffer; <structfield>sequence</structfield> field. Image 1444sizes refer to the frame, not fields. This format cannot be selected 1445when using the read/write I/O method.<!-- Where it's indistinguishable 1446from V4L2_FIELD_SEQ_*. --></entry> 1447 </row> 1448 <row> 1449 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> 1450 <entry>8</entry> 1451 <entry>Images contain both fields, interleaved line by 1452line, top field first. The top field is transmitted first.</entry> 1453 </row> 1454 <row> 1455 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> 1456 <entry>9</entry> 1457 <entry>Images contain both fields, interleaved line by 1458line, top field first. The bottom field is transmitted first.</entry> 1459 </row> 1460 </tbody> 1461 </tgroup> 1462 </table> 1463 1464 <figure id="fieldseq-tb"> 1465 <title>Field Order, Top Field First Transmitted</title> 1466 <mediaobject> 1467 <imageobject> 1468 <imagedata fileref="fieldseq_tb.pdf" format="PS" /> 1469 </imageobject> 1470 <imageobject> 1471 <imagedata fileref="fieldseq_tb.gif" format="GIF" /> 1472 </imageobject> 1473 </mediaobject> 1474 </figure> 1475 1476 <figure id="fieldseq-bt"> 1477 <title>Field Order, Bottom Field First Transmitted</title> 1478 <mediaobject> 1479 <imageobject> 1480 <imagedata fileref="fieldseq_bt.pdf" format="PS" /> 1481 </imageobject> 1482 <imageobject> 1483 <imagedata fileref="fieldseq_bt.gif" format="GIF" /> 1484 </imageobject> 1485 </mediaobject> 1486 </figure> 1487 </section> 1488
