1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 1. Common API Elements</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="v4l2spec.html" title="Part I. Video for Linux Two API Specification"><link rel="next" href="querycap.html" title="Querying Capabilities"></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 1. Common API Elements</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="v4l2spec.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="querycap.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="common"></a>Chapter 1. Common API Elements</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="common.html#open">Opening and Closing Devices</a></span></dt><dd><dl><dt><span class="section"><a href="common.html#idp1096767692">Device Naming</a></span></dt><dt><span class="section"><a href="common.html#related">Related Devices</a></span></dt><dt><span class="section"><a href="common.html#idp1096777404">Multiple Opens</a></span></dt><dt><span class="section"><a href="common.html#idp1096789052">Shared Data Streams</a></span></dt><dt><span class="section"><a href="common.html#idp1096789860">Functions</a></span></dt></dl></dd><dt><span class="section"><a href="querycap.html">Querying Capabilities</a></span></dt><dt><span class="section"><a href="app-pri.html">Application Priority</a></span></dt><dt><span class="section"><a href="video.html">Video Inputs and Outputs</a></span></dt><dt><span class="section"><a href="audio.html">Audio Inputs and Outputs</a></span></dt><dt><span class="section"><a href="tuner.html">Tuners and Modulators</a></span></dt><dd><dl><dt><span class="section"><a href="tuner.html#idp1096834708">Tuners</a></span></dt><dt><span class="section"><a href="tuner.html#idp1096841868">Modulators</a></span></dt><dt><span class="section"><a href="tuner.html#idp1096849292">Radio Frequency</a></span></dt></dl></dd><dt><span class="section"><a href="standard.html">Video Standards</a></span></dt><dt><span class="section"><a href="dv-timings.html">Digital Video (DV) Timings</a></span></dt><dt><span class="section"><a href="control.html">User Controls</a></span></dt><dt><span class="section"><a href="extended-controls.html">Extended Controls</a></span></dt><dd><dl><dt><span class="section"><a href="extended-controls.html#idp1097023452">Introduction</a></span></dt><dt><span class="section"><a href="extended-controls.html#idp1097025916">The Extended Control API</a></span></dt><dt><span class="section"><a href="extended-controls.html#idp1097037444">Enumerating Extended Controls</a></span></dt><dt><span class="section"><a href="extended-controls.html#idp1096896148">Creating Control Panels</a></span></dt><dt><span class="section"><a href="extended-controls.html#mpeg-controls">Codec Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#camera-controls">Camera Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#fm-tx-controls">FM Transmitter Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#flash-controls">Flash Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#jpeg-controls">JPEG Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#image-source-controls">Image Source Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#image-process-controls">Image Process Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#dv-controls">Digital Video Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#fm-rx-controls">FM Receiver Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#detect-controls">Detect Control Reference</a></span></dt><dt><span class="section"><a href="extended-controls.html#rf-tuner-controls">RF Tuner Control Reference</a></span></dt></dl></dd><dt><span class="section"><a href="format.html">Data Formats</a></span></dt><dd><dl><dt><span class="section"><a href="format.html#idp1098923212">Data Format Negotiation</a></span></dt><dt><span class="section"><a href="format.html#idp1098942900">Image Format Enumeration</a></span></dt></dl></dd><dt><span class="section"><a href="planar-apis.html">Single- and multi-planar APIs</a></span></dt><dd><dl><dt><span class="section"><a href="planar-apis.html#idp1098952028">Multi-planar formats</a></span></dt><dt><span class="section"><a href="planar-apis.html#idp1098952868">Calls that distinguish between single and multi-planar APIs</a></span></dt></dl></dd><dt><span class="section"><a href="crop.html">Image Cropping, Insertion and Scaling</a></span></dt><dd><dl><dt><span class="section"><a href="crop.html#idp1098969740">Cropping Structures</a></span></dt><dt><span class="section"><a href="crop.html#idp1098993076">Scaling Adjustments</a></span></dt><dt><span class="section"><a href="crop.html#idp1098980540">Examples</a></span></dt></dl></dd><dt><span class="section"><a href="selection-api.html">Experimental API for cropping, composing and scaling</a></span></dt><dd><dl><dt><span class="section"><a href="selection-api.html#idp1099015196">Introduction</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099060620">Selection targets</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099063868">Configuration</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099082516">Comparison with old cropping API</a></span></dt><dt><span class="section"><a href="selection-api.html#idp1099087124">Examples</a></span></dt></dl></dd><dt><span class="section"><a href="streaming-par.html">Streaming Parameters</a></span></dt></dl></div><p>Programming a V4L2 device consists of these 2steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Opening the device</p></li><li class="listitem"><p>Changing device properties, selecting a video and audio 3input, video standard, picture brightness a. o.</p></li><li class="listitem"><p>Negotiating a data format</p></li><li class="listitem"><p>Negotiating an input/output method</p></li><li class="listitem"><p>The actual input/output loop</p></li><li class="listitem"><p>Closing the device</p></li></ul></div><p>In practice most steps are optional and can be executed out of 4order. It depends on the V4L2 device type, you can read about the 5details in <a class="xref" href="devices.html" title="Chapter 4. Interfaces">Chapter 4, <i>Interfaces</i></a>. In this chapter we will discuss 6the basic concepts applicable to all devices.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="open"></a>Opening and Closing Devices</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="common.html#idp1096767692">Device Naming</a></span></dt><dt><span class="section"><a href="common.html#related">Related Devices</a></span></dt><dt><span class="section"><a href="common.html#idp1096777404">Multiple Opens</a></span></dt><dt><span class="section"><a href="common.html#idp1096789052">Shared Data Streams</a></span></dt><dt><span class="section"><a href="common.html#idp1096789860">Functions</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1096767692"></a>Device Naming</h3></div></div></div><p>V4L2 drivers are implemented as kernel modules, loaded 7manually by the system administrator or automatically when a device is 8first discovered. The driver modules plug into the "videodev" kernel 9module. It provides helper functions and a common application 10interface specified in this document.</p><p>Each driver thus loaded registers one or more device nodes 11with major number 81 and a minor number between 0 and 255. Minor numbers 12are allocated dynamically unless the kernel is compiled with the kernel 13option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are 14allocated in ranges depending on the device node type (video, radio, etc.).</p><p>Many drivers support "video_nr", "radio_nr" or "vbi_nr" 15module options to select specific video/radio/vbi node numbers. This allows 16the user to request that the device node is named e.g. /dev/video5 instead 17of leaving it to chance. When the driver supports multiple devices of the same 18type more than one device node number can be assigned, separated by commas: 19 </p><div class="informalexample"><pre class="screen"> 20> modprobe mydriver video_nr=0,1 radio_nr=0,1</pre></div><p>In <code class="filename">/etc/modules.conf</code> this may be 21written as: </p><div class="informalexample"><pre class="screen"> 22options mydriver video_nr=0,1 radio_nr=0,1 23 </pre></div><p> When no device node number is given as module 24option the driver supplies a default.</p><p>Normally udev will create the device nodes in /dev automatically 25for you. If udev is not installed, then you need to enable the 26CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly 27relate a minor number to a device node number. I.e., you need to be certain 28that minor number 5 maps to device node name video5. With this kernel option 29different device types have different minor number ranges. These ranges are 30listed in <a class="xref" href="devices.html" title="Chapter 4. Interfaces">Chapter 4, <i>Interfaces</i></a>. 31</p><p>The creation of character special files (with 32<span class="application">mknod</span>) is a privileged operation and 33devices cannot be opened by major and minor number. That means 34applications cannot <span class="emphasis"><em>reliable</em></span> scan for loaded or 35installed drivers. The user must enter a device name, or the 36application can try the conventional device names.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="related"></a>Related Devices</h3></div></div></div><p>Devices can support several functions. For example 37video capturing, VBI capturing and radio support.</p><p>The V4L2 API creates different nodes for each of these functions.</p><p>The V4L2 API was designed with the idea that one device node could support 38all functions. However, in practice this never worked: this 'feature' 39was never used by applications and many drivers did not support it and if 40they did it was certainly never tested. In addition, switching a device 41node between different functions only works when using the streaming I/O 42API, not with the read()/write() API.</p><p>Today each device node supports just one function.</p><p>Besides video input or output the hardware may also 43support audio sampling or playback. If so, these functions are 44implemented as ALSA PCM devices with optional ALSA audio mixer 45devices.</p><p>One problem with all these devices is that the V4L2 API 46makes no provisions to find these related devices. Some really 47complex devices use the Media Controller (see <a class="xref" href="media_controller.html" title="Chapter 18. Media Controller">Chapter 18, <i>Media Controller</i></a>) 48which can be used for this purpose. But most drivers do not use it, 49and while some code exists that uses sysfs to discover related devices 50(see libmedia_dev in the <a class="ulink" href="http://git.linuxtv.org/cgit.cgi/v4l-utils.git/" target="_top">v4l-utils</a> 51git repository), there is no library yet that can provide a single API towards 52both Media Controller-based devices and devices that do not use the Media Controller. 53If you want to work on this please write to the linux-media mailing list: <a class="ulink" href="http://www.linuxtv.org/lists.php" target="_top">http://www.linuxtv.org/lists.php</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1096777404"></a>Multiple Opens</h3></div></div></div><p>V4L2 devices can be opened more than once.<a href="#ftn.idp1096778508" class="footnote" name="idp1096778508"><sup class="footnote">[1]</sup></a> 54When this is supported by the driver, users can for example start a 55"panel" application to change controls like brightness or audio 56volume, while another application captures video and audio. In other words, panel 57applications are comparable to an ALSA audio mixer application. 58Just opening a V4L2 device should not change the state of the device.<a href="#ftn.idp1096781020" class="footnote" name="idp1096781020"><sup class="footnote">[2]</sup></a></p><p>Once an application has allocated the memory buffers needed for 59streaming data (by calling the <a class="link" href="vidioc-reqbufs.html" title="ioctl VIDIOC_REQBUFS"><code class="constant">VIDIOC_REQBUFS</code></a> or <a class="link" href="vidioc-create-bufs.html" title="ioctl VIDIOC_CREATE_BUFS"><code class="constant">VIDIOC_CREATE_BUFS</code></a> ioctls, 60or implicitly by calling the <a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a> or <a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> functions) that 61application (filehandle) becomes the owner of the device. It is no longer 62allowed to make changes that would affect the buffer sizes (e.g. by calling 63the <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) and other applications are no longer allowed to allocate 64buffers or start or stop streaming. The <span class="errorcode">EBUSY</span> error code will be returned instead.</p><p>Merely opening a V4L2 device does not grant exclusive 65access.<a href="#ftn.idp1096786884" class="footnote" name="idp1096786884"><sup class="footnote">[3]</sup></a> Initiating data exchange however assigns the right 66to read or write the requested type of data, and to change related 67properties, to this file descriptor. Applications can request 68additional access privileges using the priority mechanism described in 69<a class="xref" href="app-pri.html" title="Application Priority">the section called “Application Priority”</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1096789052"></a>Shared Data Streams</h3></div></div></div><p>V4L2 drivers should not support multiple applications 70reading or writing the same data stream on a device by copying 71buffers, time multiplexing or similar means. This is better handled by 72a proxy application in user space.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1096789860"></a>Functions</h3></div></div></div><p>To open and close V4L2 devices applications use the 73<a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a> and <a class="link" href="func-close.html" title="V4L2 close()"><code class="function">close()</code></a> function, respectively. Devices are 74programmed using the <a class="link" href="func-ioctl.html" title="V4L2 ioctl()"><code class="function">ioctl()</code></a> function as explained in the 75following sections.</p></div></div><div class="footnotes"><br><hr style="width:100; text-align:left;margin-left: 0"><div id="ftn.idp1096778508" class="footnote"><p><a href="#idp1096778508" class="para"><sup class="para">[1] </sup></a> 76There are still some old and obscure drivers that have not been updated to 77allow for multiple opens. This implies that for such drivers <a class="link" href="func-open.html" title="V4L2 open()"><code class="function">open()</code></a> can 78return an <span class="errorcode">EBUSY</span> error code when the device is already in use.</p></div><div id="ftn.idp1096781020" class="footnote"><p><a href="#idp1096781020" class="para"><sup class="para">[2] </sup></a>Unfortunately, opening a radio device often switches the state of the 79device to radio mode in many drivers. This behavior should be fixed eventually 80as it violates the V4L2 specification.</p></div><div id="ftn.idp1096786884" class="footnote"><p><a href="#idp1096786884" class="para"><sup class="para">[3] </sup></a>Drivers could recognize the 81<code class="constant">O_EXCL</code> open flag. Presently this is not required, 82so applications cannot know if it really works.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="v4l2spec.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="querycap.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part I. Video for Linux Two API Specification </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Querying Capabilities</td></tr></table></div></body></html> 83