<title>Common API Elements</title>
<para>Programming a V4L2 device consists of these
steps:</para>
<itemizedlist>
<listitem>
<para>Opening the device</para>
</listitem>
<listitem>
<para>Changing device properties, selecting a video and audio
input, video standard, picture brightness a. o.</para>
</listitem>
<listitem>
<para>Negotiating a data format</para>
</listitem>
<listitem>
<para>Negotiating an input/output method</para>
</listitem>
<listitem>
<para>The actual input/output loop</para>
</listitem>
<listitem>
<para>Closing the device</para>
</listitem>
</itemizedlist>
<para>In practice most steps are optional and can be executed out of
order. It depends on the V4L2 device type, you can read about the
details in <xref linkend="devices" />. In this chapter we will discuss
the basic concepts applicable to all devices.</para>
<section id="open">
<title>Opening and Closing Devices</title>
<section>
<title>Device Naming</title>
<para>V4L2 drivers are implemented as kernel modules, loaded
manually by the system administrator or automatically when a device is
first discovered. The driver modules plug into the "videodev" kernel
module. It provides helper functions and a common application
interface specified in this document.</para>
<para>Each driver thus loaded registers one or more device nodes
with major number 81 and a minor number between 0 and 255. Minor numbers
are allocated dynamically unless the kernel is compiled with the kernel
option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers are
allocated in ranges depending on the device node type (video, radio, etc.).</para>
<para>Many drivers support "video_nr", "radio_nr" or "vbi_nr"
module options to select specific video/radio/vbi node numbers. This allows
the user to request that the device node is named e.g. /dev/video5 instead
of leaving it to chance. When the driver supports multiple devices of the same
type more than one device node number can be assigned, separated by commas:
<informalexample>
<screen>
> modprobe mydriver video_nr=0,1 radio_nr=0,1</screen>
</informalexample></para>
<para>In <filename>/etc/modules.conf</filename> this may be
written as: <informalexample>
<screen>
options mydriver video_nr=0,1 radio_nr=0,1
</screen>
</informalexample> When no device node number is given as module
option the driver supplies a default.</para>
<para>Normally udev will create the device nodes in /dev automatically
for you. If udev is not installed, then you need to enable the
CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to correctly
relate a minor number to a device node number. I.e., you need to be certain
that minor number 5 maps to device node name video5. With this kernel option
different device types have different minor number ranges. These ranges are
listed in <xref linkend="devices" />.
</para>
<para>The creation of character special files (with
<application>mknod</application>) is a privileged operation and
devices cannot be opened by major and minor number. That means
applications cannot <emphasis>reliable</emphasis> scan for loaded or
installed drivers. The user must enter a device name, or the
application can try the conventional device names.</para>
</section>
<section id="related">
<title>Related Devices</title>
<para>Devices can support several functions. For example
video capturing, VBI capturing and radio support.</para>
<para>The V4L2 API creates different nodes for each of these functions.</para>
<para>The V4L2 API was designed with the idea that one device node could support
all functions. However, in practice this never worked: this 'feature'
was never used by applications and many drivers did not support it and if
they did it was certainly never tested. In addition, switching a device
node between different functions only works when using the streaming I/O
API, not with the read()/write() API.</para>
<para>Today each device node supports just one function.</para>
<para>Besides video input or output the hardware may also
support audio sampling or playback. If so, these