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&nbsp;<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&nbsp;<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&nbsp;<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 (&amp;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>, &amp;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 &lt; 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 &lt; reqbuf.count; i++) {
239        struct&nbsp;<A
240HREF="x5953.htm#V4L2-BUFFER"
241>v4l2_buffer</A
242> buffer;
243
244        memset (&amp;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>, &amp;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 &lt; 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&nbsp;<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&nbsp;<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