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>Input/Output</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="PREVIOUS"
13TITLE="Reserved Format Identifiers"
14HREF="x5665.htm"><LINK
15REL="NEXT"
16TITLE="Streaming I/O (Memory Mapping)"
17HREF="x5791.htm"></HEAD
18><BODY
19CLASS="CHAPTER"
20BGCOLOR="#FFFFFF"
21TEXT="#000000"
22LINK="#0000FF"
23VLINK="#840084"
24ALINK="#0000FF"
25><DIV
26CLASS="NAVHEADER"
27><TABLE
28SUMMARY="Header navigation table"
29WIDTH="100%"
30BORDER="0"
31CELLPADDING="0"
32CELLSPACING="0"
33><TR
34><TH
35COLSPAN="3"
36ALIGN="center"
37>Video for Linux Two API Specification: Revision 0.24</TH
38></TR
39><TR
40><TD
41WIDTH="10%"
42ALIGN="left"
43VALIGN="bottom"
44><A
45HREF="x5665.htm"
46ACCESSKEY="P"
47>Prev</A
48></TD
49><TD
50WIDTH="80%"
51ALIGN="center"
52VALIGN="bottom"
53></TD
54><TD
55WIDTH="10%"
56ALIGN="right"
57VALIGN="bottom"
58><A
59HREF="x5791.htm"
60ACCESSKEY="N"
61>Next</A
62></TD
63></TR
64></TABLE
65><HR
66ALIGN="LEFT"
67WIDTH="100%"></DIV
68><DIV
69CLASS="CHAPTER"
70><H1
71><A
72NAME="IO"
73></A
74>Chapter 3. Input/Output</H1
75><DIV
76CLASS="TOC"
77><DL
78><DT
79><B
80>Table of Contents</B
81></DT
82><DT
83>3.1. <A
84HREF="c5742.htm#RW"
85>Read/Write</A
86></DT
87><DT
88>3.2. <A
89HREF="x5791.htm"
90>Streaming I/O (Memory Mapping)</A
91></DT
92><DT
93>3.3. <A
94HREF="x5884.htm"
95>Streaming I/O (User Pointers)</A
96></DT
97><DT
98>3.4. <A
99HREF="x5950.htm"
100>Asynchronous I/O</A
101></DT
102><DT
103>3.5. <A
104HREF="x5953.htm"
105>Buffers</A
106></DT
107><DT
108>3.6. <A
109HREF="x6386.htm"
110>Field Order</A
111></DT
112></DL
113></DIV
114><P
115>The V4L2 API defines several different methods to read from or
116write to a device. All drivers exchanging data with applications must
117support at least one of them.</P
118><P
119>The classic I/O method using the <CODE
120CLASS="FUNCTION"
121>read()</CODE
122>
123and <CODE
124CLASS="FUNCTION"
125>write()</CODE
126> function is automatically selected
127after opening a V4L2 device. When the driver does not support this
128method attempts to read or write will fail at any time.</P
129><P
130>Other methods must be negotiated. To select the streaming I/O
131method with memory mapped or user buffers applications call the
132<A
133HREF="r13696.htm"
134><CODE
135CLASS="CONSTANT"
136>VIDIOC_REQBUFS</CODE
137></A
138> ioctl. The asynchronous I/O method is not defined
139yet.</P
140><P
141>Video overlay can be considered another I/O method, although
142the application does not directly receive the image data. It is
143selected by initiating video overlay with the <A
144HREF="r10944.htm"
145><CODE
146CLASS="CONSTANT"
147>VIDIOC_S_FMT</CODE
148></A
149> ioctl.
150For more information see <A
151HREF="x6570.htm"
152>Section 4.2</A
153>.</P
154><P
155>Generally exactly one I/O method, including overlay, is
156associated with each file descriptor. The only exceptions are
157applications not exchanging data with a driver ("panel applications",
158see <A
159HREF="c174.htm#OPEN"
160>Section 1.1</A
161>) and drivers permitting simultaneous video capturing
162and overlay using the same file descriptor, for compatibility with V4L
163and earlier versions of V4L2.</P
164><P
165><CODE
166CLASS="CONSTANT"
167>VIDIOC_S_FMT</CODE
168> and
169<CODE
170CLASS="CONSTANT"
171>VIDIOC_REQBUFS</CODE
172> would permit this to some degree,
173but for simplicity drivers need not support switching the I/O method
174(after first switching away from read/write) other than by closing
175and reopening the device.</P
176><P
177>The following sections describe the various I/O methods in
178more detail.</P
179><DIV
180CLASS="SECTION"
181><H1
182CLASS="SECTION"
183><A
184NAME="RW"
185>3.1. Read/Write</A
186></H1
187><P
188>Input and output devices support the
189<CODE
190CLASS="FUNCTION"
191>read()</CODE
192> and <CODE
193CLASS="FUNCTION"
194>write()</CODE
195> function,
196respectively, when the <CODE
197CLASS="CONSTANT"
198>V4L2_CAP_READWRITE</CODE
199> flag in
200the <CODE
201CLASS="STRUCTFIELD"
202>capabilities</CODE
203> field of struct&nbsp;<A
204HREF="r13105.htm#V4L2-CAPABILITY"
205>v4l2_capability</A
206>
207returned by the <A
208HREF="r13105.htm"
209><CODE
210CLASS="CONSTANT"
211>VIDIOC_QUERYCAP</CODE
212></A
213> ioctl is set.</P
214><P
215>Drivers may need the CPU to copy the data, but they may also
216support DMA to or from user memory, so this I/O method is not
217necessarily less efficient than other methods merely exchanging buffer
218pointers. It is considered inferior though because no meta-information
219like frame counters or timestamps are passed. This information is
220necessary to recognize frame dropping and to synchronize with other
221data streams. However this is also the simplest I/O method, requiring
222little or no setup to exchange data. It permits command line stunts
223like this (the <SPAN
224CLASS="APPLICATION"
225>vidctrl</SPAN
226> tool is
227fictitious):</P
228><DIV
229CLASS="INFORMALEXAMPLE"
230><P
231></P
232><A
233NAME="AEN5773"
234></A
235><PRE
236CLASS="SCREEN"
237>&gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
238&gt; dd if=/dev/video of=myimage.422 bs=202752 count=1</PRE
239><P
240></P
241></DIV
242><P
243>To read from the device applications use the
244<A
245HREF="r14264.htm"
246><CODE
247CLASS="FUNCTION"
248>read()</CODE
249></A
250> function, to write the <A
251HREF="r14496.htm"
252><CODE
253CLASS="FUNCTION"
254>write()</CODE
255></A
256> function.
257Drivers must implement one I/O method if they
258exchange data with applications, but it need not be this.<A
259NAME="AEN5780"
260HREF="c5742.htm#FTN.AEN5780"
261><SPAN
262CLASS="footnote"
263>[1]</SPAN
264></A
265> When reading or writing is supported, the driver
266must also support the <A
267HREF="r14390.htm"
268><CODE
269CLASS="FUNCTION"
270>select()</CODE
271></A
272> and <A
273HREF="r14169.htm"
274><CODE
275CLASS="FUNCTION"
276>poll()</CODE
277></A
278>
279function.<A
280NAME="AEN5786"
281HREF="c5742.htm#FTN.AEN5786"
282><SPAN
283CLASS="footnote"
284>[2]</SPAN
285></A
286></P
287></DIV
288></DIV
289><H3
290CLASS="FOOTNOTES"
291>Notes</H3
292><TABLE
293BORDER="0"
294CLASS="FOOTNOTES"
295WIDTH="100%"
296><TR
297><TD
298ALIGN="LEFT"
299VALIGN="TOP"
300WIDTH="5%"
301><A
302NAME="FTN.AEN5780"
303HREF="c5742.htm#AEN5780"
304><SPAN
305CLASS="footnote"
306>[1]</SPAN
307></A
308></TD
309><TD
310ALIGN="LEFT"
311VALIGN="TOP"
312WIDTH="95%"
313><P
314>It would be desirable if applications could depend on
315drivers supporting all I/O interfaces, but as much as the complex
316memory mapping I/O can be inadequate for some devices we have no
317reason to require this interface, which is most useful for simple
318applications capturing still images.</P
319></TD
320></TR
321><TR
322><TD
323ALIGN="LEFT"
324VALIGN="TOP"
325WIDTH="5%"
326><A
327NAME="FTN.AEN5786"
328HREF="c5742.htm#AEN5786"
329><SPAN
330CLASS="footnote"
331>[2]</SPAN
332></A
333></TD
334><TD
335ALIGN="LEFT"
336VALIGN="TOP"
337WIDTH="95%"
338><P
339>At the driver level <CODE
340CLASS="FUNCTION"
341>select()</CODE
342> and
343<CODE
344CLASS="FUNCTION"
345>poll()</CODE
346> are the same, and
347<CODE
348CLASS="FUNCTION"
349>select()</CODE
350> is too important to be optional.</P
351></TD
352></TR
353></TABLE
354><DIV
355CLASS="NAVFOOTER"
356><HR
357ALIGN="LEFT"
358WIDTH="100%"><TABLE
359SUMMARY="Footer navigation table"
360WIDTH="100%"
361BORDER="0"
362CELLPADDING="0"
363CELLSPACING="0"
364><TR
365><TD
366WIDTH="33%"
367ALIGN="left"
368VALIGN="top"
369><A
370HREF="x5665.htm"
371ACCESSKEY="P"
372>Prev</A
373></TD
374><TD
375WIDTH="34%"
376ALIGN="center"
377VALIGN="top"
378><A
379HREF="book1.htm"
380ACCESSKEY="H"
381>Home</A
382></TD
383><TD
384WIDTH="33%"
385ALIGN="right"
386VALIGN="top"
387><A
388HREF="x5791.htm"
389ACCESSKEY="N"
390>Next</A
391></TD
392></TR
393><TR
394><TD
395WIDTH="33%"
396ALIGN="left"
397VALIGN="top"
398>Reserved Format Identifiers</TD
399><TD
400WIDTH="34%"
401ALIGN="center"
402VALIGN="top"
403>&nbsp;</TD
404><TD
405WIDTH="33%"
406ALIGN="right"
407VALIGN="top"
408>Streaming I/O (Memory Mapping)</TD
409></TR
410></TABLE
411></DIV
412></BODY
413></HTML
414>
415