What is this? | How to build? | How to run? | V4L2 | Code Coverage | Status | Results | Similar projects | Feedback

# v4l-test: Test environment for Video For Linux Two (V4L2) API

Download v4l-test or visit v4l-test project page at sourceforge.net .

## What is this?

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".

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 Linux DVB API for digital broadcast and Chapter 6.3 Relation of V4L2 to other Linux multimedia APIs in V4L2 specification.

## How to build?

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.

## How to run?

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:

      -> Device Drivers
        -> Multimedia devices
          -> Video For Linux
            -> Video capture adapters
              -> Virtual Video Driver

At this point you can execute v4l-test.

## Video for Linux Two Specification

The V4L2 API specification revision 0.24 is the base for this test environment. The most recent version can be found at http://v4l2spec.bytesex.org/spec/ .

## Code Coverage

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 gocv and lcov softwares.

## Current status

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.

The following tables give an overview about the current state of implemented test cases.

V4L API element | Covered? | Note
V4L2 close() | yes | All
V4L2 ioctl() | yes | All
ioctl VIDIOC_CROPCAP | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_DBG_G_REGISTER | no | Exp.
ioctl VIDIOC_DBG_S_REGISTER | no | Exp.
ioctl VIDIOC_ENCODER_CMD | no | Exp.
ioctl VIDIOC_TRY_ENCODER_CMD | no | Exp.
ioctl VIDIOC_ENUMAUDIO | yes, only when STREAM_OFF | Enum.
ioctl VIDIOC_ENUMAUDOUT | yes, only when STREAM_OFF | Enum.
ioctl VIDIOC_ENUM_FMT | yes, only when STREAM_OFF | Enum.
ioctl VIDIOC_ENUM_FRAMESIZES | yes, only when STREAM_OFF | Exp. Enum.
ioctl VIDIOC_ENUM_FRAMEINTERVALS | no | Exp. Enum.
ioctl VIDIOC_ENUMINPUT | yes, only when STREAM_OFF | Enum.
ioctl VIDIOC_ENUMOUTPUT | yes, only when STREAM_OFF | Enum.
ioctl VIDIOC_ENUMSTD | yes, only when STREAM_OFF | Enum.
ioctl VIDIOC_G_AUDIO | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_AUDIO | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_AUDOUT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_AUDOUT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_CHIP_IDENT | no | Exp.
ioctl VIDIOC_G_CROP | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_CROP | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_CTRL | yes, only when STREAM_OFF |
ioctl VIDIOC_S_CTRL | yes, only when STREAM_OFF |
ioctl VIDIOC_G_ENC_INDEX | no | Exp.
ioctl VIDIOC_G_EXT_CTRLS | yes, only when STREAM_OFF, currently only zero and one item | Opt.
ioctl VIDIOC_S_EXT_CTRLS | yes, only when STREAM_OFF, only with zero item | Opt.
ioctl VIDIOC_TRY_EXT_CTRLS | yes, only when STREAM_OFF, only with zero item | Opt.
ioctl VIDIOC_G_FBUF | no | Opt.
ioctl VIDIOC_S_FBUF | no | Opt.
ioctl VIDIOC_G_FMT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_FMT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_TRY_FMT | no | Opt.
ioctl VIDIOC_G_FREQUENCY | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_FREQUENCY | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_INPUT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_INPUT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_JPEGCOMP | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_JPEGCOMP | no | Opt.
ioctl VIDIOC_G_MODULATOR | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_MODULATOR | no | Opt.
ioctl VIDIOC_G_OUTPUT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_OUTPUT | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_PARM | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_PARM | no | Opt.
ioctl VIDIOC_G_PRIORITY | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_PRIORITY | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_SLICED_VBI_CAP | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_STD | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_S_STD | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_G_TUNER | yes, only when STREAM_OFF |
ioctl VIDIOC_S_TUNER | yes, only when STREAM_OFF |
ioctl VIDIOC_LOG_STATUS | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_OVERLAY | no | Opt.
ioctl VIDIOC_QBUF | no | Opt.
ioctl VIDIOC_DQBUF | no | Opt.
ioctl VIDIOC_QUERYBUF | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_QUERYCAP | yes, only when STREAM_OFF | All
ioctl VIDIOC_QUERYCTRL | yes, only private and user controls; only user controls with V4L2_CTRL_FLAG_NEXT_CTRL | Enum.
ioctl VIDIOC_QUERYMENU | yes, only when STREAM_OFF | Enum.
ioctl VIDIOC_QUERYSTD | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_REQBUFS | yes, only when STREAM_OFF | Opt.
ioctl VIDIOC_STREAMON | no | Opt.
ioctl VIDIOC_STREAMOFF | no | Opt.
V4L2 mmap() | no | Opt.
V4L2 munmap() | no | Opt.
V4L2 open() | yes, partly | All
V4L2 poll() | no | Opt.
V4L2 read() | no | Opt.
V4L2 select() | no | Opt.
V4L2 write() | no | Opt.

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

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

Action | Covered?
Load kernel module | no
Unload kernel module | no
USB connect event (in case of USB webcams) | no
USB disconnect event (in case of USB webcams) | no
Suspend | no
Resume | no
Check for memory leak (e.g. analyze /proc/slab_allocators) | no
Opening /dev/video0 multiple times | no
Using /dev/video0 from a multi-threaded or multi-process environment paralell | no

## Similar projects

There migth be similar projects which also tries to test the V4L2 API. So far I could find the following:

- A list of V4L and V4L2 test drivers and applications at LinuxTV Wiki
- v4ltest
- test cases in dvb-apps repository, under /test directory
- test cases in v4l-dvb repository, under /v4l2-apps/test directory
- this test environment is also available under Linux Test Project (LTP), under directory testcases/kernel/device-drivers/v4l/user_space

Please let me know if this list misses other V4L or V4L2 test project.

The following documents and articles are useful if you are dealing with V4L2:

- Video for Linux Two API Specification
- The Video4Linux2 API series at lwn.net
- libv4l 0.5.8
- Simple V4L2 video viewer: svv.c, writen by Jean-François Moine

For USB or V4L loopback testing:

- USB/IP
- Linux-USB Gadget API Framework
- Video4Linux Loopback Device

And what else can we read if we are looking for webcam test ideas:

- Testing Windows Video Capture Drivers
- Webcam Video Fidelity Tests

## Feedbacks

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.

Last changed: Thu Jul 23 06:47:49 CEST 2009