• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 (User Pointers)</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="Streaming I/O (Memory Mapping)"
17HREF="x5791.htm"><LINK
18REL="NEXT"
19TITLE="Asynchronous I/O"
20HREF="x5950.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="x5791.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="x5950.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="USERP"
77>3.3. Streaming I/O (User Pointers)</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. If the particular user
99pointer method (not only memory mapping) is supported must be
100determined by calling the <A
101HREF="r13696.htm"
102><CODE
103CLASS="CONSTANT"
104>VIDIOC_REQBUFS</CODE
105></A
106> ioctl.</P
107><P
108>This I/O method combines advantages of the read/write and
109memory mapping methods. Buffers are allocated by the application
110itself, and can reside for example in virtual or shared memory. Only
111pointers to data are exchanged, these pointers and meta-information
112are passed in struct&nbsp;<A
113HREF="x5953.htm#V4L2-BUFFER"
114>v4l2_buffer</A
115>. The driver must be switched
116into user pointer I/O mode by calling the <A
117HREF="r13696.htm"
118><CODE
119CLASS="CONSTANT"
120>VIDIOC_REQBUFS</CODE
121></A
122> with the
123desired buffer type. No buffers are allocated beforehands,
124consequently they are not indexed and cannot be queried like mapped
125buffers with the <CODE
126CLASS="CONSTANT"
127>VIDIOC_QUERYBUF</CODE
128> ioctl.</P
129><DIV
130CLASS="EXAMPLE"
131><A
132NAME="AEN5899"
133></A
134><P
135><B
136>Example 3-2. Initiating streaming I/O with user pointers</B
137></P
138><PRE
139CLASS="PROGRAMLISTING"
140>struct&nbsp;<A
141HREF="r13696.htm#V4L2-REQUESTBUFFERS"
142>v4l2_requestbuffers</A
143> reqbuf;
144
145memset (&amp;reqbuf, 0, sizeof (reqbuf));
146reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
147reqbuf.memory = V4L2_MEMORY_USERPTR;
148
149if (ioctl (fd, <A
150HREF="r13696.htm"
151><CODE
152CLASS="CONSTANT"
153>VIDIOC_REQBUFS</CODE
154></A
155>, &amp;reqbuf) == -1) {
156        if (errno == EINVAL)
157                printf ("Video capturing or user pointer streaming is not supported\n");
158        else
159                perror ("VIDIOC_REQBUFS");
160
161        exit (EXIT_FAILURE);
162}
163      </PRE
164></DIV
165><P
166>Buffer addresses and sizes are passed on the fly with the
167<A
168HREF="r12878.htm"
169><CODE
170CLASS="CONSTANT"
171>VIDIOC_QBUF</CODE
172></A
173> ioctl. Although buffers are commonly cycled,
174applications can pass different addresses and sizes at each
175<CODE
176CLASS="CONSTANT"
177>VIDIOC_QBUF</CODE
178> call. If required by the hardware the
179driver swaps memory pages within physical memory to create a
180continuous area of memory. This happens transparently to the
181application in the virtual memory subsystem of the kernel. When buffer
182pages have been swapped out to disk they are brought back and finally
183locked in physical memory for DMA.<A
184NAME="AEN5909"
185HREF="x5884.htm#FTN.AEN5909"
186><SPAN
187CLASS="footnote"
188>[1]</SPAN
189></A
190></P
191><P
192>Filled or displayed buffers are dequeued with the
193<A
194HREF="r12878.htm"
195><CODE
196CLASS="CONSTANT"
197>VIDIOC_DQBUF</CODE
198></A
199> ioctl. The driver can unlock the memory pages at any
200time between the completion of the DMA and this ioctl. The memory is
201also unlocked when <A
202HREF="r13817.htm"
203><CODE
204CLASS="CONSTANT"
205>VIDIOC_STREAMOFF</CODE
206></A
207> is called, <A
208HREF="r13696.htm"
209><CODE
210CLASS="CONSTANT"
211>VIDIOC_REQBUFS</CODE
212></A
213>, or
214when the device is closed. Applications must take care not to free
215buffers without dequeuing. For once, the buffers remain locked until
216further, wasting physical memory. Second the driver will not be
217notified when the memory is returned to the application's free list
218and subsequently reused for other purposes, possibly completing the
219requested DMA and overwriting valuable data.</P
220><P
221>For capturing applications it is customary to enqueue a
222number of empty buffers, to start capturing and enter the read loop.
223Here the application waits until a filled buffer can be dequeued, and
224re-enqueues the buffer when the data is no longer needed. Output
225applications fill and enqueue buffers, when enough buffers are stacked
226up output is started. In the write loop, when the application
227runs out of free buffers it must wait until an empty buffer can be
228dequeued and reused. Two methods exist to suspend execution of the
229application until one or more buffers can be dequeued. By default
230<CODE
231CLASS="CONSTANT"
232>VIDIOC_DQBUF</CODE
233> blocks when no buffer is in the
234outgoing queue. When the <CODE
235CLASS="CONSTANT"
236>O_NONBLOCK</CODE
237> flag was
238given to the <A
239HREF="r14090.htm"
240><CODE
241CLASS="FUNCTION"
242>open()</CODE
243></A
244> function, <CODE
245CLASS="CONSTANT"
246>VIDIOC_DQBUF</CODE
247>
248returns immediately with an <SPAN
249CLASS="ERRORCODE"
250>EAGAIN</SPAN
251> error code when no buffer is available. The
252<A
253HREF="r14390.htm"
254><CODE
255CLASS="FUNCTION"
256>select()</CODE
257></A
258> or <A
259HREF="r14169.htm"
260><CODE
261CLASS="FUNCTION"
262>poll()</CODE
263></A
264> function are always available.</P
265><P
266>To start and stop capturing or output applications call the
267<A
268HREF="r13817.htm"
269><CODE
270CLASS="CONSTANT"
271>VIDIOC_STREAMON</CODE
272></A
273> and <A
274HREF="r13817.htm"
275><CODE
276CLASS="CONSTANT"
277>VIDIOC_STREAMOFF</CODE
278></A
279> ioctl. Note
280<CODE
281CLASS="CONSTANT"
282>VIDIOC_STREAMOFF</CODE
283> removes all buffers from both
284queues and unlocks all buffers as a side effect. Since there is no
285notion of doing anything "now" on a multitasking system, if an
286application needs to synchronize with another event it should examine
287the struct&nbsp;<A
288HREF="x5953.htm#V4L2-BUFFER"
289>v4l2_buffer</A
290> <CODE
291CLASS="STRUCTFIELD"
292>timestamp</CODE
293> of captured
294buffers, or set the field before enqueuing buffers for output.</P
295><P
296>Drivers implementing user pointer I/O must
297support the <CODE
298CLASS="CONSTANT"
299>VIDIOC_REQBUFS</CODE
300>,
301<CODE
302CLASS="CONSTANT"
303>VIDIOC_QBUF</CODE
304>, <CODE
305CLASS="CONSTANT"
306>VIDIOC_DQBUF</CODE
307>,
308<CODE
309CLASS="CONSTANT"
310>VIDIOC_STREAMON</CODE
311> and
312<CODE
313CLASS="CONSTANT"
314>VIDIOC_STREAMOFF</CODE
315> ioctl, the
316<CODE
317CLASS="FUNCTION"
318>select()</CODE
319> and <CODE
320CLASS="FUNCTION"
321>poll()</CODE
322> function.<A
323NAME="AEN5945"
324HREF="x5884.htm#FTN.AEN5945"
325><SPAN
326CLASS="footnote"
327>[2]</SPAN
328></A
329></P
330></DIV
331><H3
332CLASS="FOOTNOTES"
333>Notes</H3
334><TABLE
335BORDER="0"
336CLASS="FOOTNOTES"
337WIDTH="100%"
338><TR
339><TD
340ALIGN="LEFT"
341VALIGN="TOP"
342WIDTH="5%"
343><A
344NAME="FTN.AEN5909"
345HREF="x5884.htm#AEN5909"
346><SPAN
347CLASS="footnote"
348>[1]</SPAN
349></A
350></TD
351><TD
352ALIGN="LEFT"
353VALIGN="TOP"
354WIDTH="95%"
355><P
356>We expect that frequently used buffers are typically not
357swapped out. Anyway, the process of swapping, locking or generating
358scatter-gather lists may be time consuming. The delay can be masked by
359the depth of the incoming buffer queue, and perhaps by maintaining
360caches assuming a buffer will be soon enqueued again. On the other
361hand, to optimize memory usage drivers can limit the number of buffers
362locked in advance and recycle the most recently used buffers first. Of
363course, the pages of empty buffers in the incoming queue need not be
364saved to disk. Output buffers must be saved on the incoming and
365outgoing queue because an application may share them with other
366processes.</P
367></TD
368></TR
369><TR
370><TD
371ALIGN="LEFT"
372VALIGN="TOP"
373WIDTH="5%"
374><A
375NAME="FTN.AEN5945"
376HREF="x5884.htm#AEN5945"
377><SPAN
378CLASS="footnote"
379>[2]</SPAN
380></A
381></TD
382><TD
383ALIGN="LEFT"
384VALIGN="TOP"
385WIDTH="95%"
386><P
387>At the driver level <CODE
388CLASS="FUNCTION"
389>select()</CODE
390> and
391<CODE
392CLASS="FUNCTION"
393>poll()</CODE
394> are the same, and
395<CODE
396CLASS="FUNCTION"
397>select()</CODE
398> is too important to be optional. The
399rest should be evident.</P
400></TD
401></TR
402></TABLE
403><DIV
404CLASS="NAVFOOTER"
405><HR
406ALIGN="LEFT"
407WIDTH="100%"><TABLE
408SUMMARY="Footer navigation table"
409WIDTH="100%"
410BORDER="0"
411CELLPADDING="0"
412CELLSPACING="0"
413><TR
414><TD
415WIDTH="33%"
416ALIGN="left"
417VALIGN="top"
418><A
419HREF="x5791.htm"
420ACCESSKEY="P"
421>Prev</A
422></TD
423><TD
424WIDTH="34%"
425ALIGN="center"
426VALIGN="top"
427><A
428HREF="book1.htm"
429ACCESSKEY="H"
430>Home</A
431></TD
432><TD
433WIDTH="33%"
434ALIGN="right"
435VALIGN="top"
436><A
437HREF="x5950.htm"
438ACCESSKEY="N"
439>Next</A
440></TD
441></TR
442><TR
443><TD
444WIDTH="33%"
445ALIGN="left"
446VALIGN="top"
447>Streaming I/O (Memory Mapping)</TD
448><TD
449WIDTH="34%"
450ALIGN="center"
451VALIGN="top"
452><A
453HREF="c5742.htm"
454ACCESSKEY="U"
455>Up</A
456></TD
457><TD
458WIDTH="33%"
459ALIGN="right"
460VALIGN="top"
461>Asynchronous I/O</TD
462></TR
463></TABLE
464></DIV
465></BODY
466></HTML
467>
468