<?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.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><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 id="io"></a>Chapter 3. Input/Output</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></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#idm140470022731280">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
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="vidioc-reqbufs.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="vidioc-g-fmt.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="overlay.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="common.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"><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="vidioc-querycap.html#v4l2-capability" title="Table A.88. struct v4l2_capability">v4l2_capability</a>
returned 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
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="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.
Drivers must implement one I/O method if they
exchange data with applications, but it need not be this.<a href="#ftn.idm140470023103872" class="footnote" id="idm140470023103872"><sup class="footnote">[12]</sup></a> When reading or writing is supported, the driver
must 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>
function.<a href="#ftn.idm140470023101104" class="footnote" id="idm140470023101104"><sup class="footnote">[13]</sup></a></p></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div id="ftn.idm140470023103872" class="footnote"><p><a href="#idm140470023103872" class="para"><sup class="para">[12] </sup></a>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 id="ftn.idm140470023101104" class="footnote"><p><a href="#idm140470023101104" class="para"><sup class="para">[13] </sup></a>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="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>
distrib
>
Fedora
>
18
>
x86_64
>
media
>
updates
>
by-pkgid
>
1a595394b241504ff370a8d12ebfcea7
>
files
>
3726
