<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><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.75.2" /><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API" /><link rel="up" href="pt01.html" title="Part I. Video for Linux Two API Specification" /><link rel="prev" href="ch02s07.html" title="Reserved Format Identifiers" /><link rel="next" href="ch03s02.html" title="Streaming I/O (Memory Mapping)" /></head><body><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="ch02s07.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="ch03s02.html">Next</a></td></tr></table><hr /></div><div class="chapter" title="Chapter 3. Input/Output"><div class="titlepage"><div><div><h2 class="title"><a id="io"></a>Chapter 3. Input/Output</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="ch03.html#rw">Read/Write</a></span></dt><dt><span class="section"><a href="ch03s02.html">Streaming I/O (Memory Mapping)</a></span></dt><dt><span class="section"><a href="ch03s03.html">Streaming I/O (User Pointers)</a></span></dt><dt><span class="section"><a href="ch03s04.html">Asynchronous I/O</a></span></dt><dt><span class="section"><a href="ch03s05.html">Buffers</a></span></dt><dd><dl><dt><span class="section"><a href="ch03s05.html#id2647246">Timecodes</a></span></dt></dl></dd><dt><span class="section"><a href="ch03s06.html">Field Order</a></span></dt></dl></div><p>The V4L2 API defines several different methods to read from or write to a device. All drivers exchanging data with applications must support at least one of them.</p><p>The classic I/O method using the <code class="function">read()</code> and <code class="function">write()</code> function is automatically selected after opening a V4L2 device. When the driver does not support this method attempts to read or write will fail at any time.</p><p>Other methods must be negotiated. To select the streaming I/O method with memory mapped or user buffers applications call the <a class="link" href="re59.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> ioctl. The asynchronous I/O method is not defined yet.</p><p>Video overlay can be considered another I/O method, although the application does not directly receive the image data. It is selected by initiating video overlay with the <a class="link" href="re41.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl. For more information see <a class="xref" href="ch04s02.html" title="Video Overlay Interface">the section called “Video Overlay Interface”</a>.</p><p>Generally exactly one I/O method, including overlay, is associated with each file descriptor. The only exceptions are applications not exchanging data with a driver ("panel applications", see <a class="xref" href="ch01.html#open" title="Opening and Closing Devices">the section called “Opening and Closing Devices”</a>) and drivers permitting simultaneous video capturing and overlay using the same file descriptor, for compatibility with V4L and earlier versions of V4L2.</p><p><code class="constant">VIDIOC_S_FMT</code> and <code class="constant">VIDIOC_REQBUFS</code> would permit this to some degree, but for simplicity drivers need not support switching the I/O method (after first switching away from read/write) other than by closing and reopening the device.</p><p>The following sections describe the various I/O methods in more detail.</p><div class="section" title="Read/Write"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="rw"></a>Read/Write</h2></div></div></div><p>Input and output devices support the <code class="function">read()</code> and <code class="function">write()</code> function, respectively, when the <code class="constant">V4L2_CAP_READWRITE</code> flag in the <em class="structfield"><code>capabilities</code></em> field of struct <a class="link" href="re56.html#v4l2-capability" title="Table A.66. struct v4l2_capability">v4l2_capability</a> returned by the <a class="link" href="re56.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 support DMA to or from user memory, so this I/O method is not necessarily less efficient than other methods merely exchanging buffer pointers. It is considered inferior though because no meta-information like frame counters or timestamps are passed. This information is necessary to recognize frame dropping and to synchronize with other data streams. However this is also the simplest I/O method, requiring little or no setup to exchange data. It permits command line stunts like this (the <span class="application">vidctrl</span> tool is fictitious):</p><div class="informalexample"><pre class="screen"> > vidctrl /dev/video --input=0 --format=YUYV --size=352x288 > dd if=/dev/video of=myimage.422 bs=202752 count=1 </pre></div><p>To read from the device applications use the <a class="link" href="re66.html" title="V4L2 read()"><code class="function">read()</code></a> function, to write the <a class="link" href="re68.html" title="V4L2 write()"><code class="function">write()</code></a> function. Drivers must implement one I/O method if they exchange data with applications, but it need not be this.<sup>[<a id="id2644873" href="#ftn.id2644873" class="footnote">12</a>]</sup> When reading or writing is supported, the driver must also support the <a class="link" href="re67.html" title="V4L2 select()"><code class="function">select()</code></a> and <a class="link" href="re65.html" title="V4L2 poll()"><code class="function">poll()</code></a> function.<sup>[<a id="id2644903" href="#ftn.id2644903" class="footnote">13</a>]</sup></p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id2644873" href="#id2644873" class="para">12</a>] </sup>It would be desirable if applications could depend on drivers supporting all I/O interfaces, but as much as the complex memory mapping I/O can be inadequate for some devices we have no reason to require this interface, which is most useful for simple applications capturing still images.</p></div><div class="footnote"><p><sup>[<a id="ftn.id2644903" href="#id2644903" class="para">13</a>] </sup>At the driver level <code class="function">select()</code> and <code class="function">poll()</code> are the same, and <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="ch02s07.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch03s02.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>