1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 3. Input/Output</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="v4l2spec.html" title="Part I. Video for Linux Two API Specification"><link rel="prev" href="pixfmt-reserved.html" title="Reserved Format Identifiers"><link rel="next" href="mmap.html" title="Streaming I/O (Memory Mapping)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Input/Output</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="pixfmt-reserved.html">Prev</a> </td><th width="60%" align="center">Part I. Video for Linux Two API Specification</th><td width="20%" align="right"> <a accesskey="n" href="mmap.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="io"></a>Chapter 3. Input/Output</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="io.html#rw">Read/Write</a></span></dt><dt><span class="section"><a href="mmap.html">Streaming I/O (Memory Mapping)</a></span></dt><dt><span class="section"><a href="userp.html">Streaming I/O (User Pointers)</a></span></dt><dt><span class="section"><a href="dmabuf.html">Streaming I/O (DMA buffer importing)</a></span></dt><dt><span class="section"><a href="async.html">Asynchronous I/O</a></span></dt><dt><span class="section"><a href="buffer.html">Buffers</a></span></dt><dd><dl><dt><span class="section"><a href="buffer.html#idp1104802220">Timecodes</a></span></dt></dl></dd><dt><span class="section"><a href="field-order.html">Field Order</a></span></dt></dl></div><p>The V4L2 API defines several different methods to read from or 2write to a device. All drivers exchanging data with applications must 3support at least one of them.</p><p>The classic I/O method using the <code class="function">read()</code> 4and <code class="function">write()</code> function is automatically selected 5after opening a V4L2 device. When the driver does not support this 6method attempts to read or write will fail at any time.</p><p>Other methods must be negotiated. To select the streaming I/O 7method with memory mapped or user buffers applications call the 8<a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl. The asynchronous I/O method is not defined 9yet.</p><p>Video overlay can be considered another I/O method, although 10the application does not directly receive the image data. It is 11selected by initiating video overlay with the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl. 12For more information see <a class="xref" href="overlay.html" title="Video Overlay Interface">the section called “Video Overlay Interface”</a>.</p><p>Generally exactly one I/O method, including overlay, is 13associated with each file descriptor. The only exceptions are 14applications not exchanging data with a driver ("panel applications", 15see <a class="xref" href="common.html#open" title="Opening and Closing Devices">the section called “Opening and Closing Devices”</a>) and drivers permitting simultaneous video capturing 16and overlay using the same file descriptor, for compatibility with V4L 17and earlier versions of V4L2.</p><p><code class="constant">VIDIOC_S_FMT</code> and 18<code class="constant">VIDIOC_REQBUFS</code> would permit this to some degree, 19but for simplicity drivers need not support switching the I/O method 20(after first switching away from read/write) other than by closing 21and reopening the device.</p><p>The following sections describe the various I/O methods in 22more detail.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rw"></a>Read/Write</h2></div></div></div><p>Input and output devices support the 23<code class="function">read()</code> and <code class="function">write()</code> function, 24respectively, when the <code class="constant">V4L2_CAP_READWRITE</code> flag in 25the <em class="structfield"><code>capabilities</code></em> field of struct <a class="link" href="vidioc-querycap.html#v4l2-capability" title="Table A.93. struct v4l2_capability">v4l2_capability</a> 26returned by the <a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a> ioctl is set.</p><p>Drivers may need the CPU to copy the data, but they may also 27support DMA to or from user memory, so this I/O method is not 28necessarily less efficient than other methods merely exchanging buffer 29pointers. It is considered inferior though because no meta-information 30like frame counters or timestamps are passed. This information is 31necessary to recognize frame dropping and to synchronize with other 32data streams. However this is also the simplest I/O method, requiring 33little or no setup to exchange data. It permits command line stunts 34like this (the <span class="application">vidctrl</span> tool is 35fictitious):</p><div class="informalexample"><pre class="screen"> 36> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 37> dd if=/dev/video of=myimage.422 bs=202752 count=1 38</pre></div><p>To read from the device applications use the 39<a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a> function, to write the <a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> function. 40Drivers must implement one I/O method if they 41exchange data with applications, but it need not be this.<a href="#ftn.idp1104584524" class="footnote" name="idp1104584524"><sup class="footnote">[8]</sup></a> When reading or writing is supported, the driver 42must also support the <a class="link" href="func-select.html" title="V4L2 select()"><code class="function">select()</code></a> and <a class="link" href="func-poll.html" title="V4L2 poll()"><code class="function">poll()</code></a> 43function.<a href="#ftn.idp1104586700" class="footnote" name="idp1104586700"><sup class="footnote">[9]</sup></a></p></div><div class="footnotes"><br><hr style="width:100; text-align:left;margin-left: 0"><div id="ftn.idp1104584524" class="footnote"><p><a href="#idp1104584524" class="para"><sup class="para">[8] </sup></a>It would be desirable if applications could depend on 44drivers supporting all I/O interfaces, but as much as the complex 45memory mapping I/O can be inadequate for some devices we have no 46reason to require this interface, which is most useful for simple 47applications capturing still images.</p></div><div id="ftn.idp1104586700" class="footnote"><p><a href="#idp1104586700" class="para"><sup class="para">[9] </sup></a>At the driver level <code class="function">select()</code> and 48<code class="function">poll()</code> are the same, and 49<code class="function">select()</code> is too important to be optional.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="pixfmt-reserved.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="v4l2spec.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="mmap.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Reserved Format Identifiers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Streaming I/O (Memory Mapping)</td></tr></table></div></body></html> 50