Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.
1 <title>Input/Output</title> 2 3 <para>The V4L2 API defines several different methods to read from or 4 write to a device. All drivers exchanging data with applications must 5 support at least one of them.</para> 6 7 <para>The classic I/O method using the <function>read()</function> 8 and <function>write()</function> function is automatically selected 9 after opening a V4L2 device. When the driver does not support this 10 method attempts to read or write will fail at any time.</para> 11 12 <para>Other methods must be negotiated. To select the streaming I/O 13 method with memory mapped or user buffers applications call the 14 &VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined 15 yet.</para> 16 17 <para>Video overlay can be considered another I/O method, although 18 the application does not directly receive the image data. It is 19 selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl. 20 For more information see <xref linkend="overlay" />.</para> 21 22 <para>Generally exactly one I/O method, including overlay, is 23 associated with each file descriptor. The only exceptions are 24 applications not exchanging data with a driver ("panel applications", 25 see <xref linkend="open" />) and drivers permitting simultaneous video capturing 26 and overlay using the same file descriptor, for compatibility with V4L 27 and earlier versions of V4L2.</para> 28 29 <para><constant>VIDIOC_S_FMT</constant> and 30 <constant>VIDIOC_REQBUFS</constant> would permit this to some degree, 31 but for simplicity drivers need not support switching the I/O method 32 (after first switching away from read/write) other than by closing 33 and reopening the device.</para> 34 35 <para>The following sections describe the various I/O methods in 36 more detail.</para> 37 38 <section id="rw"> 39 <title>Read/Write</title> 40 41 <para>Input and output devices support the 42 <function>read()</function> and <function>write()</function> function, 43 respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in 44 the <structfield>capabilities</structfield> field of &v4l2-capability; 45 returned by the &VIDIOC-QUERYCAP; ioctl is set.</para> 46 47 <para>Drivers may need the CPU to copy the data, but they may also 48 support DMA to or from user memory, so this I/O method is not 49 necessarily less efficient than other methods merely exchanging buffer 50 pointers. It is considered inferior though because no meta-information 51 like frame counters or timestamps are passed. This information is 52 necessary to recognize frame dropping and to synchronize with other 53 data streams. However this is also the simplest I/O method, requiring 54 little or no setup to exchange data. It permits command line stunts 55 like this (the <application>vidctrl</application> tool is 56 fictitious):</para> 57 58 <informalexample> 59 <screen> 60 > 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. 67 Drivers must implement one I/O method if they 68 exchange data with applications, but it need not be this.<footnote> 69 <para>It would be desirable if applications could depend on 70 drivers supporting all I/O interfaces, but as much as the complex 71 memory mapping I/O can be inadequate for some devices we have no 72 reason to require this interface, which is most useful for simple 73 applications capturing still images.</para> 74 </footnote> When reading or writing is supported, the driver 75 must also support the &func-select; and &func-poll; 76 function.<footnote> 77 <para>At the driver level <function>select()</function> and 78 <function>poll()</function> are the same, and 79 <function>select()</function> is too important to be optional.</para> 80 </footnote></para> 81 </section> 82 83 <section id="mmap"> 84 <title>Streaming I/O (Memory Mapping)</title> 85 86 <para>Input and output devices support this I/O method when the 87 <constant>V4L2_CAP_STREAMING</constant> flag in the 88 <structfield>capabilities</structfield> field of &v4l2-capability; 89 returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two 90 streaming methods, to determine if the memory mapping flavor is 91 supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> 92 93 <para>Streaming is an I/O method where only pointers to buffers 94 are exchanged between application and driver, the data itself is not 95 copied. Memory mapping is primarily intended to map buffers in device 96 memory into the application's address space. Device memory can be for 97 example the video memory on a graphics card with a video capture 98 add-on. However, being the most efficient I/O method available for a 99 long time, many other drivers support streaming as well, allocating 100 buffers in DMA-able main memory.</para> 101 102 <para>A driver can support many sets of buffers. Each set is 103 identified by a unique buffer type value. The sets are independent and 104 each set can hold a different type of data. To access different sets 105 at the same time different file descriptors must be used.<footnote> 106 <para>One could use one file descriptor and set the buffer 107 type field accordingly when calling &VIDIOC-QBUF; etc., but it makes 108 the <function>select()</function> function ambiguous. We also like the 109 clean approach of one file descriptor per logical stream. Video 110 overlay for example is also a logical stream, although the CPU is not 111 needed for continuous operation.</para> 112 </footnote></para> 113 114 <para>To allocate device buffers applications call the 115 &VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer 116 type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. 117 This ioctl can also be used to change the number of buffers or to free 118 the allocated memory, provided none of the buffers are still 119 mapped.</para> 120 121 <para>Before applications can access the buffers they must map 122 them into their address space with the &func-mmap; function. The 123 location of the buffers in device memory can be determined with the 124 &VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the 125 <structfield>m.offset</structfield> and <structfield>length</structfield> 126 returned in a &v4l2-buffer; are passed as sixth and second parameter to the 127 <function>mmap()</function> function. When using the multi-planar API, 128 &v4l2-buffer; contains an array of &v4l2-plane; structures, each 129 containing its own <structfield>m.offset</structfield> and 130 <structfield>length</structfield>. When using the multi-planar API, every 131 plane of every buffer has to be mapped separately, so the number of 132 calls to &func-mmap; should be equal to number of buffers times number of 133 planes in each buffer. The offset and length values must not be modified. 134 Remember, the buffers are allocated in physical memory, as opposed to virtual 135 memory, which can be swapped out to disk. Applications should free the buffers 136 as soon as possible with the &func-munmap; function.</para> 137 138 <example> 139 <title>Mapping buffers in the single-planar API</title> 140 <programlisting> 141 &v4l2-requestbuffers; reqbuf; 142 struct { 143 void *start; 144 size_t length; 145 } *buffers; 146 unsigned int i; 147 148 memset(&reqbuf, 0, sizeof(reqbuf)); 149 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 150 reqbuf.memory = V4L2_MEMORY_MMAP; 151 reqbuf.count = 20; 152 153 if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf)) { 154 if (errno == EINVAL) 155 printf("Video capturing or mmap-streaming is not supported\n"); 156 else 157 perror("VIDIOC_REQBUFS"); 158 159 exit(EXIT_FAILURE); 160 } 161 162 /* We want at least five buffers. */ 163 164 if (reqbuf.count < 5) { 165 /* You may need to free the buffers here. */ 166 printf("Not enough buffer memory\n"); 167 exit(EXIT_FAILURE); 168 } 169 170 buffers = calloc(reqbuf.count, sizeof(*buffers)); 171 assert(buffers != NULL); 172 173 for (i = 0; i < 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 203 for (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 215 struct { 216 void *start[FMT_NUM_PLANES]; 217 size_t length[FMT_NUM_PLANES]; 218 } *buffers; 219 unsigned int i, j; 220 221 memset(&reqbuf, 0, sizeof(reqbuf)); 222 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; 223 reqbuf.memory = V4L2_MEMORY_MMAP; 224 reqbuf.count = 20; 225 226 if (ioctl(fd, &VIDIOC-REQBUFS;, &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 237 if (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 243 buffers = calloc(reqbuf.count, sizeof(*buffers)); 244 assert(buffers != NULL); 245 246 for (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 284 for (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 291 and an outgoing queue. They separate the synchronous capture or output 292 operation locked to a video clock from the application which is 293 subject to random disk or network delays and preemption by 294 other processes, thereby reducing the probability of data loss. 295 The queues are organized as FIFOs, buffers will be 296 output in the order enqueued in the incoming FIFO, and were 297 captured in the order dequeued from the outgoing FIFO.</para> 298 299 <para>The driver may require a minimum number of buffers enqueued 300 at all times to function, apart of this no limit exists on the number 301 of buffers applications can enqueue in advance, or dequeue and 302 process. They can also enqueue in a different order than buffers have 303 been dequeued, and the driver can <emphasis>fill</emphasis> enqueued 304 <emphasis>empty</emphasis> buffers in any order. <footnote> 305 <para>Random enqueue order permits applications processing 306 images out of order (such as video codecs) to return buffers earlier, 307 reducing the probability of data loss. Random fill order allows 308 drivers to reuse buffers on a LIFO-basis, taking advantage of caches 309 holding scatter-gather lists and the like.</para> 310 </footnote> The index number of a buffer (&v4l2-buffer; 311 <structfield>index</structfield>) plays no role here, it only 312 identifies the buffer.</para> 313 314 <para>Initially all mapped buffers are in dequeued state, 315 inaccessible by the driver. For capturing applications it is customary 316 to first enqueue all mapped buffers, then to start capturing and enter 317 the read loop. Here the application waits until a filled buffer can be 318 dequeued, and re-enqueues the buffer when the data is no longer 319 needed. Output applications fill and enqueue buffers, when enough 320 buffers are stacked up the output is started with 321 <constant>VIDIOC_STREAMON</constant>. In the write loop, when 322 the application runs out of free buffers, it must wait until an empty 323 buffer can be dequeued and reused.</para> 324 325 <para>To enqueue and dequeue a buffer applications use the 326 &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being 327 mapped, enqueued, full or empty can be determined at any time using the 328 &VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the 329 application until one or more buffers can be dequeued. By default 330 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 331 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 332 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 333 returns immediately with an &EAGAIN; when no buffer is available. The 334 &func-select; or &func-poll; functions are always available.</para> 335 336 <para>To start and stop capturing or output applications call the 337 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note 338 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both 339 queues as a side effect. Since there is no notion of doing anything 340 "now" on a multitasking system, if an application needs to synchronize 341 with another event it should examine the &v4l2-buffer; 342 <structfield>timestamp</structfield> of captured or outputted buffers. 343 </para> 344 345 <para>Drivers implementing memory mapping I/O must 346 support the <constant>VIDIOC_REQBUFS</constant>, 347 <constant>VIDIOC_QUERYBUF</constant>, 348 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, 349 <constant>VIDIOC_STREAMON</constant> and 350 <constant>VIDIOC_STREAMOFF</constant> ioctl, the 351 <function>mmap()</function>, <function>munmap()</function>, 352 <function>select()</function> and <function>poll()</function> 353 function.<footnote> 354 <para>At the driver level <function>select()</function> and 355 <function>poll()</function> are the same, and 356 <function>select()</function> is too important to be optional. The 357 rest should be evident.</para> 358 </footnote></para> 359 360 <para>[capture example]</para> 361 362 </section> 363 364 <section id="userp"> 365 <title>Streaming I/O (User Pointers)</title> 366 367 <para>Input and output devices support this I/O method when the 368 <constant>V4L2_CAP_STREAMING</constant> flag in the 369 <structfield>capabilities</structfield> field of &v4l2-capability; 370 returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user 371 pointer method (not only memory mapping) is supported must be 372 determined by calling the &VIDIOC-REQBUFS; ioctl.</para> 373 374 <para>This I/O method combines advantages of the read/write and 375 memory mapping methods. Buffers (planes) are allocated by the application 376 itself, and can reside for example in virtual or shared memory. Only 377 pointers to data are exchanged, these pointers and meta-information 378 are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case). 379 The driver must be switched into user pointer I/O mode by calling the 380 &VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated 381 beforehand, consequently they are not indexed and cannot be queried like mapped 382 buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> 383 384 <example> 385 <title>Initiating streaming I/O with user pointers</title> 386 387 <programlisting> 388 &v4l2-requestbuffers; reqbuf; 389 390 memset (&reqbuf, 0, sizeof (reqbuf)); 391 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 392 reqbuf.memory = V4L2_MEMORY_USERPTR; 393 394 if (ioctl (fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { 395 if (errno == EINVAL) 396 printf ("Video capturing or user pointer streaming is not supported\n"); 397 else 398 perror ("VIDIOC_REQBUFS"); 399 400 exit (EXIT_FAILURE); 401 } 402 </programlisting> 403 </example> 404 405 <para>Buffer (plane) addresses and sizes are passed on the fly with the 406 &VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, 407 applications can pass different addresses and sizes at each 408 <constant>VIDIOC_QBUF</constant> call. If required by the hardware the 409 driver swaps memory pages within physical memory to create a 410 continuous area of memory. This happens transparently to the 411 application in the virtual memory subsystem of the kernel. When buffer 412 pages have been swapped out to disk they are brought back and finally 413 locked in physical memory for DMA.<footnote> 414 <para>We expect that frequently used buffers are typically not 415 swapped out. Anyway, the process of swapping, locking or generating 416 scatter-gather lists may be time consuming. The delay can be masked by 417 the depth of the incoming buffer queue, and perhaps by maintaining 418 caches assuming a buffer will be soon enqueued again. On the other 419 hand, to optimize memory usage drivers can limit the number of buffers 420 locked in advance and recycle the most recently used buffers first. Of 421 course, the pages of empty buffers in the incoming queue need not be 422 saved to disk. Output buffers must be saved on the incoming and 423 outgoing queue because an application may share them with other 424 processes.</para> 425 </footnote></para> 426 427 <para>Filled or displayed buffers are dequeued with the 428 &VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any 429 time between the completion of the DMA and this ioctl. The memory is 430 also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or 431 when the device is closed. Applications must take care not to free 432 buffers without dequeuing. For once, the buffers remain locked until 433 further, wasting physical memory. Second the driver will not be 434 notified when the memory is returned to the application's free list 435 and subsequently reused for other purposes, possibly completing the 436 requested DMA and overwriting valuable data.</para> 437 438 <para>For capturing applications it is customary to enqueue a 439 number of empty buffers, to start capturing and enter the read loop. 440 Here the application waits until a filled buffer can be dequeued, and 441 re-enqueues the buffer when the data is no longer needed. Output 442 applications fill and enqueue buffers, when enough buffers are stacked 443 up output is started. In the write loop, when the application 444 runs out of free buffers it must wait until an empty buffer can be 445 dequeued and reused. Two methods exist to suspend execution of the 446 application until one or more buffers can be dequeued. By default 447 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 448 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 449 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 450 returns immediately with an &EAGAIN; when no buffer is available. The 451 &func-select; or &func-poll; function are always available.</para> 452 453 <para>To start and stop capturing or output applications call the 454 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note 455 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both 456 queues and unlocks all buffers as a side effect. Since there is no 457 notion of doing anything "now" on a multitasking system, if an 458 application needs to synchronize with another event it should examine 459 the &v4l2-buffer; <structfield>timestamp</structfield> of captured 460 or outputted buffers.</para> 461 462 <para>Drivers implementing user pointer I/O must 463 support the <constant>VIDIOC_REQBUFS</constant>, 464 <constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>, 465 <constant>VIDIOC_STREAMON</constant> and 466 <constant>VIDIOC_STREAMOFF</constant> ioctl, the 467 <function>select()</function> and <function>poll()</function> function.<footnote> 468 <para>At the driver level <function>select()</function> and 469 <function>poll()</function> are the same, and 470 <function>select()</function> is too important to be optional. The 471 rest should be evident.</para> 472 </footnote></para> 473 </section> 474 475 <section id="dmabuf"> 476 <title>Streaming I/O (DMA buffer importing)</title> 477 478 <para>The DMABUF framework provides a generic method for sharing buffers 479 between multiple devices. Device drivers that support DMABUF can export a DMA 480 buffer to userspace as a file descriptor (known as the exporter role), import a 481 DMA buffer from userspace using a file descriptor previously exported for a 482 different or the same device (known as the importer role), or both. This 483 section describes the DMABUF importer role API in V4L2.</para> 484 485 <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for 486 details about exporting V4L2 buffers as DMABUF file descriptors.</para> 487 488 <para>Input and output devices support the streaming I/O method when the 489 <constant>V4L2_CAP_STREAMING</constant> flag in the 490 <structfield>capabilities</structfield> field of &v4l2-capability; returned by 491 the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through 492 DMABUF file descriptors is supported is determined by calling the 493 &VIDIOC-REQBUFS; ioctl with the memory type set to 494 <constant>V4L2_MEMORY_DMABUF</constant>.</para> 495 496 <para>This I/O method is dedicated to sharing DMA buffers between different 497 devices, which may be V4L devices or other video-related devices (e.g. DRM). 498 Buffers (planes) are allocated by a driver on behalf of an application. Next, 499 these buffers are exported to the application as file descriptors using an API 500 which is specific for an allocator driver. Only such file descriptor are 501 exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or 502 in &v4l2-plane; in the multi-planar API case). The driver must be switched 503 into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer 504 type.</para> 505 506 <example> 507 <title>Initiating streaming I/O with DMABUF file descriptors</title> 508 509 <programlisting> 510 &v4l2-requestbuffers; reqbuf; 511 512 memset(&reqbuf, 0, sizeof (reqbuf)); 513 reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 514 reqbuf.memory = V4L2_MEMORY_DMABUF; 515 reqbuf.count = 1; 516 517 if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { 518 if (errno == EINVAL) 519 printf("Video capturing or DMABUF streaming is not supported\n"); 520 else 521 perror("VIDIOC_REQBUFS"); 522 523 exit(EXIT_FAILURE); 524 } 525 </programlisting> 526 </example> 527 528 <para>The buffer (plane) file descriptor is passed on the fly with the 529 &VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be 530 associated with a different DMABUF descriptor. Although buffers are commonly 531 cycled, applications can pass a different DMABUF descriptor at each 532 <constant>VIDIOC_QBUF</constant> call.</para> 533 534 <example> 535 <title>Queueing DMABUF using single plane API</title> 536 537 <programlisting> 538 int buffer_queue(int v4lfd, int index, int dmafd) 539 { 540 &v4l2-buffer; buf; 541 542 memset(&buf, 0, sizeof buf); 543 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 544 buf.memory = V4L2_MEMORY_DMABUF; 545 buf.index = index; 546 buf.m.fd = dmafd; 547 548 if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { 549 perror("VIDIOC_QBUF"); 550 return -1; 551 } 552 553 return 0; 554 } 555 </programlisting> 556 </example> 557 558 <example> 559 <title>Queueing DMABUF using multi plane API</title> 560 561 <programlisting> 562 int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) 563 { 564 &v4l2-buffer; buf; 565 &v4l2-plane; planes[VIDEO_MAX_PLANES]; 566 int i; 567 568 memset(&buf, 0, sizeof buf); 569 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; 570 buf.memory = V4L2_MEMORY_DMABUF; 571 buf.index = index; 572 buf.m.planes = planes; 573 buf.length = n_planes; 574 575 memset(&planes, 0, sizeof planes); 576 577 for (i = 0; i < n_planes; ++i) 578 buf.m.planes[i].m.fd = dmafd[i]; 579 580 if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { 581 perror("VIDIOC_QBUF"); 582 return -1; 583 } 584 585 return 0; 586 } 587 </programlisting> 588 </example> 589 590 <para>Captured or displayed buffers are dequeued with the 591 &VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any 592 time between the completion of the DMA and this ioctl. The memory is 593 also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or 594 when the device is closed.</para> 595 596 <para>For capturing applications it is customary to enqueue a 597 number of empty buffers, to start capturing and enter the read loop. 598 Here the application waits until a filled buffer can be dequeued, and 599 re-enqueues the buffer when the data is no longer needed. Output 600 applications fill and enqueue buffers, when enough buffers are stacked 601 up output is started. In the write loop, when the application 602 runs out of free buffers it must wait until an empty buffer can be 603 dequeued and reused. Two methods exist to suspend execution of the 604 application until one or more buffers can be dequeued. By default 605 <constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the 606 outgoing queue. When the <constant>O_NONBLOCK</constant> flag was 607 given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> 608 returns immediately with an &EAGAIN; when no buffer is available. The 609 &func-select; and &func-poll; functions are always available.</para> 610 611 <para>To start and stop capturing or displaying applications call the 612 &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that 613 <constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and 614 unlocks all buffers as a side effect. Since there is no notion of doing 615 anything "now" on a multitasking system, if an application needs to synchronize 616 with another event it should examine the &v4l2-buffer; 617 <structfield>timestamp</structfield> of captured or outputted buffers.</para> 618 619 <para>Drivers implementing DMABUF importing I/O must support the 620 <constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>, 621 <constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and 622 <constant>VIDIOC_STREAMOFF</constant> ioctls, and the 623 <function>select()</function> and <function>poll()</function> functions.</para> 624 625 </section> 626 627 <section id="async"> 628 <title>Asynchronous I/O</title> 629 630 <para>This method is not defined yet.</para> 631 </section> 632 633 <section id="buffer"> 634 <title>Buffers</title> 635 636 <para>A buffer contains data exchanged by application and 637 driver using one of the Streaming I/O methods. In the multi-planar API, the 638 data is held in planes, while the buffer structure acts as a container 639 for the planes. Only pointers to buffers (planes) are exchanged, the data 640 itself is not copied. These pointers, together with meta-information like 641 timestamps or field parity, are stored in a struct 642 <structname>v4l2_buffer</structname>, argument to 643 the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. 644 In the multi-planar API, some plane-specific members of struct 645 <structname>v4l2_buffer</structname>, such as pointers and sizes for each 646 plane, are stored in struct <structname>v4l2_plane</structname> instead. 647 In that case, struct <structname>v4l2_buffer</structname> contains an array of 648 plane structures.</para> 649 650 <para>Dequeued video buffers come with timestamps. The driver 651 decides at which part of the frame and with which clock the 652 timestamp is taken. Please see flags in the masks 653 <constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant> and 654 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> in <xref 655 linkend="buffer-flags" />. These flags are always valid and constant 656 across all buffers during the whole video stream. Changes in these 657 flags may take place as a side effect of &VIDIOC-S-INPUT; or 658 &VIDIOC-S-OUTPUT; however. The 659 <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> timestamp type 660 which is used by e.g. on mem-to-mem devices is an exception to the 661 rule: the timestamp source flags are copied from the OUTPUT video 662 buffer to the CAPTURE video buffer.</para> 663 664 <table frame="none" pgwide="1" id="v4l2-buffer"> 665 <title>struct <structname>v4l2_buffer</structname></title> 666 <tgroup cols="4"> 667 &cs-ustr; 668 <tbody valign="top"> 669 <row> 670 <entry>__u32</entry> 671 <entry><structfield>index</structfield></entry> 672 <entry></entry> 673 <entry>Number of the buffer, set by the application except 674 when calling &VIDIOC-DQBUF;, then it is set by the driver. 675 This field can range from zero to the number of buffers allocated 676 with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>), 677 plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one.</entry> 678 </row> 679 <row> 680 <entry>__u32</entry> 681 <entry><structfield>type</structfield></entry> 682 <entry></entry> 683 <entry>Type of the buffer, same as &v4l2-format; 684 <structfield>type</structfield> or &v4l2-requestbuffers; 685 <structfield>type</structfield>, set by the application. See <xref 686 linkend="v4l2-buf-type" /></entry> 687 </row> 688 <row> 689 <entry>__u32</entry> 690 <entry><structfield>bytesused</structfield></entry> 691 <entry></entry> 692 <entry>The number of bytes occupied by the data in the 693 buffer. It depends on the negotiated data format and may change with 694 each buffer for compressed variable size data like JPEG images. 695 Drivers must set this field when <structfield>type</structfield> 696 refers to a capture stream, applications when it refers to an output stream. 697 If the application sets this to 0 for an output stream, then 698 <structfield>bytesused</structfield> will be set to the size of the 699 buffer (see the <structfield>length</structfield> field of this struct) by 700 the driver. For multiplanar formats this field is ignored and the 701 <structfield>planes</structfield> pointer is used instead.</entry> 702 </row> 703 <row> 704 <entry>__u32</entry> 705 <entry><structfield>flags</structfield></entry> 706 <entry></entry> 707 <entry>Flags set by the application or driver, see <xref 708 linkend="buffer-flags" />.</entry> 709 </row> 710 <row> 711 <entry>__u32</entry> 712 <entry><structfield>field</structfield></entry> 713 <entry></entry> 714 <entry>Indicates the field order of the image in the 715 buffer, see <xref linkend="v4l2-field" />. This field is not used when 716 the buffer contains VBI data. Drivers must set it when 717 <structfield>type</structfield> refers to a capture stream, 718 applications when it refers to an output stream.</entry> 719 </row> 720 <row> 721 <entry>struct timeval</entry> 722 <entry><structfield>timestamp</structfield></entry> 723 <entry></entry> 724 <entry><para>For capture streams this is time when the first data 725 byte was captured, as returned by the 726 <function>clock_gettime()</function> function for the relevant 727 clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in 728 <xref linkend="buffer-flags" />. For output streams the driver 729 stores the time at which the last data byte was actually sent out 730 in the <structfield>timestamp</structfield> field. This permits 731 applications to monitor the drift between the video and system 732 clock. For output streams that use <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> 733 the application has to fill in the timestamp which will be copied 734 by the driver to the capture stream.</para></entry> 735 </row> 736 <row> 737 <entry>&v4l2-timecode;</entry> 738 <entry><structfield>timecode</structfield></entry> 739 <entry></entry> 740 <entry>When <structfield>type</structfield> is 741 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the 742 <constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in 743 <structfield>flags</structfield>, this structure contains a frame 744 timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> 745 mode the top and bottom field contain the same timecode. 746 Timecodes are intended to help video editing and are typically recorded on 747 video tapes, but also embedded in compressed formats like MPEG. This 748 field is independent of the <structfield>timestamp</structfield> and 749 <structfield>sequence</structfield> fields.</entry> 750 </row> 751 <row> 752 <entry>__u32</entry> 753 <entry><structfield>sequence</structfield></entry> 754 <entry></entry> 755 <entry>Set by the driver, counting the frames (not fields!) in 756 sequence. This field is set for both input and output devices.</entry> 757 </row> 758 <row> 759 <entry spanname="hspan"><para>In <link 760 linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and 761 bottom field have the same sequence number. The count starts at zero 762 and includes dropped or repeated frames. A dropped frame was received 763 by an input device but could not be stored due to lack of free buffer 764 space. A repeated frame was displayed again by an output device 765 because the application did not pass new data in 766 time.</para><para>Note this may count the frames received 767 e.g. over USB, without taking into account the frames dropped by the 768 remote hardware due to limited compression throughput or bus 769 bandwidth. These devices identify by not enumerating any video 770 standards, see <xref linkend="standard" />.</para></entry> 771 </row> 772 <row> 773 <entry>__u32</entry> 774 <entry><structfield>memory</structfield></entry> 775 <entry></entry> 776 <entry>This field must be set by applications and/or drivers 777 in accordance with the selected I/O method. See <xref linkend="v4l2-memory" 778 /></entry> 779 </row> 780 <row> 781 <entry>union</entry> 782 <entry><structfield>m</structfield></entry> 783 </row> 784 <row> 785 <entry></entry> 786 <entry>__u32</entry> 787 <entry><structfield>offset</structfield></entry> 788 <entry>For the single-planar API and when 789 <structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this 790 is the offset of the buffer from the start of the device memory. The value is 791 returned by the driver and apart of serving as parameter to the &func-mmap; 792 function not useful for applications. See <xref linkend="mmap" /> for details 793 </entry> 794 </row> 795 <row> 796 <entry></entry> 797 <entry>unsigned long</entry> 798 <entry><structfield>userptr</structfield></entry> 799 <entry>For the single-planar API and when 800 <structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant> 801 this is a pointer to the buffer (casted to unsigned long type) in virtual 802 memory, set by the application. See <xref linkend="userp" /> for details. 803 </entry> 804 </row> 805 <row> 806 <entry></entry> 807 <entry>struct v4l2_plane</entry> 808 <entry><structfield>*planes</structfield></entry> 809 <entry>When using the multi-planar API, contains a userspace pointer 810 to an array of &v4l2-plane;. The size of the array should be put 811 in the <structfield>length</structfield> field of this 812 <structname>v4l2_buffer</structname> structure.</entry> 813 </row> 814 <row> 815 <entry></entry> 816 <entry>int</entry> 817 <entry><structfield>fd</structfield></entry> 818 <entry>For the single-plane API and when 819 <structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this 820 is the file descriptor associated with a DMABUF buffer.</entry> 821 </row> 822 <row> 823 <entry>__u32</entry> 824 <entry><structfield>length</structfield></entry> 825 <entry></entry> 826 <entry>Size of the buffer (not the payload) in bytes for the 827 single-planar API. This is set by the driver based on the calls to 828 &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. For the multi-planar API the application sets 829 this to the number of elements in the <structfield>planes</structfield> 830 array. The driver will fill in the actual number of valid elements in 831 that array. 832 </entry> 833 </row> 834 <row> 835 <entry>__u32</entry> 836 <entry><structfield>reserved2</structfield></entry> 837 <entry></entry> 838 <entry>A place holder for future extensions. Drivers and applications 839 must set this to 0.</entry> 840 </row> 841 <row> 842 <entry>__u32</entry> 843 <entry><structfield>reserved</structfield></entry> 844 <entry></entry> 845 <entry>A place holder for future extensions. Drivers and applications 846 must set this to 0.</entry> 847 </row> 848 </tbody> 849 </tgroup> 850 </table> 851 852 <table frame="none" pgwide="1" id="v4l2-plane"> 853 <title>struct <structname>v4l2_plane</structname></title> 854 <tgroup cols="4"> 855 &cs-ustr; 856 <tbody valign="top"> 857 <row> 858 <entry>__u32</entry> 859 <entry><structfield>bytesused</structfield></entry> 860 <entry></entry> 861 <entry>The number of bytes occupied by data in the plane 862 (its payload). Drivers must set this field when <structfield>type</structfield> 863 refers to a capture stream, applications when it refers to an output stream. 864 If the application sets this to 0 for an output stream, then 865 <structfield>bytesused</structfield> will be set to the size of the 866 plane (see the <structfield>length</structfield> field of this struct) 867 by the driver. Note that the actual image data starts at 868 <structfield>data_offset</structfield> which may not be 0.</entry> 869 </row> 870 <row> 871 <entry>__u32</entry> 872 <entry><structfield>length</structfield></entry> 873 <entry></entry> 874 <entry>Size in bytes of the plane (not its payload). This is set by the driver 875 based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;.</entry> 876 </row> 877 <row> 878 <entry>union</entry> 879 <entry><structfield>m</structfield></entry> 880 <entry></entry> 881 <entry></entry> 882 </row> 883 <row> 884 <entry></entry> 885 <entry>__u32</entry> 886 <entry><structfield>mem_offset</structfield></entry> 887 <entry>When the memory type in the containing &v4l2-buffer; is 888 <constant>V4L2_MEMORY_MMAP</constant>, this is the value that 889 should be passed to &func-mmap;, similar to the 890 <structfield>offset</structfield> field in &v4l2-buffer;.</entry> 891 </row> 892 <row> 893 <entry></entry> 894 <entry>unsigned long</entry> 895 <entry><structfield>userptr</structfield></entry> 896 <entry>When the memory type in the containing &v4l2-buffer; is 897 <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace 898 pointer to the memory allocated for this plane by an application. 899 </entry> 900 </row> 901 <row> 902 <entry></entry> 903 <entry>int</entry> 904 <entry><structfield>fd</structfield></entry> 905 <entry>When the memory type in the containing &v4l2-buffer; is 906 <constant>V4L2_MEMORY_DMABUF</constant>, this is a file 907 descriptor associated with a DMABUF buffer, similar to the 908 <structfield>fd</structfield> field in &v4l2-buffer;.</entry> 909 </row> 910 <row> 911 <entry>__u32</entry> 912 <entry><structfield>data_offset</structfield></entry> 913 <entry></entry> 914 <entry>Offset in bytes to video data in the plane. 915 Drivers must set this field when <structfield>type</structfield> 916 refers to a capture stream, applications when it refers to an output stream. 917 Note that data_offset is included in <structfield>bytesused</structfield>. 918 So the size of the image in the plane is 919 <structfield>bytesused</structfield>-<structfield>data_offset</structfield> at 920 offset <structfield>data_offset</structfield> from the start of the plane. 921 </entry> 922 </row> 923 <row> 924 <entry>__u32</entry> 925 <entry><structfield>reserved[11]</structfield></entry> 926 <entry></entry> 927 <entry>Reserved for future use. Should be zeroed by drivers and 928 applications.</entry> 929 </row> 930 </tbody> 931 </tgroup> 932 </table> 933 934 <table frame="none" pgwide="1" id="v4l2-buf-type"> 935 <title>enum v4l2_buf_type</title> 936 <tgroup cols="3"> 937 &cs-def; 938 <tbody valign="top"> 939 <row> 940 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> 941 <entry>1</entry> 942 <entry>Buffer of a single-planar video capture stream, see <xref 943 linkend="capture" />.</entry> 944 </row> 945 <row> 946 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> 947 </entry> 948 <entry>9</entry> 949 <entry>Buffer of a multi-planar video capture stream, see <xref 950 linkend="capture" />.</entry> 951 </row> 952 <row> 953 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> 954 <entry>2</entry> 955 <entry>Buffer of a single-planar video output stream, see <xref 956 linkend="output" />.</entry> 957 </row> 958 <row> 959 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> 960 </entry> 961 <entry>10</entry> 962 <entry>Buffer of a multi-planar video output stream, see <xref 963 linkend="output" />.</entry> 964 </row> 965 <row> 966 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry> 967 <entry>3</entry> 968 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry> 969 </row> 970 <row> 971 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry> 972 <entry>4</entry> 973 <entry>Buffer of a raw VBI capture stream, see <xref 974 linkend="raw-vbi" />.</entry> 975 </row> 976 <row> 977 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry> 978 <entry>5</entry> 979 <entry>Buffer of a raw VBI output stream, see <xref 980 linkend="raw-vbi" />.</entry> 981 </row> 982 <row> 983 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry> 984 <entry>6</entry> 985 <entry>Buffer of a sliced VBI capture stream, see <xref 986 linkend="sliced" />.</entry> 987 </row> 988 <row> 989 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry> 990 <entry>7</entry> 991 <entry>Buffer of a sliced VBI output stream, see <xref 992 linkend="sliced" />.</entry> 993 </row> 994 <row> 995 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> 996 <entry>8</entry> 997 <entry>Buffer for video output overlay (OSD), see <xref 998 linkend="osd" />.</entry> 999 </row> 1000 <row> 1001 <entry><constant>V4L2_BUF_TYPE_SDR_CAPTURE</constant></entry> 1002 <entry>11</entry> 1003 <entry>Buffer for Software Defined Radio (SDR) capture stream, see 1004 <xref linkend="sdr" />.</entry> 1005 </row> 1006 <row> 1007 <entry><constant>V4L2_BUF_TYPE_SDR_OUTPUT</constant></entry> 1008 <entry>12</entry> 1009 <entry>Buffer for Software Defined Radio (SDR) output stream, see 1010 <xref linkend="sdr" />.</entry> 1011 </row> 1012 </tbody> 1013 </tgroup> 1014 </table> 1015 1016 <table frame="none" pgwide="1" id="buffer-flags"> 1017 <title>Buffer Flags</title> 1018 <tgroup cols="3"> 1019 &cs-def; 1020 <tbody valign="top"> 1021 <row> 1022 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry> 1023 <entry>0x00000001</entry> 1024 <entry>The buffer resides in device memory and has been mapped 1025 into the application's address space, see <xref linkend="mmap" /> for details. 1026 Drivers set or clear this flag when the 1027 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link 1028 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link 1029 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry> 1030 </row> 1031 <row> 1032 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry> 1033 <entry>0x00000002</entry> 1034 <entry>Internally drivers maintain two buffer queues, an 1035 incoming and outgoing queue. When this flag is set, the buffer is 1036 currently on the incoming queue. It automatically moves to the 1037 outgoing queue after the buffer has been filled (capture devices) or 1038 displayed (output devices). Drivers set or clear this flag when the 1039 <constant>VIDIOC_QUERYBUF</constant> ioctl is called. After 1040 (successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is 1041 always set and after <constant>VIDIOC_DQBUF</constant> always 1042 cleared.</entry> 1043 </row> 1044 <row> 1045 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry> 1046 <entry>0x00000004</entry> 1047 <entry>When this flag is set, the buffer is currently on 1048 the outgoing queue, ready to be dequeued from the driver. Drivers set 1049 or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl 1050 is called. After calling the <constant>VIDIOC_QBUF</constant> or 1051 <constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a 1052 buffer cannot be on both queues at the same time, the 1053 <constant>V4L2_BUF_FLAG_QUEUED</constant> and 1054 <constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive. 1055 They can be both cleared however, then the buffer is in "dequeued" 1056 state, in the application domain so to say.</entry> 1057 </row> 1058 <row> 1059 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry> 1060 <entry>0x00000040</entry> 1061 <entry>When this flag is set, the buffer has been dequeued 1062 successfully, although the data might have been corrupted. 1063 This is recoverable, streaming may continue as normal and 1064 the buffer may be reused normally. 1065 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant> 1066 ioctl is called.</entry> 1067 </row> 1068 <row> 1069 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry> 1070 <entry>0x00000008</entry> 1071 <entry>Drivers set or clear this flag when calling the 1072 <constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video 1073 capture devices when the buffer contains a compressed image which is a 1074 key frame (or field), &ie; can be decompressed on its own. Also known as 1075 an I-frame. Applications can set this bit when <structfield>type</structfield> 1076 refers to an output stream.</entry> 1077 </row> 1078 <row> 1079 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry> 1080 <entry>0x00000010</entry> 1081 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> 1082 this flags predicted frames or fields which contain only differences to a 1083 previous key frame. Applications can set this bit when <structfield>type</structfield> 1084 refers to an output stream.</entry> 1085 </row> 1086 <row> 1087 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry> 1088 <entry>0x00000020</entry> 1089 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant> 1090 this flags a bi-directional predicted frame or field which contains only 1091 the differences between the current frame and both the preceding and following 1092 key frames to specify its content. Applications can set this bit when 1093 <structfield>type</structfield> refers to an output stream.</entry> 1094 </row> 1095 <row> 1096 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry> 1097 <entry>0x00000100</entry> 1098 <entry>The <structfield>timecode</structfield> field is valid. 1099 Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> 1100 ioctl is called. Applications can set this bit and the corresponding 1101 <structfield>timecode</structfield> structure when <structfield>type</structfield> 1102 refers to an output stream.</entry> 1103 </row> 1104 <row> 1105 <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> 1106 <entry>0x00000400</entry> 1107 <entry>The buffer has been prepared for I/O and can be queued by the 1108 application. Drivers set or clear this flag when the 1109 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link 1110 linkend="vidioc-qbuf">VIDIOC_PREPARE_BUF</link>, <link 1111 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link 1112 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called.</entry> 1113 </row> 1114 <row> 1115 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> 1116 <entry>0x00000800</entry> 1117 <entry>Caches do not have to be invalidated for this buffer. 1118 Typically applications shall use this flag if the data captured in the buffer 1119 is not going to be touched by the CPU, instead the buffer will, probably, be 1120 passed on to a DMA-capable hardware unit for further processing or output. 1121 </entry> 1122 </row> 1123 <row> 1124 <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> 1125 <entry>0x00001000</entry> 1126 <entry>Caches do not have to be cleaned for this buffer. 1127 Typically applications shall use this flag for output buffers if the data 1128 in this buffer has not been created by the CPU but by some DMA-capable unit, 1129 in which case caches have not been used.</entry> 1130 </row> 1131 <row> 1132 <entry><constant>V4L2_BUF_FLAG_LAST</constant></entry> 1133 <entry>0x00100000</entry> 1134 <entry>Last buffer produced by the hardware. mem2mem codec drivers 1135 set this flag on the capture queue for the last buffer when the 1136 <link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link> or 1137 <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Due to hardware 1138 limitations, the last buffer may be empty. In this case the driver will set the 1139 <structfield>bytesused</structfield> field to 0, regardless of the format. Any 1140 Any subsequent call to the <link linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl 1141 will not block anymore, but return an &EPIPE;.</entry> 1142 </row> 1143 <row> 1144 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry> 1145 <entry>0x0000e000</entry> 1146 <entry>Mask for timestamp types below. To test the 1147 timestamp type, mask out bits not belonging to timestamp 1148 type by performing a logical and operation with buffer 1149 flags and timestamp mask.</entry> 1150 </row> 1151 <row> 1152 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry> 1153 <entry>0x00000000</entry> 1154 <entry>Unknown timestamp type. This type is used by 1155 drivers before Linux 3.9 and may be either monotonic (see 1156 below) or realtime (wall clock). Monotonic clock has been 1157 favoured in embedded systems whereas most of the drivers 1158 use the realtime clock. Either kinds of timestamps are 1159 available in user space via 1160 <function>clock_gettime(2)</function> using clock IDs 1161 <constant>CLOCK_MONOTONIC</constant> and 1162 <constant>CLOCK_REALTIME</constant>, respectively.</entry> 1163 </row> 1164 <row> 1165 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry> 1166 <entry>0x00002000</entry> 1167 <entry>The buffer timestamp has been taken from the 1168 <constant>CLOCK_MONOTONIC</constant> clock. To access the 1169 same clock outside V4L2, use 1170 <function>clock_gettime(2)</function>.</entry> 1171 </row> 1172 <row> 1173 <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry> 1174 <entry>0x00004000</entry> 1175 <entry>The CAPTURE buffer timestamp has been taken from the 1176 corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry> 1177 </row> 1178 <row> 1179 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant></entry> 1180 <entry>0x00070000</entry> 1181 <entry>Mask for timestamp sources below. The timestamp source 1182 defines the point of time the timestamp is taken in relation to 1183 the frame. Logical 'and' operation between the 1184 <structfield>flags</structfield> field and 1185 <constant>V4L2_BUF_FLAG_TSTAMP_SRC_MASK</constant> produces the 1186 value of the timestamp source. Applications must set the timestamp 1187 source when <structfield>type</structfield> refers to an output stream 1188 and <constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant> is set.</entry> 1189 </row> 1190 <row> 1191 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_EOF</constant></entry> 1192 <entry>0x00000000</entry> 1193 <entry>End Of Frame. The buffer timestamp has been taken 1194 when the last pixel of the frame has been received or the 1195 last pixel of the frame has been transmitted. In practice, 1196 software generated timestamps will typically be read from 1197 the clock a small amount of time after the last pixel has 1198 been received or transmitten, depending on the system and 1199 other activity in it.</entry> 1200 </row> 1201 <row> 1202 <entry><constant>V4L2_BUF_FLAG_TSTAMP_SRC_SOE</constant></entry> 1203 <entry>0x00010000</entry> 1204 <entry>Start Of Exposure. The buffer timestamp has been 1205 taken when the exposure of the frame has begun. This is 1206 only valid for the 1207 <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> buffer 1208 type.</entry> 1209 </row> 1210 </tbody> 1211 </tgroup> 1212 </table> 1213 1214 <table pgwide="1" frame="none" id="v4l2-memory"> 1215 <title>enum v4l2_memory</title> 1216 <tgroup cols="3"> 1217 &cs-def; 1218 <tbody valign="top"> 1219 <row> 1220 <entry><constant>V4L2_MEMORY_MMAP</constant></entry> 1221 <entry>1</entry> 1222 <entry>The buffer is used for <link linkend="mmap">memory 1223 mapping</link> I/O.</entry> 1224 </row> 1225 <row> 1226 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry> 1227 <entry>2</entry> 1228 <entry>The buffer is used for <link linkend="userp">user 1229 pointer</link> I/O.</entry> 1230 </row> 1231 <row> 1232 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry> 1233 <entry>3</entry> 1234 <entry>[to do]</entry> 1235 </row> 1236 <row> 1237 <entry><constant>V4L2_MEMORY_DMABUF</constant></entry> 1238 <entry>4</entry> 1239 <entry>The buffer is used for <link linkend="dmabuf">DMA shared 1240 buffer</link> I/O.</entry> 1241 </row> 1242 </tbody> 1243 </tgroup> 1244 </table> 1245 1246 <section> 1247 <title>Timecodes</title> 1248 1249 <para>The <structname>v4l2_timecode</structname> structure is 1250 designed to hold a <xref linkend="smpte12m" /> or similar timecode. 1251 (struct <structname>timeval</structname> timestamps are stored in 1252 &v4l2-buffer; field <structfield>timestamp</structfield>.)</para> 1253 1254 <table frame="none" pgwide="1" id="v4l2-timecode"> 1255 <title>struct <structname>v4l2_timecode</structname></title> 1256 <tgroup cols="3"> 1257 &cs-str; 1258 <tbody valign="top"> 1259 <row> 1260 <entry>__u32</entry> 1261 <entry><structfield>type</structfield></entry> 1262 <entry>Frame rate the timecodes are based on, see <xref 1263 linkend="timecode-type" />.</entry> 1264 </row> 1265 <row> 1266 <entry>__u32</entry> 1267 <entry><structfield>flags</structfield></entry> 1268 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry> 1269 </row> 1270 <row> 1271 <entry>__u8</entry> 1272 <entry><structfield>frames</structfield></entry> 1273 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the 1274 type of timecode.</entry> 1275 </row> 1276 <row> 1277 <entry>__u8</entry> 1278 <entry><structfield>seconds</structfield></entry> 1279 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry> 1280 </row> 1281 <row> 1282 <entry>__u8</entry> 1283 <entry><structfield>minutes</structfield></entry> 1284 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry> 1285 </row> 1286 <row> 1287 <entry>__u8</entry> 1288 <entry><structfield>hours</structfield></entry> 1289 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry> 1290 </row> 1291 <row> 1292 <entry>__u8</entry> 1293 <entry><structfield>userbits</structfield>[4]</entry> 1294 <entry>The "user group" bits from the timecode.</entry> 1295 </row> 1296 </tbody> 1297 </tgroup> 1298 </table> 1299 1300 <table frame="none" pgwide="1" id="timecode-type"> 1301 <title>Timecode Types</title> 1302 <tgroup cols="3"> 1303 &cs-def; 1304 <tbody valign="top"> 1305 <row> 1306 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry> 1307 <entry>1</entry> 1308 <entry>24 frames per second, i. e. film.</entry> 1309 </row> 1310 <row> 1311 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry> 1312 <entry>2</entry> 1313 <entry>25 frames per second, &ie; PAL or SECAM video.</entry> 1314 </row> 1315 <row> 1316 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry> 1317 <entry>3</entry> 1318 <entry>30 frames per second, &ie; NTSC video.</entry> 1319 </row> 1320 <row> 1321 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry> 1322 <entry>4</entry> 1323 <entry></entry> 1324 </row> 1325 <row> 1326 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry> 1327 <entry>5</entry> 1328 <entry></entry> 1329 </row> 1330 </tbody> 1331 </tgroup> 1332 </table> 1333 1334 <table frame="none" pgwide="1" id="timecode-flags"> 1335 <title>Timecode Flags</title> 1336 <tgroup cols="3"> 1337 &cs-def; 1338 <tbody valign="top"> 1339 <row> 1340 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry> 1341 <entry>0x0001</entry> 1342 <entry>Indicates "drop frame" semantics for counting frames 1343 in 29.97 fps material. When set, frame numbers 0 and 1 at the start of 1344 each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the 1345 count.</entry> 1346 </row> 1347 <row> 1348 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry> 1349 <entry>0x0002</entry> 1350 <entry>The "color frame" flag.</entry> 1351 </row> 1352 <row> 1353 <entry><constant>V4L2_TC_USERBITS_field</constant></entry> 1354 <entry>0x000C</entry> 1355 <entry>Field mask for the "binary group flags".</entry> 1356 </row> 1357 <row> 1358 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry> 1359 <entry>0x0000</entry> 1360 <entry>Unspecified format.</entry> 1361 </row> 1362 <row> 1363 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry> 1364 <entry>0x0008</entry> 1365 <entry>8-bit ISO characters.</entry> 1366 </row> 1367 </tbody> 1368 </tgroup> 1369 </table> 1370 </section> 1371 </section> 1372 1373 <section id="field-order"> 1374 <title>Field Order</title> 1375 1376 <para>We have to distinguish between progressive and interlaced 1377 video. Progressive video transmits all lines of a video image 1378 sequentially. Interlaced video divides an image into two fields, 1379 containing only the odd and even lines of the image, respectively. 1380 Alternating the so called odd and even field are transmitted, and due 1381 to a small delay between fields a cathode ray TV displays the lines 1382 interleaved, yielding the original frame. This curious technique was 1383 invented because at refresh rates similar to film the image would 1384 fade out too quickly. Transmitting fields reduces the flicker without 1385 the necessity of doubling the frame rate and with it the bandwidth 1386 required for each channel.</para> 1387 1388 <para>It is important to understand a video camera does not expose 1389 one frame at a time, merely transmitting the frames separated into 1390 fields. The fields are in fact captured at two different instances in 1391 time. An object on screen may well move between one field and the 1392 next. For applications analysing motion it is of paramount importance 1393 to recognize which field of a frame is older, the <emphasis>temporal 1394 order</emphasis>.</para> 1395 1396 <para>When the driver provides or accepts images field by field 1397 rather than interleaved, it is also important applications understand 1398 how the fields combine to frames. We distinguish between top (aka odd) and 1399 bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line 1400 of the top field is the first line of an interlaced frame, the first 1401 line of the bottom field is the second line of that frame.</para> 1402 1403 <para>However because fields were captured one after the other, 1404 arguing whether a frame commences with the top or bottom field is 1405 pointless. Any two successive top and bottom, or bottom and top fields 1406 yield a valid frame. Only when the source was progressive to begin 1407 with, ⪚ when transferring film to video, two fields may come from 1408 the same frame, creating a natural order.</para> 1409 1410 <para>Counter to intuition the top field is not necessarily the 1411 older field. Whether the older field contains the top or bottom lines 1412 is a convention determined by the video standard. Hence the 1413 distinction between temporal and spatial order of fields. The diagrams 1414 below should make this clearer.</para> 1415 1416 <para>All video capture and output devices must report the current 1417 field order. Some drivers may permit the selection of a different 1418 order, to this end applications initialize the 1419 <structfield>field</structfield> field of &v4l2-pix-format; before 1420 calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should 1421 have the value <constant>V4L2_FIELD_ANY</constant> (0).</para> 1422 1423 <table frame="none" pgwide="1" id="v4l2-field"> 1424 <title>enum v4l2_field</title> 1425 <tgroup cols="3"> 1426 &cs-def; 1427 <tbody valign="top"> 1428 <row> 1429 <entry><constant>V4L2_FIELD_ANY</constant></entry> 1430 <entry>0</entry> 1431 <entry>Applications request this field order when any 1432 one of the <constant>V4L2_FIELD_NONE</constant>, 1433 <constant>V4L2_FIELD_TOP</constant>, 1434 <constant>V4L2_FIELD_BOTTOM</constant>, or 1435 <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. 1436 Drivers choose depending on hardware capabilities or e. g. the 1437 requested image size, and return the actual field order. Drivers must 1438 never return <constant>V4L2_FIELD_ANY</constant>. If multiple 1439 field orders are possible the driver must choose one of the possible 1440 field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; 1441 <structfield>field</structfield> can never be 1442 <constant>V4L2_FIELD_ANY</constant>.</entry> 1443 </row> 1444 <row> 1445 <entry><constant>V4L2_FIELD_NONE</constant></entry> 1446 <entry>1</entry> 1447 <entry>Images are in progressive format, not interlaced. 1448 The driver may also indicate this order when it cannot distinguish 1449 between <constant>V4L2_FIELD_TOP</constant> and 1450 <constant>V4L2_FIELD_BOTTOM</constant>.</entry> 1451 </row> 1452 <row> 1453 <entry><constant>V4L2_FIELD_TOP</constant></entry> 1454 <entry>2</entry> 1455 <entry>Images consist of the top (aka odd) field only.</entry> 1456 </row> 1457 <row> 1458 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry> 1459 <entry>3</entry> 1460 <entry>Images consist of the bottom (aka even) field only. 1461 Applications may wish to prevent a device from capturing interlaced 1462 images because they will have "comb" or "feathering" artefacts around 1463 moving objects.</entry> 1464 </row> 1465 <row> 1466 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry> 1467 <entry>4</entry> 1468 <entry>Images contain both fields, interleaved line by 1469 line. The temporal order of the fields (whether the top or bottom 1470 field is first transmitted) depends on the current video standard. 1471 M/NTSC transmits the bottom field first, all other standards the top 1472 field first.</entry> 1473 </row> 1474 <row> 1475 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry> 1476 <entry>5</entry> 1477 <entry>Images contain both fields, the top field lines 1478 are stored first in memory, immediately followed by the bottom field 1479 lines. Fields are always stored in temporal order, the older one first 1480 in memory. Image sizes refer to the frame, not fields.</entry> 1481 </row> 1482 <row> 1483 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry> 1484 <entry>6</entry> 1485 <entry>Images contain both fields, the bottom field 1486 lines are stored first in memory, immediately followed by the top 1487 field lines. Fields are always stored in temporal order, the older one 1488 first in memory. Image sizes refer to the frame, not fields.</entry> 1489 </row> 1490 <row> 1491 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry> 1492 <entry>7</entry> 1493 <entry>The two fields of a frame are passed in separate 1494 buffers, in temporal order, &ie; the older one first. To indicate the field 1495 parity (whether the current field is a top or bottom field) the driver 1496 or application, depending on data direction, must set &v4l2-buffer; 1497 <structfield>field</structfield> to 1498 <constant>V4L2_FIELD_TOP</constant> or 1499 <constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair 1500 to build a frame. If fields are successive, without any dropped fields 1501 between them (fields can drop individually), can be determined from 1502 the &v4l2-buffer; <structfield>sequence</structfield> field. This format 1503 cannot be selected when using the read/write I/O method since there 1504 is no way to communicate if a field was a top or bottom field.</entry> 1505 </row> 1506 <row> 1507 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry> 1508 <entry>8</entry> 1509 <entry>Images contain both fields, interleaved line by 1510 line, top field first. The top field is transmitted first.</entry> 1511 </row> 1512 <row> 1513 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry> 1514 <entry>9</entry> 1515 <entry>Images contain both fields, interleaved line by 1516 line, top field first. The bottom field is transmitted first.</entry> 1517 </row> 1518 </tbody> 1519 </tgroup> 1520 </table> 1521 1522 <figure id="fieldseq-tb"> 1523 <title>Field Order, Top Field First Transmitted</title> 1524 <mediaobject> 1525 <imageobject> 1526 <imagedata fileref="fieldseq_tb.pdf" format="PS" /> 1527 </imageobject> 1528 <imageobject> 1529 <imagedata fileref="fieldseq_tb.gif" format="GIF" /> 1530 </imageobject> 1531 </mediaobject> 1532 </figure> 1533 1534 <figure id="fieldseq-bt"> 1535 <title>Field Order, Bottom Field First Transmitted</title> 1536 <mediaobject> 1537 <imageobject> 1538 <imagedata fileref="fieldseq_bt.pdf" format="PS" /> 1539 </imageobject> 1540 <imageobject> 1541 <imagedata fileref="fieldseq_bt.gif" format="GIF" /> 1542 </imageobject> 1543 </mediaobject> 1544 </figure> 1545 </section>
