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, 128&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 or outputted buffers. 343</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 460or outputted buffers.</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 or outputted buffers.</para> 624 625 <para>Drivers implementing DMABUF importing I/O must support the 626<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>, 627<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and 628<constant>VIDIOC_STREAMOFF</constant> ioctls, and the 629<function>select()</function> and <function>poll()</function> functions.</para> 630 631 </section> 632 633 <section id="async"> 634 <title>Asynchronous I/O</title> 635 636 <para>This method is not defined yet.</para> 637 </section> 638 639 <section id="buffer"> 640 <title>Buffers</title> 641 642 <para>A buffer contains data exchanged by application and 643driver using one of the Streaming I/O methods. In the multi-planar API, the 644data is held in planes, while the buffer structure acts as a container 645for the planes. Only pointers to buffers (planes) are exchanged, the data 646itself is not copied. These pointers, together with meta-information like 647timestamps or field parity, are stored in a struct 648<structname>v4l2_buffer</structname>, argument to 649the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. 650In the multi-planar API, some plane-specific members of struct 651<structname>v4l2_buffer</structname>, such as pointers and sizes for each 652plane, are stored in struct <structname>v4l2_plane</structname> instead. 653In that case, struct <structname>v4l2_buffer</structname> contains an array of 654plane structures.</para> 655 656 <para>Dequeued video buffers come with timestamps. The driver 657 decides at which part of the frame and with which clock the 658 timestamp is taken. Please see flags in the masks 659 <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and 660 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref 661 linkend="buffer-flags" />. These flags are always valid and constant 662 across all buffers during the whole video stream. Changes in these 663 flags may take place as a side effect of &VIDIOC-S-INPUT; or 664 &VIDIOC-S-OUTPUT; however. The 665 <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type 666 which is used by e.g. on mem-to-mem devices is an exception to the 667 rule: the timestamp source flags are copied from the OUTPUT video 668 buffer to the CAPTURE video buffer.</para> 669 670 <table frame="none" pgwide="1" id="v4l2-buffer"> 671 <title>struct <structname>v4l2_buffer</structname></title> 672 <tgroup cols="4"> 673 &cs-ustr; 674 <tbody valign="top"> 675 <row> 676 <entry>__u32</entry> 677 <entry><structfield>index</structfield></entry> 678 <entry></entry> 679 <entry>Number of the buffer, set by the application except 680when calling &VIDIOC-DQBUF;, then it is set by the driver. 681This field can range from zero to the number of buffers allocated 682with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>), 683plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry> 684 </row> 685 <row> 686 <entry>__u32</entry> 687 <entry><structfield>type</structfield></entry> 688 <entry></entry> 689 <entry>Type of the buffer, same as &v4l2-format; 690<structfield>type</structfield> or &v4l2-requestbuffers; 691<structfield>type</structfield>, set by the application. See <xref 692linkend="v4l2-buf-type" /></entry> 693 </row> 694 <row> 695 <entry>__u32</entry> 696 <entry><structfield>bytesused</structfield></entry> 697 <entry></entry> 698 <entry>The number of bytes occupied by the data in the 699buffer. It depends on the negotiated data format and may change with 700each buffer for compressed variable size data like JPEG images. 701Drivers must set this field when <structfield>type</structfield> 702refers to an input stream, applications when it refers to an output stream. 703If the application sets this to 0 for an output stream, then 704<structfield>bytesused</structfield> will be set to the size of the 705buffer (see the <structfield>length</structfield> field of this struct) by 706the driver. For multiplanar formats this field is ignored and the 707<structfield>planes</structfield> pointer is used instead.</entry> 708 </row> 709 <row> 710 <entry>__u32</entry> 711 <entry><structfield>flags</structfield></entry> 712 <entry></entry> 713 <entry>Flags set by the application or driver, see <xref 714linkend="buffer-flags" />.</entry> 715 </row> 716 <row> 717 <entry>__u32</entry> 718 <entry><structfield>field</structfield></entry> 719 <entry></entry> 720 <entry>Indicates the field order of the image in the 721buffer, see <xref linkend="v4l2-field" />. This field is not used when 722the buffer contains VBI data. Drivers must set it when 723<structfield>type</structfield> refers to an input stream, 724applications when it refers to an output stream.</entry> 725 </row> 726 <row> 727 <entry>struct timeval</entry> 728 <entry><structfield>timestamp</structfield></entry> 729 <entry></entry> 730 <entry><para>For input streams this is time when the first data 731 byte was captured, as returned by the 732 <function>clock_gettime()</function> function for the relevant 733 clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in 734 <xref linkend="buffer-flags" />. For output streams the driver 735 stores the time at which the last data byte was actually sent out 736 in the <structfield>timestamp</structfield> field. This permits 737 applications to monitor the drift between the video and system 738 clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> 739 the application has to fill in the timestamp which will be copied 740 by the driver to the capture stream.</para></entry> 741 </row> 742 <row> 743 <entry>&v4l2-timecode;</entry> 744 <entry><structfield>timecode</structfield></entry> 745 <entry></entry> 746 <entry>When <structfield>type</structfield> is 747<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the 748<constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in 749<structfield>flags</structfield>, this structure contains a frame 750timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> 751mode the top and bottom field contain the same timecode. 752Timecodes are intended to help video editing and are typically recorded on 753video tapes, but also embedded in compressed formats like MPEG. This 754field is independent of the <structfield>timestamp</structfield> and 755<structfield>sequence</structfield> fields.</entry> 756 </row> 757 <row> 758 <entry>__u32</entry> 759 <entry><structfield>sequence</structfield></entry> 760 <entry></entry> 761 <entry>Set by the driver, counting the frames (not fields!) in 762sequence. This field is set for both input and output devices.</entry> 763 </row> 764 <row> 765 <entry spanname="hspan"><para>In <link 766linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and 767bottom field have the same sequence number. The count starts at zero 768and includes dropped or repeated frames. A dropped frame was received 769by an input device but could not be stored due to lack of free buffer 770space. A repeated frame was displayed again by an output device 771because the application did not pass new data in 772time.</para><para>Note this may count the frames received 773e.g. over USB, without taking into account the frames dropped by the 774remote hardware due to limited compression throughput or bus 775bandwidth. These devices identify by not enumerating any video 776standards, see <xref linkend="standard" />.</para></entry> 777 </row> 778 <row> 779 <entry>__u32</entry> 780 <entry><structfield>memory</structfield></entry> 781 <entry></entry> 782 <entry>This field must be set by applications and/or drivers 783in accordance with the selected I/O method. See <xref linkend="v4l2-memory" 784 /></entry> 785 </row> 786 <row> 787 <entry>union</entry> 788 <entry><structfield>m</structfield></entry> 789 </row> 790 <row> 791 <entry></entry> 792 <entry>__u32</entry> 793 <entry><structfield>offset</structfield></entry> 794 <entry>For the single-planar API and when 795<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this 796is the offset of the buffer from the start of the device memory. The value is 797returned by the driver and apart of serving as parameter to the &func-mmap; 798function not useful for applications. See <xref linkend="mmap" /> for details 799 </entry> 800 </row> 801 <row> 802 <entry></entry> 803 <entry>unsigned long</entry> 804 <entry><structfield>userptr</structfield></entry> 805 <entry>For the single-planar API and when 806<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant> 807this is a pointer to the buffer (casted to unsigned long type) in virtual 808memory, set by the application. See <xref linkend="userp" /> for details. 809 </entry> 810 </row> 811 <row> 812 <entry></entry> 813 <entry>struct v4l2_plane</entry> 814 <entry><structfield>*planes</structfield></entry> 815 <entry>When using the multi-planar API, contains a userspace pointer 816 to an array of &v4l2-plane;. The size of the array should be put 817 in the <structfield>length</structfield> field of this 818 <structname>v4l2_buffer</structname> structure.</entry> 819 </row> 820 <row> 821 <entry></entry> 822 <entry>int</entry> 823 <entry><structfield>fd</structfield></entry> 824 <entry>For the single-plane API and when 825<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this 826is the file descriptor associated with a DMABUF buffer.</entry> 827 </row> 828 <row> 829 <entry>__u32</entry> 830 <entry><structfield>length</structfield></entry> 831 <entry></entry> 832 <entry>Size of the buffer (not the payload) in bytes for the 833 single-planar API. This is set by the driver based on the calls to 834 &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets 835 this to the number of elements in the <structfield>planes</structfield> 836 array. The driver will fill in the actual number of valid elements in 837 that array. 838 </entry> 839 </row> 840 <row> 841 <entry>__u32</entry> 842 <entry><structfield>reserved2</structfield></entry> 843 <entry></entry> 844 <entry>A place holder for future extensions. Drivers and applications 845must set this to 0.</entry> 846 </row> 847 <row> 848 <entry>__u32</entry> 849 <entry><structfield>reserved</structfield></entry> 850 <entry></entry> 851 <entry>A place holder for future extensions. Drivers and applications 852must set this to 0.</entry> 853 </row> 854 </tbody> 855 </tgroup> 856 </table> 857 858 <table frame="none" pgwide="1" id="v4l2-plane"> 859 <title>struct <structname>v4l2_plane</structname></title> 860 <tgroup cols="4"> 861 &cs-ustr; 862 <tbody valign="top"> 863 <row> 864 <entry>__u32</entry> 865 <entry><structfield>bytesused</structfield></entry> 866 <entry></entry> 867 <entry>The number of bytes occupied by data in the plane 868 (its payload). Drivers must set this field when <structfield>type</structfield> 869 refers to an input stream, applications when it refers to an output stream. 870 If the application sets this to 0 for an output stream, then 871 <structfield>bytesused</structfield> will be set to the size of the 872 plane (see the <structfield>length</structfield> field of this struct) 873 by the driver. Note that the actual image data starts at 874 <structfield>data_offset</structfield> which may not be 0.</entry> 875 </row> 876 <row> 877 <entry>__u32</entry> 878 <entry><structfield>length</structfield></entry> 879 <entry></entry> 880 <entry>Size in bytes of the plane (not its payload). This is set by the driver 881 based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry> 882 </row> 883 <row> 884 <entry>union</entry> 885 <entry><structfield>m</structfield></entry> 886 <entry></entry> 887 <entry></entry> 888 </row> 889 <row> 890 <entry></entry> 891 <entry>__u32</entry> 892 <entry><structfield>mem_offset</structfield></entry> 893 <entry>When the memory type in the containing &v4l2-buffer; is 894 <constant>V4L2_MEMORY_MMAP</constant>, this is the value that 895 should be passed to &func-mmap;, similar to the 896 <structfield>offset</structfield> field in &v4l2-buffer;.</entry> 897 </row> 898 <row> 899 <entry></entry> 900 <entry>unsigned long</entry> 901 <entry><structfield>userptr</structfield></entry> 902 <entry>When the memory type in the containing &v4l2-buffer; is 903 <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace 904 pointer to the memory allocated for this plane by an application. 905 </entry> 906 </row> 907 <row> 908 <entry></entry> 909 <entry>int</entry> 910 <entry><structfield>fd</structfield></entry> 911 <entry>When the memory type in the containing &v4l2-buffer; is 912 <constant>V4L2_MEMORY_DMABUF</constant>, this is a file 913 descriptor associated with a DMABUF buffer, similar to the 914 <structfield>fd</structfield> field in &v4l2-buffer;.</entry> 915 </row> 916 <row> 917 <entry>__u32</entry> 918 <entry><structfield>data_offset</structfield></entry> 919 <entry></entry> 920 <entry>Offset in bytes to video data in the plane. 921 Drivers must set this field when <structfield>type</structfield> 922 refers to an input stream, applications when it refers to an output stream. 923 Note that data_offset is included in <structfield>bytesused</structfield>. 924 So the size of the image in the plane is 925 <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at 926 offset <structfield>data_offset</structfield> from the start of the plane. 927 </entry> 928 </row> 929 <row> 930 <entry>__u32</entry> 931 <entry><structfield>reserved[11]</structfield></entry> 932 <entry></entry> 933 <entry>Reserved for future use. Should be zeroed by drivers and 934 applications.</entry> 935 </row> 936 </tbody> 937 </tgroup> 938 </table> 939 940 <table frame="none" pgwide="1" id="v4l2-buf-type"> 941 <title>enum v4l2_buf_type</title> 942 <tgroup cols="3"> 943 &cs-def; 944 <tbody valign="top"> 945 <row> 946 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> 947 <entry>1</entry> 948 <entry>Buffer of a single-planar video capture stream, see <xref 949 linkend="capture" />.</entry> 950 </row> 951 <row> 952 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> 953 </entry> 954 <entry>9</entry> 955 <entry>Buffer of a multi-planar video capture stream, see <xref 956 linkend="capture" />.</entry> 957 </row> 958 <row> 959 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> 960 <entry>2</entry> 961 <entry>Buffer of a single-planar video output stream, see <xref 962 linkend="output" />.</entry> 963 </row> 964 <row> 965 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> 966 </entry> 967 <entry>10</entry> 968 <entry>Buffer of a multi-planar video output stream, see <xref 969 linkend="output" />.</entry> 970 </row> 971 <row> 972 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> 973 <entry>3</entry> 974 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> 975 </row> 976 <row> 977 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> 978 <entry>4</entry> 979 <entry>Buffer of a raw VBI capture stream, see <xref 980 linkend="raw-vbi" />.</entry> 981 </row> 982 <row> 983 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> 984 <entry>5</entry> 985 <entry>Buffer of a raw VBI output stream, see <xref 986 linkend="raw-vbi" />.</entry> 987 </row> 988 <row> 989 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> 990 <entry>6</entry> 991 <entry>Buffer of a sliced VBI capture stream, see <xref 992 linkend="sliced" />.</entry> 993 </row> 994 <row> 995 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> 996 <entry>7</entry> 997 <entry>Buffer of a sliced VBI output stream, see <xref 998 linkend="sliced" />.</entry> 999 </row> 1000 <row> 1001 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> 1002 <entry>8</entry> 1003 <entry>Buffer for video output overlay (OSD), see <xref 1004 linkend="osd" />.</entry> 1005 </row> 1006 <row> 1007 <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry> 1008 <entry>11</entry> 1009 <entry>Buffer for Software Defined Radio (SDR) capture stream, see 1010 <xref linkend="sdr" />.</entry> 1011 </row> 1012 <row> 1013 <entry><constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant></entry> 1014 <entry>12</entry> 1015 <entry>Buffer for Software Defined Radio (SDR) output stream, see 1016 <xref linkend="sdr" />.</entry> 1017 </row> 1018 </tbody> 1019 </tgroup> 1020 </table> 1021 1022 <table frame="none" pgwide="1" id="buffer-flags"> 1023 <title>Buffer Flags</title> 1024 <tgroup cols="3"> 1025 &cs-def; 1026 <tbody valign="top"> 1027 <row> 1028 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> 1029 <entry>0x00000001</entry> 1030 <entry>The buffer resides in device memory and has been mapped 1031into the application's address space, see <xref linkend="mmap" /> for details. 1032Drivers set or clear this flag when the 1033<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link 1034 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link 1035 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> 1036 </row> 1037 <row> 1038 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> 1039 <entry>0x00000002</entry> 1040 <entry>Internally drivers maintain two buffer queues, an 1041incoming and outgoing queue. When this flag is set, the buffer is 1042currently on the incoming queue. It automatically moves to the 1043outgoing queue after the buffer has been filled (capture devices) or 1044displayed (output devices). Drivers set or clear this flag when the 1045<constant>VIDIOC_QUERYBUF</constant> ioctl is called. After 1046(successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is 1047always set and after <constant>VIDIOC_DQBUF</constant> always 1048cleared.</entry> 1049 </row> 1050 <row> 1051 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> 1052 <entry>0x00000004</entry> 1053 <entry>When this flag is set, the buffer is currently on 1054the outgoing queue, ready to be dequeued from the driver. Drivers set 1055or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl 1056is called. After calling the <constant>VIDIOC_QBUF</constant> or 1057<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a 1058buffer cannot be on both queues at the same time, the 1059<constant>V4L2_BUF_FLAG_QUEUED</constant> and 1060<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. 1061They can be both cleared however, then the buffer is in "dequeued" 1062state, in the application domain so to say.</entry> 1063 </row> 1064 <row> 1065 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry> 1066 <entry>0x00000040</entry> 1067 <entry>When this flag is set, the buffer has been dequeued 1068 successfully, although the data might have been corrupted. 1069 This is recoverable, streaming may continue as normal and 1070 the buffer may be reused normally. 1071 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant> 1072 ioctl is called.</entry> 1073 </row> 1074 <row> 1075 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> 1076 <entry>0x00000008</entry> 1077 <entry>Drivers set or clear this flag when calling the 1078<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video 1079capture devices when the buffer contains a compressed image which is a 1080key frame (or field), &ie; can be decompressed on its own. Also known as 1081an I-frame. Applications can set this bit when <structfield>type</structfield> 1082refers to an output stream.</entry> 1083 </row> 1084 <row> 1085 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> 1086 <entry>0x00000010</entry> 1087 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> 1088this flags predicted frames or fields which contain only differences to a 1089previous key frame. Applications can set this bit when <structfield>type</structfield> 1090refers to an output stream.</entry> 1091 </row> 1092 <row> 1093 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> 1094 <entry>0x00000020</entry> 1095 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> 1096this flags a bi-directional predicted frame or field which contains only 1097the differences between the current frame and both the preceding and following 1098key frames to specify its content. Applications can set this bit when 1099<structfield>type</structfield> refers to an output stream.</entry> 1100 </row> 1101 <row> 1102 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> 1103 <entry>0x00000100</entry> 1104 <entry>The <structfield>timecode</structfield> field is valid. 1105Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> 1106ioctl is called. Applications can set this bit and the corresponding 1107<structfield>timecode</structfield> structure when <structfield>type</structfield> 1108refers to an output stream.</entry> 1109 </row> 1110 <row> 1111 <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> 1112 <entry>0x00000400</entry> 1113 <entry>The buffer has been prepared for I/O and can be queued by the 1114application. Drivers set or clear this flag when the 1115<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link 1116 linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link 1117 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link 1118 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry> 1119 </row> 1120 <row> 1121 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> 1122 <entry>0x00000800</entry> 1123 <entry>Caches do not have to be invalidated for this buffer. 1124Typically applications shall use this flag if the data captured in the buffer 1125is not going to be touched by the CPU, instead the buffer will, probably, be 1126passed on to a DMA-capable hardware unit for further processing or output. 1127</entry> 1128 </row> 1129 <row> 1130 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> 1131 <entry>0x00001000</entry> 1132 <entry>Caches do not have to be cleaned for this buffer. 1133Typically applications shall use this flag for output buffers if the data 1134in this buffer has not been created by the CPU but by some DMA-capable unit, 1135in which case caches have not been used.</entry> 1136 </row> 1137 <row> 1138 <entry><constant>V4L2_BUF_FLAG_LAST</constant></entry> 1139 <entry>0x00100000</entry> 1140 <entry>Last buffer produced by the hardware. mem2mem codec drivers 1141set this flag on the capture queue for the last buffer when the 1142<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link> or 1143<link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Due to hardware 1144limitations, the last buffer may be empty. In this case the driver will set the 1145<structfield>bytesused</structfield> field to 0, regardless of the format. Any 1146Any subsequent call to the <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl 1147will not block anymore, but return an &EPIPE;.</entry> 1148 </row> 1149 <row> 1150 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry> 1151 <entry>0x0000e000</entry> 1152 <entry>Mask for timestamp types below. To test the 1153 timestamp type, mask out bits not belonging to timestamp 1154 type by performing a logical and operation with buffer 1155 flags and timestamp mask.</entry> 1156 </row> 1157 <row> 1158 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry> 1159 <entry>0x00000000</entry> 1160 <entry>Unknown timestamp type. This type is used by 1161 drivers before Linux 3.9 and may be either monotonic (see 1162 below) or realtime (wall clock). Monotonic clock has been 1163 favoured in embedded systems whereas most of the drivers 1164 use the realtime clock. Either kinds of timestamps are 1165 available in user space via 1166 <function>clock_gettime(2)</function> using clock IDs 1167 <constant>CLOCK_MONOTONIC</constant> and 1168 <constant>CLOCK_REALTIME</constant>, respectively.</entry> 1169 </row> 1170 <row> 1171 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry> 1172 <entry>0x00002000</entry> 1173 <entry>The buffer timestamp has been taken from the 1174 <constant>CLOCK_MONOTONIC</constant> clock. To access the 1175 same clock outside V4L2, use 1176 <function>clock_gettime(2)</function>.</entry> 1177 </row> 1178 <row> 1179 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry> 1180 <entry>0x00004000</entry> 1181 <entry>The CAPTURE buffer timestamp has been taken from the 1182 corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry> 1183 </row> 1184 <row> 1185 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry> 1186 <entry>0x00070000</entry> 1187 <entry>Mask for timestamp sources below. The timestamp source 1188 defines the point of time the timestamp is taken in relation to 1189 the frame. Logical 'and' operation between the 1190 <structfield>flags</structfield> field and 1191 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the 1192 value of the timestamp source. Applications must set the timestamp 1193 source when <structfield>type</structfield> refers to an output stream 1194 and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry> 1195 </row> 1196 <row> 1197 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry> 1198 <entry>0x00000000</entry> 1199 <entry>End Of Frame. The buffer timestamp has been taken 1200 when the last pixel of the frame has been received or the 1201 last pixel of the frame has been transmitted. In practice, 1202 software generated timestamps will typically be read from 1203 the clock a small amount of time after the last pixel has 1204 been received or transmitten, depending on the system and 1205 other activity in it.</entry> 1206 </row> 1207 <row> 1208 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry> 1209 <entry>0x00010000</entry> 1210 <entry>Start Of Exposure. The buffer timestamp has been 1211 taken when the exposure of the frame has begun. This is 1212 only valid for the 1213 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer 1214 type.</entry> 1215 </row> 1216 </tbody> 1217 </tgroup> 1218 </table> 1219 1220 <table pgwide="1" frame="none" id="v4l2-memory"> 1221 <title>enum v4l2_memory</title> 1222 <tgroup cols="3"> 1223 &cs-def; 1224 <tbody valign="top"> 1225 <row> 1226 <entry><constant>V4L2_MEMORY_MMAP</constant></entry> 1227 <entry>1</entry> 1228 <entry>The buffer is used for <link linkend="mmap">memory 1229mapping</link> I/O.</entry> 1230 </row> 1231 <row> 1232 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> 1233 <entry>2</entry> 1234 <entry>The buffer is used for <link linkend="userp">user 1235pointer</link> I/O.</entry> 1236 </row> 1237 <row> 1238 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> 1239 <entry>3</entry> 1240 <entry>[to do]</entry> 1241 </row> 1242 <row> 1243 <entry><constant>V4L2_MEMORY_DMABUF</constant></entry> 1244 <entry>4</entry> 1245 <entry>The buffer is used for <link linkend="dmabuf">DMA shared 1246buffer</link> I/O.</entry> 1247 </row> 1248 </tbody> 1249 </tgroup> 1250 </table> 1251 1252 <section> 1253 <title>Timecodes</title> 1254 1255 <para>The <structname>v4l2_timecode</structname> structure is 1256designed to hold a <xref linkend="smpte12m" /> or similar timecode. 1257(struct <structname>timeval</structname> timestamps are stored in 1258&v4l2-buffer; field <structfield>timestamp</structfield>.)</para> 1259 1260 <table frame="none" pgwide="1" id="v4l2-timecode"> 1261 <title>struct <structname>v4l2_timecode</structname></title> 1262 <tgroup cols="3"> 1263 &cs-str; 1264 <tbody valign="top"> 1265 <row> 1266 <entry>__u32</entry> 1267 <entry><structfield>type</structfield></entry> 1268 <entry>Frame rate the timecodes are based on, see <xref 1269 linkend="timecode-type" />.</entry> 1270 </row> 1271 <row> 1272 <entry>__u32</entry> 1273 <entry><structfield>flags</structfield></entry> 1274 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> 1275 </row> 1276 <row> 1277 <entry>__u8</entry> 1278 <entry><structfield>frames</structfield></entry> 1279 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the 1280 type of timecode.</entry> 1281 </row> 1282 <row> 1283 <entry>__u8</entry> 1284 <entry><structfield>seconds</structfield></entry> 1285 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> 1286 </row> 1287 <row> 1288 <entry>__u8</entry> 1289 <entry><structfield>minutes</structfield></entry> 1290 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> 1291 </row> 1292 <row> 1293 <entry>__u8</entry> 1294 <entry><structfield>hours</structfield></entry> 1295 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> 1296 </row> 1297 <row> 1298 <entry>__u8</entry> 1299 <entry><structfield>userbits</structfield>[4]</entry> 1300 <entry>The "user group" bits from the timecode.</entry> 1301 </row> 1302 </tbody> 1303 </tgroup> 1304 </table> 1305 1306 <table frame="none" pgwide="1" id="timecode-type"> 1307 <title>Timecode Types</title> 1308 <tgroup cols="3"> 1309 &cs-def; 1310 <tbody valign="top"> 1311 <row> 1312 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> 1313 <entry>1</entry> 1314 <entry>24 frames per second, i. e. film.</entry> 1315 </row> 1316 <row> 1317 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> 1318 <entry>2</entry> 1319 <entry>25 frames per second, &ie; PAL or SECAM video.</entry> 1320 </row> 1321 <row> 1322 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> 1323 <entry>3</entry> 1324 <entry>30 frames per second, &ie; NTSC video.</entry> 1325 </row> 1326 <row> 1327 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> 1328 <entry>4</entry> 1329 <entry></entry> 1330 </row> 1331 <row> 1332 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> 1333 <entry>5</entry> 1334 <entry></entry> 1335 </row> 1336 </tbody> 1337 </tgroup> 1338 </table> 1339 1340 <table frame="none" pgwide="1" id="timecode-flags"> 1341 <title>Timecode Flags</title> 1342 <tgroup cols="3"> 1343 &cs-def; 1344 <tbody valign="top"> 1345 <row> 1346 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> 1347 <entry>0x0001</entry> 1348 <entry>Indicates "drop frame" semantics for counting frames 1349in 29.97 fps material. When set, frame numbers 0 and 1 at the start of 1350each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the 1351count.</entry> 1352 </row> 1353 <row> 1354 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> 1355 <entry>0x0002</entry> 1356 <entry>The "color frame" flag.</entry> 1357 </row> 1358 <row> 1359 <entry><constant>V4L2_TC_USERBITS_field</constant></entry> 1360 <entry>0x000C</entry> 1361 <entry>Field mask for the "binary group flags".</entry> 1362 </row> 1363 <row> 1364 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> 1365 <entry>0x0000</entry> 1366 <entry>Unspecified format.</entry> 1367 </row> 1368 <row> 1369 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> 1370 <entry>0x0008</entry> 1371 <entry>8-bit ISO characters.</entry> 1372 </row> 1373 </tbody> 1374 </tgroup> 1375 </table> 1376 </section> 1377 </section> 1378 1379 <section id="field-order"> 1380 <title>Field Order</title> 1381 1382 <para>We have to distinguish between progressive and interlaced 1383video. Progressive video transmits all lines of a video image 1384sequentially. Interlaced video divides an image into two fields, 1385containing only the odd and even lines of the image, respectively. 1386Alternating the so called odd and even field are transmitted, and due 1387to a small delay between fields a cathode ray TV displays the lines 1388interleaved, yielding the original frame. This curious technique was 1389invented because at refresh rates similar to film the image would 1390fade out too quickly. Transmitting fields reduces the flicker without 1391the necessity of doubling the frame rate and with it the bandwidth 1392required for each channel.</para> 1393 1394 <para>It is important to understand a video camera does not expose 1395one frame at a time, merely transmitting the frames separated into 1396fields. The fields are in fact captured at two different instances in 1397time. An object on screen may well move between one field and the 1398next. For applications analysing motion it is of paramount importance 1399to recognize which field of a frame is older, the <emphasis>temporal 1400order</emphasis>.</para> 1401 1402 <para>When the driver provides or accepts images field by field 1403rather than interleaved, it is also important applications understand 1404how the fields combine to frames. We distinguish between top (aka odd) and 1405bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line 1406of the top field is the first line of an interlaced frame, the first 1407line of the bottom field is the second line of that frame.</para> 1408 1409 <para>However because fields were captured one after the other, 1410arguing whether a frame commences with the top or bottom field is 1411pointless. Any two successive top and bottom, or bottom and top fields 1412yield a valid frame. Only when the source was progressive to begin 1413with, ⪚ when transferring film to video, two fields may come from 1414the same frame, creating a natural order.</para> 1415 1416 <para>Counter to intuition the top field is not necessarily the 1417older field. Whether the older field contains the top or bottom lines 1418is a convention determined by the video standard. Hence the 1419distinction between temporal and spatial order of fields. The diagrams 1420below should make this clearer.</para> 1421 1422 <para>All video capture and output devices must report the current 1423field order. Some drivers may permit the selection of a different 1424order, to this end applications initialize the 1425<structfield>field</structfield> field of &v4l2-pix-format; before 1426calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should 1427have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> 1428 1429 <table frame="none" pgwide="1" id="v4l2-field"> 1430 <title>enum v4l2_field</title> 1431 <tgroup cols="3"> 1432 &cs-def; 1433 <tbody valign="top"> 1434 <row> 1435 <entry><constant>V4L2_FIELD_ANY</constant></entry> 1436 <entry>0</entry> 1437 <entry>Applications request this field order when any 1438one of the <constant>V4L2_FIELD_NONE</constant>, 1439<constant>V4L2_FIELD_TOP</constant>, 1440<constant>V4L2_FIELD_BOTTOM</constant>, or 1441<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. 1442Drivers choose depending on hardware capabilities or e. g. the 1443requested image size, and return the actual field order. Drivers must 1444never return <constant>V4L2_FIELD_ANY</constant>. If multiple 1445field orders are possible the driver must choose one of the possible 1446field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; 1447<structfield>field</structfield> can never be 1448<constant>V4L2_FIELD_ANY</constant>.</entry> 1449 </row> 1450 <row> 1451 <entry><constant>V4L2_FIELD_NONE</constant></entry> 1452 <entry>1</entry> 1453 <entry>Images are in progressive format, not interlaced. 1454The driver may also indicate this order when it cannot distinguish 1455between <constant>V4L2_FIELD_TOP</constant> and 1456<constant>V4L2_FIELD_BOTTOM</constant>.</entry> 1457 </row> 1458 <row> 1459 <entry><constant>V4L2_FIELD_TOP</constant></entry> 1460 <entry>2</entry> 1461 <entry>Images consist of the top (aka odd) field only.</entry> 1462 </row> 1463 <row> 1464 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> 1465 <entry>3</entry> 1466 <entry>Images consist of the bottom (aka even) field only. 1467Applications may wish to prevent a device from capturing interlaced 1468images because they will have "comb" or "feathering" artefacts around 1469moving objects.</entry> 1470 </row> 1471 <row> 1472 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> 1473 <entry>4</entry> 1474 <entry>Images contain both fields, interleaved line by 1475line. The temporal order of the fields (whether the top or bottom 1476field is first transmitted) depends on the current video standard. 1477M/NTSC transmits the bottom field first, all other standards the top 1478field first.</entry> 1479 </row> 1480 <row> 1481 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> 1482 <entry>5</entry> 1483 <entry>Images contain both fields, the top field lines 1484are stored first in memory, immediately followed by the bottom field 1485lines. Fields are always stored in temporal order, the older one first 1486in memory. Image sizes refer to the frame, not fields.</entry> 1487 </row> 1488 <row> 1489 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> 1490 <entry>6</entry> 1491 <entry>Images contain both fields, the bottom field 1492lines are stored first in memory, immediately followed by the top 1493field lines. Fields are always stored in temporal order, the older one 1494first in memory. Image sizes refer to the frame, not fields.</entry> 1495 </row> 1496 <row> 1497 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> 1498 <entry>7</entry> 1499 <entry>The two fields of a frame are passed in separate 1500buffers, in temporal order, &ie; the older one first. To indicate the field 1501parity (whether the current field is a top or bottom field) the driver 1502or application, depending on data direction, must set &v4l2-buffer; 1503<structfield>field</structfield> to 1504<constant>V4L2_FIELD_TOP</constant> or 1505<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair 1506to build a frame. If fields are successive, without any dropped fields 1507between them (fields can drop individually), can be determined from 1508the &v4l2-buffer; <structfield>sequence</structfield> field. This format 1509cannot be selected when using the read/write I/O method since there 1510is no way to communicate if a field was a top or bottom field.</entry> 1511 </row> 1512 <row> 1513 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> 1514 <entry>8</entry> 1515 <entry>Images contain both fields, interleaved line by 1516line, top field first. The top field is transmitted first.</entry> 1517 </row> 1518 <row> 1519 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> 1520 <entry>9</entry> 1521 <entry>Images contain both fields, interleaved line by 1522line, top field first. The bottom field is transmitted first.</entry> 1523 </row> 1524 </tbody> 1525 </tgroup> 1526 </table> 1527 1528 <figure id="fieldseq-tb"> 1529 <title>Field Order, Top Field First Transmitted</title> 1530 <mediaobject> 1531 <imageobject> 1532 <imagedata fileref="fieldseq_tb.pdf" format="PS" /> 1533 </imageobject> 1534 <imageobject> 1535 <imagedata fileref="fieldseq_tb.gif" format="GIF" /> 1536 </imageobject> 1537 </mediaobject> 1538 </figure> 1539 1540 <figure id="fieldseq-bt"> 1541 <title>Field Order, Bottom Field First Transmitted</title> 1542 <mediaobject> 1543 <imageobject> 1544 <imagedata fileref="fieldseq_bt.pdf" format="PS" /> 1545 </imageobject> 1546 <imageobject> 1547 <imagedata fileref="fieldseq_bt.gif" format="GIF" /> 1548 </imageobject> 1549 </mediaobject> 1550 </figure> 1551 </section> 1552
