user_space/doc/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <meta content="text/html;charset=UTF-8" http-equiv="Content-Type">
  <title>v4l-test: Test environment for Video For Linux Two (V4L2) API</title>
</head>
<body>
<p>
<a href="#what">What is this?</a> |
<a href="#build">How to build?</a> |
<a href="#run">How to run?</a> |
<a href="#v4l2">V4L2</a> |
<a href="#code_coverage">Code Coverage</a> |
<a href="#status">Status</a> |
<a href="results.html">Results</a> |
<a href="#others">Similar projects</a> |
<a href="#feedback">Feedback</a><br>
</p>
<hr style="width: 100%; height: 2px;">

<h1>v4l-test: Test environment for Video For Linux Two (V4L2) API</h1>
<p>
Download <a href="http://sourceforge.net/project/showfiles.php?group_id=247983">v4l-test</a>
or visit <a href="http://sourceforge.net/projects/v4l-test/">v4l-test project page</a> at
<a href="http://sourceforge.net">sourceforge.net</a> .
</p>

<h2><a name="what">What is this?</a></h2>
<p>
v4l-test is a test environment for V4L2 drivers. The V4L2 drivers
are running under Linux in kernel space. This test environment is
running in userspace and tries what normal video application would do.
It also tries some things which are supposed to test the error handling
mechanisms of a V4L2 driver. These are the "invalid test cases".
</p>
<p>
The V4L2 API only covers webcams and analog tuner cards. The digital
broadcast is out of the scope of V4L2 API so it is also out of the
scope of this test environment. See
<a href="http://linuxtv.org/docs/dvbapi/dvbapi.html">Linux DVB API</a>
for digital broadcast and
<a href="spec/x16430.htm">Chapter 6.3 Relation of V4L2 to other Linux
multimedia APIs</a> in V4L2 specification.
</p>

<h2><a name="build">How to build?</a></h2>
<p>
To build the test environment you will need a C compiler, "make" and
the CUnit development files installed. Just type "make" and the test
environment is ready.
</p>

<h2><a name="run">How to run?</a></h2>
<p>
You need to have a video device (i.e. webcam, tuner card, etc.)
connected to your system and available under /dev/video0. If you don't
have any hardware device available, you can still test the "Virtual
Video Driver". To compile this you need to compile your kernel with
CONFIG_VIDEO_VIVI=m under:
</p>
<pre>
  -&gt; Device Drivers
    -&gt; Multimedia devices
      -&gt; Video For Linux
        -&gt; Video capture adapters
          -&gt; Virtual Video Driver
</pre>
<p>
At this point you can execute v4l-test.
</p>

<h2><a name="v4l2">Video for Linux Two Specification</a></h2>
<p>
The <a href="spec/index.html">V4L2 API specification</a>
revision 0.24 is the base for this test environment. The most recent
version can be found at
<a href="http://v4l2spec.bytesex.org/spec/">http://v4l2spec.bytesex.org/spec/</a> .
</p>

<h2><a name="code_coverage">Code Coverage</a></h2>
<p>
The code coverage shows which lines of the code were executed and how
many times. The measurement results gives you a feedback about the
quality of the test cases. You can measure the code coverage of a
kernel module with the
<a href="http://ltp.sourceforge.net/coverage/gcov.php">gocv</a> and
<a href="http://ltp.sourceforge.net/coverage/lcov.php">lcov</a> softwares.
</p>

<h2><a name="status">Current status</a></h2>
<p>
Currently all test are running and evaluated automatically. This might
change in future if we want to test for example plugging and unplugging
a USB video device or ask the user if a received picture make sense or
not.
</p>
<p>
The following tables give an overview about the current state of
implemented test cases.</p>

<table border="1" cellpadding="2"
 cellspacing="0">
  <thead>
    <tr>
      <td><b>V4L API element</b></td>
      <td><b>Covered?</b></td>
      <td><b>Note</b></td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>V4L2 <a href="spec/r7626.htm">close()</a></td>
      <td>yes</td>
      <td>All</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r7667.htm">ioctl()</a></td>
      <td>yes</td>
      <td>All</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r7771.htm">VIDIOC_CROPCAP</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r7900.htm">VIDIOC_DBG_G_REGISTER</a></td>
      <td>no</td>
      <td><a href="spec/x16453.htm">Exp.</a></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r7900.htm">VIDIOC_DBG_S_REGISTER</a></td>
      <td>no</td>
      <td><a href="spec/x16453.htm">Exp.</a></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8087.htm">VIDIOC_ENCODER_CMD</a></td>
      <td>no</td>
      <td><a href="spec/x16453.htm">Exp.</a></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8087.htm">VIDIOC_TRY_ENCODER_CMD</a></td>
      <td>no</td>
      <td><a href="spec/x16453.htm">Exp.</a></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8242.htm">VIDIOC_ENUMAUDIO</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8304.htm">VIDIOC_ENUMAUDOUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8367.htm">VIDIOC_ENUM_FMT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8494.htm">VIDIOC_ENUM_FRAMESIZES</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td><a href="spec/x16453.htm">Exp.</a> Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8724.htm">VIDIOC_ENUM_FRAMEINTERVALS</a></td>
      <td>no</td>
      <td><a href="spec/x16453.htm">Exp.</a> Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r8936.htm">VIDIOC_ENUMINPUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9149.htm">VIDIOC_ENUMOUTPUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9288.htm">VIDIOC_ENUMSTD</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9539.htm">VIDIOC_G_AUDIO</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9539.htm">VIDIOC_S_AUDIO</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9688.htm">VIDIOC_G_AUDOUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9688.htm">VIDIOC_S_AUDOUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9804.htm">VIDIOC_G_CHIP_IDENT</a></td>
      <td>no</td>
      <td><a href="spec/x16453.htm">Exp.</a></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9994.htm">VIDIOC_G_CROP</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r9994.htm">VIDIOC_S_CROP</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10104.htm">VIDIOC_G_CTRL</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td><br></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10104.htm">VIDIOC_S_CTRL</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td><br></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10211.htm">VIDIOC_G_ENC_INDEX</a></td>
      <td>no</td>
      <td><a href="spec/x16453.htm">Exp.</a></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10386.htm">VIDIOC_G_EXT_CTRLS</a></td>
      <td>yes, only when STREAM_OFF, currently only zero and one item</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10386.htm">VIDIOC_S_EXT_CTRLS</a></td>
      <td>yes, only when STREAM_OFF, only with zero item</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10386.htm">VIDIOC_TRY_EXT_CTRLS</a></td>
      <td>yes, only when STREAM_OFF, only with zero item</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10595.htm">VIDIOC_G_FBUF</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10595.htm">VIDIOC_S_FBUF</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10944.htm">VIDIOC_G_FMT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10944.htm">VIDIOC_S_FMT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r10944.htm">VIDIOC_TRY_FMT</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11094.htm">VIDIOC_G_FREQUENCY</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11094.htm">VIDIOC_S_FREQUENCY</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11217.htm">VIDIOC_G_INPUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11217.htm">VIDIOC_S_INPUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11285.htm">VIDIOC_G_JPEGCOMP</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11285.htm">VIDIOC_S_JPEGCOMP</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11430.htm">VIDIOC_G_MODULATOR</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11430.htm">VIDIOC_S_MODULATOR</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11612.htm">VIDIOC_G_OUTPUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11612.htm">VIDIOC_S_OUTPUT</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11680.htm">VIDIOC_G_PARM</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11680.htm">VIDIOC_S_PARM</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11946.htm">VIDIOC_G_PRIORITY</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r11946.htm">VIDIOC_S_PRIORITY</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12051.htm">VIDIOC_G_SLICED_VBI_CAP</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12265.htm">VIDIOC_G_STD</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12265.htm">VIDIOC_S_STD</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12342.htm">VIDIOC_G_TUNER</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td><br></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12342.htm">VIDIOC_S_TUNER</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td><br></td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12784.htm">VIDIOC_LOG_STATUS</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12816.htm">VIDIOC_OVERLAY</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12878.htm">VIDIOC_QBUF</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r12878.htm">VIDIOC_DQBUF</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13022.htm">VIDIOC_QUERYBUF</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13105.htm">VIDIOC_QUERYCAP</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>All</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13317.htm">VIDIOC_QUERYCTRL</a></td>
      <td>yes, only private and user controls;
          only user controls with V4L2_CTRL_FLAG_NEXT_CTRL</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13317.htm">VIDIOC_QUERYMENU</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Enum.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13641.htm">VIDIOC_QUERYSTD</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13696.htm">VIDIOC_REQBUFS</a></td>
      <td>yes, only when STREAM_OFF</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13817.htm">VIDIOC_STREAMON</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>ioctl <a href="spec/r13817.htm">VIDIOC_STREAMOFF</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r13889.htm">mmap()</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r14037.htm">munmap()</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r14090.htm">open()</a></td>
      <td>yes, partly</td>
      <td>All</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r14169.htm">poll()</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r14264.htm">read()</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r14390.htm">select()</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
    <tr>
      <td>V4L2 <a href="spec/r14496.htm">write()</a></td>
      <td>no</td>
      <td>Opt.</td>
    </tr>
  </tbody>
</table>

<p>
All: all drivers should support<br>
Opt.: optional<br>
Enum.: enumeration, will return EINVAL for the first unknown entry<br>
Exp.: experimental, may change in future
</p>

<p>The following actions are not part of the V4L2 API but they might have
influence on the V4L2 API functions:</p>

<table border="1" cellpadding="2"
 cellspacing="0">
  <thead>
    <tr>
      <td><b>Action</b></td>
      <td><b>Covered?</b></td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Load kernel module</td>
      <td>no</td>
    </tr>
    <tr>
      <td>Unload kernel module</td>
      <td>no</td>
    </tr>
    <tr>
      <td>USB connect event (in case of USB webcams)</td>
      <td>no</td>
    </tr>
    <tr>
      <td>USB disconnect event (in case of USB webcams)</td>
      <td>no</td>
    </tr>
    <tr>
      <td>Suspend</td>
      <td>no</td>
    </tr>
    <tr>
      <td>Resume</td>
      <td>no</td>
    </tr>
    <tr>
      <td>Check for memory leak (e.g. analyze /proc/slab_allocators)</td>
      <td>no</td>
    </tr>
    <tr>
      <td>Opening /dev/video0 multiple times</td>
      <td>no</td>
    </tr>
    <tr>
      <td>Using /dev/video0 from a multi-threaded or multi-process environment paralell</td>
      <td>no</td>
    </tr>
  </tbody>
</table>


<h2><a name="others">Similar projects</a></h2>
<p>
There migth be similar projects which also tries to test the V4L2 API.
So far I could find the following:
</p>
<ul>
  <li>A <a href="http://www.linuxtv.org/wiki/index.php/V4L_Test_Suite">
  list of V4L and V4L2 test drivers and applications</a> at
  <a href="http://www.linuxtv.org/wiki/index.php/Main_Page">LinuxTV Wiki</a>
  </li>
  <li><a href="http://www.linuxowl.com/v4ltest.html">v4ltest</a><br>
  </li>
  <li>test cases in <a href="http://linuxtv.org/hg/dvb-apps/file">dvb-apps repository</a>, under /test directory
  </li>
  <li>test cases in <a href="http://linuxtv.org/hg/v4l-dvb/file">v4l-dvb repository</a>, under /v4l2-apps/test directory
  </li>
  <li>this test environment is also available under <a href="http://ltp.sourceforge.net/">Linux Test Project</a>
      (LTP), under directory testcases/kernel/device-drivers/v4l/user_space
  </li>
</ul>
<p>
Please let me know if this list misses other V4L or V4L2 test project.
</p>
<p>
The following documents and articles are useful if you are dealing with V4L2:
</p>
<ul>
  <li>
  <a href="http://v4l2spec.bytesex.org/spec/">Video for Linux Two API Specification</a>
  </li>
  <li>
  <a href="http://lwn.net/Articles/203924/">The Video4Linux2 API series</a> at
  <a href="http://lwn.net/">lwn.net</a>
  </li>
  <li><a href="http://freshmeat.net/projects/libv4l">libv4l</a>
      <a href="http://people.atrpms.net/~hdegoede/libv4l-0.5.8.tar.gz">0.5.8</a>
  </li>
  <li>Simple V4L2 video viewer: <a href="http://moinejf.free.fr/svv.c">svv.c</a>,
      writen by <a href="http://moinejf.free.fr/">Jean-Franois Moine</a>
  </li>
</ul>
<p>
For USB or V4L loopback testing:
</p>
<ul>
  <li>
  <a href="http://sourceforge.net/projects/usbip/">USB/IP</a>
  </li>
  <li>
  <a href="http://www.linux-usb.org/gadget/">Linux-USB Gadget API Framework</a>
  </li>
  <li>
  <a href="http://www.lavrsen.dk/twiki/bin/view/Motion/VideoFourLinuxLoopbackDevice">
  Video4Linux Loopback Device
  </a>
  </li>
</ul>
<p>
And what else can we read if we are looking for webcam test ideas:
</p>
<ul>
  <li>
  <a href="http://www.microsoft.com/whdc/device/media/vidcap-drvtest.mspx">
  Testing Windows Video Capture Drivers
  </a>
  </li>
  <li>
  <a href="http://www.microsoft.com/whdc/device/media/WebCam_VidTests.mspx">
  Webcam Video Fidelity Tests
  </a>
</ul>

<h2><a name="feedback">Feedbacks</a></h2>
<p>Any feedbacks, comments, ideas, etc. are welcome at the author's email address.
You can find the email address in the source package in the README file.</p>
<hr style="width: 100%; height: 2px;">
<p>Last changed:
Thu Jul 23 06:47:49 CEST 2009
</p>
<p>
  <a href="http://validator.w3.org/check?uri=referer"><img
     src="http://www.w3.org/Icons/valid-html401"
     alt="Valid HTML 4.01 Strict" height="31" width="88"></a>
  <a href="http://sourceforge.net"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=247983&type=4" width="125" height="37" alt="SourceForge.net Logo"></a>
</p>

</body>
</html>