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 <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>> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 238> 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> </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