1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Streaming I/O (Memory Mapping)</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="io.html" title="Chapter 3. Input/Output"><link rel="prev" href="io.html" title="Chapter 3. Input/Output"><link rel="next" href="userp.html" title="Streaming I/O (User Pointers)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Streaming I/O (Memory Mapping)</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Input/Output</th><td width="20%" align="right"> <a accesskey="n" href="userp.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mmap"></a>Streaming I/O (Memory Mapping)</h2></div></div></div><p>Input and output devices support this I/O method when the 2<code class="constant">V4L2_CAP_STREAMING</code> flag in the 3<em class="structfield"><code>capabilities</code></em> field of struct <a class="link" href="vidioc-querycap.html#v4l2-capability" title="Table A.93. struct v4l2_capability">v4l2_capability</a> 4returned by the <a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a> ioctl is set. There are two 5streaming methods, to determine if the memory mapping flavor is 6supported applications must call the <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl.</p><p>Streaming is an I/O method where only pointers to buffers 7are exchanged between application and driver, the data itself is not 8copied. Memory mapping is primarily intended to map buffers in device 9memory into the application's address space. Device memory can be for 10example the video memory on a graphics card with a video capture 11add-on. However, being the most efficient I/O method available for a 12long time, many other drivers support streaming as well, allocating 13buffers in DMA-able main memory.</p><p>A driver can support many sets of buffers. Each set is 14identified by a unique buffer type value. The sets are independent and 15each set can hold a different type of data. To access different sets 16at the same time different file descriptors must be used.<a href="#ftn.idp1104592876" class="footnote" name="idp1104592876"><sup class="footnote">[10]</sup></a></p><p>To allocate device buffers applications call the 17<a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl with the desired number of buffers and buffer 18type, for example <code class="constant">V4L2_BUF_TYPE_VIDEO_CAPTURE</code>. 19This ioctl can also be used to change the number of buffers or to free 20the allocated memory, provided none of the buffers are still 21mapped.</p><p>Before applications can access the buffers they must map 22them into their address space with the <a class="link" href="func-mmap.html" title="V4L2 mmap()"><code class="function">mmap()</code></a> function. The 23location of the buffers in device memory can be determined with the 24<a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a> ioctl. In the single-planar API case, the 25<em class="structfield"><code>m.offset</code></em> and <em class="structfield"><code>length</code></em> 26returned in a struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> are passed as sixth and second parameter to the 27<code class="function">mmap()</code> function. When using the multi-planar API, 28struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> contains an array of struct <a class="link" href="buffer.html#v4l2-plane" title="Table 3.2. struct v4l2_plane">v4l2_plane</a> structures, each 29containing its own <em class="structfield"><code>m.offset</code></em> and 30<em class="structfield"><code>length</code></em>. When using the multi-planar API, every 31plane of every buffer has to be mapped separately, so the number of 32calls to <a class="link" href="func-mmap.html" title="V4L2 mmap()"><code class="function">mmap()</code></a> should be equal to number of buffers times number of 33planes in each buffer. The offset and length values must not be modified. 34Remember, the buffers are allocated in physical memory, as opposed to virtual 35memory, which can be swapped out to disk. Applications should free the buffers 36as soon as possible with the <a class="link" href="func-munmap.html" title="V4L2 munmap()"><code class="function">munmap()</code></a> function.</p><div class="example"><a name="idp1104601204"></a><p class="title"><b>Example 3.1. Mapping buffers in the single-planar API</b></p><div class="example-contents"><pre class="programlisting"> 37struct <a class="link" href="vidioc-reqbufs.html#v4l2-requestbuffers" title="Table A.100. struct v4l2_requestbuffers">v4l2_requestbuffers</a> reqbuf; 38struct { 39 void *start; 40 size_t length; 41} *buffers; 42unsigned int i; 43 44memset(&reqbuf, 0, sizeof(reqbuf)); 45reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 46reqbuf.memory = V4L2_MEMORY_MMAP; 47reqbuf.count = 20; 48 49if (-1 == ioctl (fd, <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a>, &reqbuf)) { 50 if (errno == EINVAL) 51 printf("Video capturing or mmap-streaming is not supported\n"); 52 else 53 perror("VIDIOC_REQBUFS"); 54 55 exit(EXIT_FAILURE); 56} 57 58/* We want at least five buffers. */ 59 60if (reqbuf.count < 5) { 61 /* You may need to free the buffers here. */ 62 printf("Not enough buffer memory\n"); 63 exit(EXIT_FAILURE); 64} 65 66buffers = calloc(reqbuf.count, sizeof(*buffers)); 67assert(buffers != NULL); 68 69for (i = 0; i < reqbuf.count; i++) { 70 struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> buffer; 71 72 memset(&buffer, 0, sizeof(buffer)); 73 buffer.type = reqbuf.type; 74 buffer.memory = V4L2_MEMORY_MMAP; 75 buffer.index = i; 76 77 if (-1 == ioctl (fd, <a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a>, &buffer)) { 78 perror("VIDIOC_QUERYBUF"); 79 exit(EXIT_FAILURE); 80 } 81 82 buffers[i].length = buffer.length; /* remember for munmap() */ 83 84 buffers[i].start = mmap(NULL, buffer.length, 85 PROT_READ | PROT_WRITE, /* recommended */ 86 MAP_SHARED, /* recommended */ 87 fd, buffer.m.offset); 88 89 if (MAP_FAILED == buffers[i].start) { 90 /* If you do not exit here you should unmap() and free() 91 the buffers mapped so far. */ 92 perror("mmap"); 93 exit(EXIT_FAILURE); 94 } 95} 96 97/* Cleanup. */ 98 99for (i = 0; i < reqbuf.count; i++) 100 munmap(buffers[i].start, buffers[i].length); 101 </pre></div></div><br class="example-break"><div class="example"><a name="idp1104607188"></a><p class="title"><b>Example 3.2. Mapping buffers in the multi-planar API</b></p><div class="example-contents"><pre class="programlisting"> 102struct <a class="link" href="vidioc-reqbufs.html#v4l2-requestbuffers" title="Table A.100. struct v4l2_requestbuffers">v4l2_requestbuffers</a> reqbuf; 103/* Our current format uses 3 planes per buffer */ 104#define FMT_NUM_PLANES = 3 105 106struct { 107 void *start[FMT_NUM_PLANES]; 108 size_t length[FMT_NUM_PLANES]; 109} *buffers; 110unsigned int i, j; 111 112memset(&reqbuf, 0, sizeof(reqbuf)); 113reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; 114reqbuf.memory = V4L2_MEMORY_MMAP; 115reqbuf.count = 20; 116 117if (ioctl(fd, <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a>, &reqbuf) < 0) { 118 if (errno == EINVAL) 119 printf("Video capturing or mmap-streaming is not supported\n"); 120 else 121 perror("VIDIOC_REQBUFS"); 122 123 exit(EXIT_FAILURE); 124} 125 126/* We want at least five buffers. */ 127 128if (reqbuf.count < 5) { 129 /* You may need to free the buffers here. */ 130 printf("Not enough buffer memory\n"); 131 exit(EXIT_FAILURE); 132} 133 134buffers = calloc(reqbuf.count, sizeof(*buffers)); 135assert(buffers != NULL); 136 137for (i = 0; i < reqbuf.count; i++) { 138 struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> buffer; 139 struct <a class="link" href="buffer.html#v4l2-plane" title="Table 3.2. struct v4l2_plane">v4l2_plane</a> planes[FMT_NUM_PLANES]; 140 141 memset(&buffer, 0, sizeof(buffer)); 142 buffer.type = reqbuf.type; 143 buffer.memory = V4L2_MEMORY_MMAP; 144 buffer.index = i; 145 /* length in struct v4l2_buffer in multi-planar API stores the size 146 * of planes array. */ 147 buffer.length = FMT_NUM_PLANES; 148 buffer.m.planes = planes; 149 150 if (ioctl(fd, <a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a>, &buffer) < 0) { 151 perror("VIDIOC_QUERYBUF"); 152 exit(EXIT_FAILURE); 153 } 154 155 /* Every plane has to be mapped separately */ 156 for (j = 0; j < FMT_NUM_PLANES; j++) { 157 buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */ 158 159 buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length, 160 PROT_READ | PROT_WRITE, /* recommended */ 161 MAP_SHARED, /* recommended */ 162 fd, buffer.m.planes[j].m.offset); 163 164 if (MAP_FAILED == buffers[i].start[j]) { 165 /* If you do not exit here you should unmap() and free() 166 the buffers and planes mapped so far. */ 167 perror("mmap"); 168 exit(EXIT_FAILURE); 169 } 170 } 171} 172 173/* Cleanup. */ 174 175for (i = 0; i < reqbuf.count; i++) 176 for (j = 0; j < FMT_NUM_PLANES; j++) 177 munmap(buffers[i].start[j], buffers[i].length[j]); 178 </pre></div></div><br class="example-break"><p>Conceptually streaming drivers maintain two buffer queues, an incoming 179and an outgoing queue. They separate the synchronous capture or output 180operation locked to a video clock from the application which is 181subject to random disk or network delays and preemption by 182other processes, thereby reducing the probability of data loss. 183The queues are organized as FIFOs, buffers will be 184output in the order enqueued in the incoming FIFO, and were 185captured in the order dequeued from the outgoing FIFO.</p><p>The driver may require a minimum number of buffers enqueued 186at all times to function, apart of this no limit exists on the number 187of buffers applications can enqueue in advance, or dequeue and 188process. They can also enqueue in a different order than buffers have 189been dequeued, and the driver can <span class="emphasis"><em>fill</em></span> enqueued 190<span class="emphasis"><em>empty</em></span> buffers in any order. <a href="#ftn.idp1104614756" class="footnote" name="idp1104614756"><sup class="footnote">[11]</sup></a> The index number of a buffer (struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> 191<em class="structfield"><code>index</code></em>) plays no role here, it only 192identifies the buffer.</p><p>Initially all mapped buffers are in dequeued state, 193inaccessible by the driver. For capturing applications it is customary 194to first enqueue all mapped buffers, then to start capturing and enter 195the read loop. Here the application waits until a filled buffer can be 196dequeued, and re-enqueues the buffer when the data is no longer 197needed. Output applications fill and enqueue buffers, when enough 198buffers are stacked up the output is started with 199<code class="constant">VIDIOC_STREAMON</code>. In the write loop, when 200the application runs out of free buffers, it must wait until an empty 201buffer can be dequeued and reused.</p><p>To enqueue and dequeue a buffer applications use the 202<a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_QBUF</code></a> and <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_DQBUF</code></a> ioctl. The status of a buffer being 203mapped, enqueued, full or empty can be determined at any time using the 204<a class="link" href="vidioc-querybuf.html" title="ioctl VIDIOC_QUERYBUF"><code class="constant">VIDIOC_QUERYBUF</code></a> ioctl. Two methods exist to suspend execution of the 205application until one or more buffers can be dequeued. By default 206<code class="constant">VIDIOC_DQBUF</code> blocks when no buffer is in the 207outgoing queue. When the <code class="constant">O_NONBLOCK</code> flag was 208given to the <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a> function, <code class="constant">VIDIOC_DQBUF</code> 209returns immediately with an <span class="errorcode">EAGAIN</span> error code when no buffer is available. The 210<a class="link" href="func-select.html" title="V4L2 select()"><code class="function">select()</code></a> or <a class="link" href="func-poll.html" title="V4L2 poll()"><code class="function">poll()</code></a> functions are always available.</p><p>To start and stop capturing or output applications call the 211<a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMON</code></a> and <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMOFF</code></a> ioctl. Note 212<code class="constant">VIDIOC_STREAMOFF</code> removes all buffers from both 213queues as a side effect. Since there is no notion of doing anything 214"now" on a multitasking system, if an application needs to synchronize 215with another event it should examine the struct <a class="link" href="buffer.html#v4l2-buffer" title="Table 3.1. struct v4l2_buffer">v4l2_buffer</a> 216<em class="structfield"><code>timestamp</code></em> of captured or outputted buffers. 217</p><p>Drivers implementing memory mapping I/O must 218support the <code class="constant">VIDIOC_REQBUFS</code>, 219<code class="constant">VIDIOC_QUERYBUF</code>, 220<code class="constant">VIDIOC_QBUF</code>, <code class="constant">VIDIOC_DQBUF</code>, 221<code class="constant">VIDIOC_STREAMON</code> and 222<code class="constant">VIDIOC_STREAMOFF</code> ioctl, the 223<code class="function">mmap()</code>, <code class="function">munmap()</code>, 224<code class="function">select()</code> and <code class="function">poll()</code> 225function.<a href="#ftn.idp1104628188" class="footnote" name="idp1104628188"><sup class="footnote">[12]</sup></a></p><p>[capture example]</p><div class="footnotes"><br><hr style="width:100; text-align:left;margin-left: 0"><div id="ftn.idp1104592876" class="footnote"><p><a href="#idp1104592876" class="para"><sup class="para">[10] </sup></a>One could use one file descriptor and set the buffer 226type field accordingly when calling <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_QBUF</code></a> etc., but it makes 227the <code class="function">select()</code> function ambiguous. We also like the 228clean approach of one file descriptor per logical stream. Video 229overlay for example is also a logical stream, although the CPU is not 230needed for continuous operation.</p></div><div id="ftn.idp1104614756" class="footnote"><p><a href="#idp1104614756" class="para"><sup class="para">[11] </sup></a>Random enqueue order permits applications processing 231images out of order (such as video codecs) to return buffers earlier, 232reducing the probability of data loss. Random fill order allows 233drivers to reuse buffers on a LIFO-basis, taking advantage of caches 234holding scatter-gather lists and the like.</p></div><div id="ftn.idp1104628188" class="footnote"><p><a href="#idp1104628188" class="para"><sup class="para">[12] </sup></a>At the driver level <code class="function">select()</code> and 235<code class="function">poll()</code> are the same, and 236<code class="function">select()</code> is too important to be optional. The 237rest should be evident.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="io.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="io.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="userp.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Input/Output </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Streaming I/O (User Pointers)</td></tr></table></div></body></html> 238