path: root/Documentation/DocBook/media/v4l/common.xml

  <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.&nbsp;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>
&gt; 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 functions are
implemented as ALSA PCM devices with optional ALSA audio mixer
devices.</para>

      <para>One problem with all these devices is that the V4L2 API
makes no provisions to find these related devices. Some really
complex devices use