1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"> 2<HTML 3><HEAD 4><TITLE 5>Streaming I/O (Memory Mapping)</TITLE 6><META 7NAME="GENERATOR" 8CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK 9REL="HOME" 10TITLE="Video for Linux Two API Specification" 11HREF="book1.htm"><LINK 12REL="UP" 13TITLE="Input/Output" 14HREF="c5742.htm"><LINK 15REL="PREVIOUS" 16TITLE="Input/Output" 17HREF="c5742.htm"><LINK 18REL="NEXT" 19TITLE="Streaming I/O (User Pointers)" 20HREF="x5884.htm"></HEAD 21><BODY 22CLASS="SECTION" 23BGCOLOR="#FFFFFF" 24TEXT="#000000" 25LINK="#0000FF" 26VLINK="#840084" 27ALINK="#0000FF" 28><DIV 29CLASS="NAVHEADER" 30><TABLE 31SUMMARY="Header navigation table" 32WIDTH="100%" 33BORDER="0" 34CELLPADDING="0" 35CELLSPACING="0" 36><TR 37><TH 38COLSPAN="3" 39ALIGN="center" 40>Video for Linux Two API Specification: Revision 0.24</TH 41></TR 42><TR 43><TD 44WIDTH="10%" 45ALIGN="left" 46VALIGN="bottom" 47><A 48HREF="c5742.htm" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56>Chapter 3. Input/Output</TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="x5884.htm" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><DIV 72CLASS="SECTION" 73><H1 74CLASS="SECTION" 75><A 76NAME="MMAP" 77>3.2. Streaming I/O (Memory Mapping)</A 78></H1 79><P 80>Input and output devices support this I/O method when the 81<CODE 82CLASS="CONSTANT" 83>V4L2_CAP_STREAMING</CODE 84> flag in the 85<CODE 86CLASS="STRUCTFIELD" 87>capabilities</CODE 88> field of struct <A 89HREF="r13105.htm#V4L2-CAPABILITY" 90>v4l2_capability</A 91> 92returned by the <A 93HREF="r13105.htm" 94><CODE 95CLASS="CONSTANT" 96>VIDIOC_QUERYCAP</CODE 97></A 98> ioctl is set. There are two 99streaming methods, to determine if the memory mapping flavor is 100supported applications must call the <A 101HREF="r13696.htm" 102><CODE 103CLASS="CONSTANT" 104>VIDIOC_REQBUFS</CODE 105></A 106> ioctl.</P 107><P 108>Streaming is an I/O method where only pointers to buffers 109are exchanged between application and driver, the data itself is not 110copied. Memory mapping is primarily intended to map buffers in device 111memory into the application's address space. Device memory can be for 112example the video memory on a graphics card with a video capture 113add-on. However, being the most efficient I/O method available for a 114long time, many other drivers support streaming as well, allocating 115buffers in DMA-able main memory.</P 116><P 117>A driver can support many sets of buffers. Each set is 118identified by a unique buffer type value. The sets are independent and 119each set can hold a different type of data. To access different sets 120at the same time different file descriptors must be used.<A 121NAME="AEN5803" 122HREF="x5791.htm#FTN.AEN5803" 123><SPAN 124CLASS="footnote" 125>[1]</SPAN 126></A 127></P 128><P 129>To allocate device buffers applications call the 130<A 131HREF="r13696.htm" 132><CODE 133CLASS="CONSTANT" 134>VIDIOC_REQBUFS</CODE 135></A 136> ioctl with the desired number of buffers and buffer 137type, for example <CODE 138CLASS="CONSTANT" 139>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE 140>. 141This ioctl can also be used to change the number of buffers or to free 142the allocated memory, provided none of the buffers are still 143mapped.</P 144><P 145>Before applications can access the buffers they must map 146them into their address space with the <A 147HREF="r13889.htm" 148><CODE 149CLASS="FUNCTION" 150>mmap()</CODE 151></A 152> function. The 153location of the buffers in device memory can be determined with the 154<A 155HREF="r13022.htm" 156><CODE 157CLASS="CONSTANT" 158>VIDIOC_QUERYBUF</CODE 159></A 160> ioctl. The <CODE 161CLASS="STRUCTFIELD" 162>m.offset</CODE 163> and 164<CODE 165CLASS="STRUCTFIELD" 166>length</CODE 167> returned in a struct <A 168HREF="x5953.htm#V4L2-BUFFER" 169>v4l2_buffer</A 170> are 171passed as sixth and second parameter to the 172<CODE 173CLASS="FUNCTION" 174>mmap()</CODE 175> function. The offset and length values 176must not be modified. Remember the buffers are allocated in physical 177memory, as opposed to virtual memory which can be swapped out to disk. 178Applications should free the buffers as soon as possible with the 179<A 180HREF="r14037.htm" 181><CODE 182CLASS="FUNCTION" 183>munmap()</CODE 184></A 185> function.</P 186><DIV 187CLASS="EXAMPLE" 188><A 189NAME="AEN5823" 190></A 191><P 192><B 193>Example 3-1. Mapping buffers</B 194></P 195><PRE 196CLASS="PROGRAMLISTING" 197>struct <A 198HREF="r13696.htm#V4L2-REQUESTBUFFERS" 199>v4l2_requestbuffers</A 200> reqbuf; 201struct { 202 void *start; 203 size_t length; 204} *buffers; 205unsigned int i; 206 207memset (&reqbuf, 0, sizeof (reqbuf)); 208reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 209reqbuf.memory = V4L2_MEMORY_MMAP; 210reqbuf.count = 20; 211 212if (-1 == ioctl (fd, <A 213HREF="r13696.htm" 214><CODE 215CLASS="CONSTANT" 216>VIDIOC_REQBUFS</CODE 217></A 218>, &reqbuf)) { 219 if (errno == EINVAL) 220 printf ("Video capturing or mmap-streaming is not supported\n"); 221 else 222 perror ("VIDIOC_REQBUFS"); 223 224 exit (EXIT_FAILURE); 225} 226 227/* We want at least five buffers. */ 228 229if (reqbuf.count < 5) { 230 /* You may need to free the buffers here. */ 231 printf ("Not enough buffer memory\n"); 232 exit (EXIT_FAILURE); 233} 234 235buffers = calloc (reqbuf.count, sizeof (*buffers)); 236assert (buffers != NULL); 237 238for (i = 0; i < reqbuf.count; i++) { 239 struct <A 240HREF="x5953.htm#V4L2-BUFFER" 241>v4l2_buffer</A 242> buffer; 243 244 memset (&buffer, 0, sizeof (buffer)); 245 buffer.type = reqbuf.type; 246 buffer.memory = V4L2_MEMORY_MMAP; 247 buffer.index = i; 248 249 if (-1 == ioctl (fd, <A 250HREF="r13022.htm" 251><CODE 252CLASS="CONSTANT" 253>VIDIOC_QUERYBUF</CODE 254></A 255>, &buffer)) { 256 perror ("VIDIOC_QUERYBUF"); 257 exit (EXIT_FAILURE); 258 } 259 260 buffers[i].length = buffer.length; /* remember for munmap() */ 261 262 buffers[i].start = mmap (NULL, buffer.length, 263 PROT_READ | PROT_WRITE, /* recommended */ 264 MAP_SHARED, /* recommended */ 265 fd, buffer.m.offset); 266 267 if (MAP_FAILED == buffers[i].start) { 268 /* If you do not exit here you should unmap() and free() 269 the buffers mapped so far. */ 270 perror ("mmap"); 271 exit (EXIT_FAILURE); 272 } 273} 274 275/* Cleanup. */ 276 277for (i = 0; i < reqbuf.count; i++) 278 munmap (buffers[i].start, buffers[i].length); 279 </PRE 280></DIV 281><P 282>Conceptually streaming drivers maintain two buffer queues, an incoming 283and an outgoing queue. They separate the synchronous capture or output 284operation locked to a video clock from the application which is 285subject to random disk or network delays and preemption by 286other processes, thereby reducing the probability of data loss. 287The queues are organized as FIFOs, buffers will be 288output in the order enqueued in the incoming FIFO, and were 289captured in the order dequeued from the outgoing FIFO.</P 290><P 291>The driver may require a minimum number of buffers enqueued 292at all times to function, apart of this no limit exists on the number 293of buffers applications can enqueue in advance, or dequeue and 294process. They can also enqueue in a different order than buffers have 295been dequeued, and the driver can <SPAN 296CLASS="emphasis" 297><I 298CLASS="EMPHASIS" 299>fill</I 300></SPAN 301> enqueued 302<SPAN 303CLASS="emphasis" 304><I 305CLASS="EMPHASIS" 306>empty</I 307></SPAN 308> buffers in any order. <A 309NAME="AEN5836" 310HREF="x5791.htm#FTN.AEN5836" 311><SPAN 312CLASS="footnote" 313>[2]</SPAN 314></A 315> The index number of a buffer (struct <A 316HREF="x5953.htm#V4L2-BUFFER" 317>v4l2_buffer</A 318> 319<CODE 320CLASS="STRUCTFIELD" 321>index</CODE 322>) plays no role here, it only 323identifies the buffer.</P 324><P 325>Initially all mapped buffers are in dequeued state, 326inaccessible by the driver. For capturing applications it is customary 327to first enqueue all mapped buffers, then to start capturing and enter 328the read loop. Here the application waits until a filled buffer can be 329dequeued, and re-enqueues the buffer when the data is no longer 330needed. Output applications fill and enqueue buffers, when enough 331buffers are stacked up the output is started with 332<CODE 333CLASS="CONSTANT" 334>VIDIOC_STREAMON</CODE 335>. In the write loop, when 336the application runs out of free buffers, it must wait until an empty 337buffer can be dequeued and reused.</P 338><P 339>To enqueue and dequeue a buffer applications use the 340<A 341HREF="r12878.htm" 342><CODE 343CLASS="CONSTANT" 344>VIDIOC_QBUF</CODE 345></A 346> and <A 347HREF="r12878.htm" 348><CODE 349CLASS="CONSTANT" 350>VIDIOC_DQBUF</CODE 351></A 352> ioctl. The status of a buffer being 353mapped, enqueued, full or empty can be determined at any time using the 354<A 355HREF="r13022.htm" 356><CODE 357CLASS="CONSTANT" 358>VIDIOC_QUERYBUF</CODE 359></A 360> ioctl. Two methods exist to suspend execution of the 361application until one or more buffers can be dequeued. By default 362<CODE 363CLASS="CONSTANT" 364>VIDIOC_DQBUF</CODE 365> blocks when no buffer is in the 366outgoing queue. When the <CODE 367CLASS="CONSTANT" 368>O_NONBLOCK</CODE 369> flag was 370given to the <A 371HREF="r14090.htm" 372><CODE 373CLASS="FUNCTION" 374>open()</CODE 375></A 376> function, <CODE 377CLASS="CONSTANT" 378>VIDIOC_DQBUF</CODE 379> 380returns immediately with an <SPAN 381CLASS="ERRORCODE" 382>EAGAIN</SPAN 383> error code when no buffer is available. The 384<A 385HREF="r14390.htm" 386><CODE 387CLASS="FUNCTION" 388>select()</CODE 389></A 390> or <A 391HREF="r14169.htm" 392><CODE 393CLASS="FUNCTION" 394>poll()</CODE 395></A 396> function are always available.</P 397><P 398>To start and stop capturing or output applications call the 399<A 400HREF="r13817.htm" 401><CODE 402CLASS="CONSTANT" 403>VIDIOC_STREAMON</CODE 404></A 405> and <A 406HREF="r13817.htm" 407><CODE 408CLASS="CONSTANT" 409>VIDIOC_STREAMOFF</CODE 410></A 411> ioctl. Note 412<CODE 413CLASS="CONSTANT" 414>VIDIOC_STREAMOFF</CODE 415> removes all buffers from both 416queues as a side effect. Since there is no notion of doing anything 417"now" on a multitasking system, if an application needs to synchronize 418with another event it should examine the struct <A 419HREF="x5953.htm#V4L2-BUFFER" 420>v4l2_buffer</A 421> 422<CODE 423CLASS="STRUCTFIELD" 424>timestamp</CODE 425> of captured buffers, or set the 426field before enqueuing buffers for output.</P 427><P 428>Drivers implementing memory mapping I/O must 429support the <CODE 430CLASS="CONSTANT" 431>VIDIOC_REQBUFS</CODE 432>, 433<CODE 434CLASS="CONSTANT" 435>VIDIOC_QUERYBUF</CODE 436>, 437<CODE 438CLASS="CONSTANT" 439>VIDIOC_QBUF</CODE 440>, <CODE 441CLASS="CONSTANT" 442>VIDIOC_DQBUF</CODE 443>, 444<CODE 445CLASS="CONSTANT" 446>VIDIOC_STREAMON</CODE 447> and 448<CODE 449CLASS="CONSTANT" 450>VIDIOC_STREAMOFF</CODE 451> ioctl, the 452<CODE 453CLASS="FUNCTION" 454>mmap()</CODE 455>, <CODE 456CLASS="FUNCTION" 457>munmap()</CODE 458>, 459<CODE 460CLASS="FUNCTION" 461>select()</CODE 462> and <CODE 463CLASS="FUNCTION" 464>poll()</CODE 465> 466function.<A 467NAME="AEN5878" 468HREF="x5791.htm#FTN.AEN5878" 469><SPAN 470CLASS="footnote" 471>[3]</SPAN 472></A 473></P 474><P 475>[capture example]</P 476></DIV 477><H3 478CLASS="FOOTNOTES" 479>Notes</H3 480><TABLE 481BORDER="0" 482CLASS="FOOTNOTES" 483WIDTH="100%" 484><TR 485><TD 486ALIGN="LEFT" 487VALIGN="TOP" 488WIDTH="5%" 489><A 490NAME="FTN.AEN5803" 491HREF="x5791.htm#AEN5803" 492><SPAN 493CLASS="footnote" 494>[1]</SPAN 495></A 496></TD 497><TD 498ALIGN="LEFT" 499VALIGN="TOP" 500WIDTH="95%" 501><P 502>One could use one file descriptor and set the buffer 503type field accordingly when calling <A 504HREF="r12878.htm" 505><CODE 506CLASS="CONSTANT" 507>VIDIOC_QBUF</CODE 508></A 509> etc., but it makes 510the <CODE 511CLASS="FUNCTION" 512>select()</CODE 513> function ambiguous. We also like the 514clean approach of one file descriptor per logical stream. Video 515overlay for example is also a logical stream, although the CPU is not 516needed for continuous operation.</P 517></TD 518></TR 519><TR 520><TD 521ALIGN="LEFT" 522VALIGN="TOP" 523WIDTH="5%" 524><A 525NAME="FTN.AEN5836" 526HREF="x5791.htm#AEN5836" 527><SPAN 528CLASS="footnote" 529>[2]</SPAN 530></A 531></TD 532><TD 533ALIGN="LEFT" 534VALIGN="TOP" 535WIDTH="95%" 536><P 537>Random enqueue order permits applications processing 538images out of order (such as video codecs) to return buffers earlier, 539reducing the probability of data loss. Random fill order allows 540drivers to reuse buffers on a LIFO-basis, taking advantage of caches 541holding scatter-gather lists and the like.</P 542></TD 543></TR 544><TR 545><TD 546ALIGN="LEFT" 547VALIGN="TOP" 548WIDTH="5%" 549><A 550NAME="FTN.AEN5878" 551HREF="x5791.htm#AEN5878" 552><SPAN 553CLASS="footnote" 554>[3]</SPAN 555></A 556></TD 557><TD 558ALIGN="LEFT" 559VALIGN="TOP" 560WIDTH="95%" 561><P 562>At the driver level <CODE 563CLASS="FUNCTION" 564>select()</CODE 565> and 566<CODE 567CLASS="FUNCTION" 568>poll()</CODE 569> are the same, and 570<CODE 571CLASS="FUNCTION" 572>select()</CODE 573> is too important to be optional. The 574rest should be evident.</P 575></TD 576></TR 577></TABLE 578><DIV 579CLASS="NAVFOOTER" 580><HR 581ALIGN="LEFT" 582WIDTH="100%"><TABLE 583SUMMARY="Footer navigation table" 584WIDTH="100%" 585BORDER="0" 586CELLPADDING="0" 587CELLSPACING="0" 588><TR 589><TD 590WIDTH="33%" 591ALIGN="left" 592VALIGN="top" 593><A 594HREF="c5742.htm" 595ACCESSKEY="P" 596>Prev</A 597></TD 598><TD 599WIDTH="34%" 600ALIGN="center" 601VALIGN="top" 602><A 603HREF="book1.htm" 604ACCESSKEY="H" 605>Home</A 606></TD 607><TD 608WIDTH="33%" 609ALIGN="right" 610VALIGN="top" 611><A 612HREF="x5884.htm" 613ACCESSKEY="N" 614>Next</A 615></TD 616></TR 617><TR 618><TD 619WIDTH="33%" 620ALIGN="left" 621VALIGN="top" 622>Input/Output</TD 623><TD 624WIDTH="34%" 625ALIGN="center" 626VALIGN="top" 627><A 628HREF="c5742.htm" 629ACCESSKEY="U" 630>Up</A 631></TD 632><TD 633WIDTH="33%" 634ALIGN="right" 635VALIGN="top" 636>Streaming I/O (User Pointers)</TD 637></TR 638></TABLE 639></DIV 640></BODY 641></HTML 642> 643