The Video4Linux2 API: an introduction

Your editor has recently had the opportunity to write a Linux driver for acamera device - the camera which will be packaged with the One Laptop PerChild system, in particular. This driver works with the internal kernelAPI designed for such purposes: the Video4Linux2 API. In the process ofwriting this code, your editor made the shocking discovery that, in fact,this API is not particularly well documented - though the user-space sideis, instead,quitewell documented indeed. In an attempt to remedy the situation somewhat, LWN will, over the coming months, publish a series ofarticles describing how to write drivers for the V4L2 interface.

V4L2 has a long history - the first gleam came into Bill Dirks's eye backaround August of 1998. Development proceeded for years, and the V4L2 APIwas finally merged into the mainline in November, 2002, when2.5.46 was released. To thisday, however, quite a few Linux drivers do not support the newer API; theconversion process is an ongoing task. Meanwhile, the V4L2 API continuesto evolve, with some major changes being made in 2.6.18. Applicationswhich work with V4L2 remain relatively scarce.

V4L2 is designed to support a wide variety of devices, only some of whichare truly "video" in nature:

 

• The video capture interface grabs video data from a tuner or camera device. For many, video capture will be the primary application for V4L2. Since your editor's experience is strongest in this area, this series will tend to emphasize the capture API, but there is more to V4L2 than that.

   

• The video output interface allows applications to drive peripherals which can provide video images - perhaps in the form of a television signal - outside of the computer.

   

• A variant of the capture interface can be found in the video overlay interface, whose job is to facilitate the direct display of video data from a capture device. Video data moves directly from the capture device to the display, without passing through the system's CPU.

   

• The VBI interfaces provide access to data transmitted during the video blanking interval. There are two of them, the "raw" and "sliced" interfaces, which differ in the amount of processing of the VBI data performed in hardware.

   

• The radio interface provides access to audio streams from AM and FM tuner devices.

Other types of devices are possible. The V4L2 API has some stubs for"codec" and "effect" devices, both of which perform transformations onvideo data streams. Those areas have not yet been completely specified,however, much less implemented. There are also the "teletext" and "radiodata system" interfaces currently implemented in the older V4L1 API; thosehave not been moved to V4L2 and there do not appear to be any immediateplans to do so.

Video devices differ from many others in the vast number of ways in whichthey can be configured. As a result, much of a V4L2 driver implements codewhich enables applications to discover a given device's capabilities and toconfigure that device to operate in the desired manner. The V4L2 APIdefines several dozen callbacks for the configuration of parameters liketuner frequencies, windowing and cropping, frame rates, video compression,image parameters (brightness, contrast, ...), video standards, videoformats, etc. Much of this series will be devoted to looking at how thisconfiguration process happens.

Then, there is the small task of actually performing I/O at video rates inan efficient manner. The V4L2 API defines three different ways of movingvideo data between user space and the peripheral, some of which can be onthe complex side. Separate articles will look at video I/O and thevideo-buf layer which has been provided to handle common tasks.

Subsequent articles will appear every few weeks, and will be added to thelist below:

 

• Part 2: registration and open()
• Part 3: Basic ioctl() handling
• Part 4: Inputs and Outputs
• Part 5a: Colors andformats
• Part 5b: Format negotiation
• Part 6a: Basic frame I/O
• Part 6b: Streaming I/O
• Part 7: Controls