path: root/Documentation/DocBook/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 opened. 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. Assigning
minor numbers to V4L2 devices is entirely up to the system administrator,
this is primarily intended to solve conflicts between devices.<footnote>
	  <para>Access permissions are associated with character
device special files, hence we must ensure device numbers cannot
change with the module load order. To this end minor numbers are no
longer automatically assigned by the "videodev" module as in V4L but
requested by the driver. The defaults will suffice for most people
unless two drivers compete for the same minor numbers.</para>
	</footnote> The module options to select minor numbers are named
after the device special file with a "_nr" suffix. For example "video_nr"
for <filename>/dev/video</filename> video capture devices. The number is
an offset to the base minor number associated with the device type.
<footnote>
	  <para>In earlier versions of the V4L2 API the module options
where named after the device special file with a "unit_" prefix, expressing
the minor number itself, not an offset. Rationale for this change is unknown.
Lastly the naming and semantics are just a convention among driver writers,
the point to note is that minor numbers are not supposed to be hardcoded
into drivers.</para>
	</footnote> When the driver supports multiple devices of the same
type more than one minor number can be assigned, separated by commas:
<informalexample>
	  <screen>
&gt; insmod mydriver.o 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>
alias char-major-81-0 mydriver
alias char-major-81-1 mydriver
alias char-major-81-64 mydriver              <co id="alias" />
options mydriver video_nr=0,1 radio_nr=0,1   <co id="options" />
	  </screen>
	  <calloutlist>
	    <callout arearefs="alias">
	      <para>When an application attempts to open a device
special file with major number 81 and minor number 0, 1, or 64, load
"mydriver" (and the "videodev" module it depends upon).