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