Video4linux2 Part 3: Basic IOCTL () Handling

Anybody who has spent any amount of time working through
Video4linux2 apispecification will have certainly noted that v4l2 makes heavy use ofthe
IOCTL ()Interface. perhaps more than just about any othertype of peripheral, Video hardware has a vast number of knobs to tweak. video streams have parameter parameters associated with them, and, often, there is quite a bit of processing done in the hardware.
Trying tooperate Video hardware outside of its well-supported modes can lead to poorperformance at best, and often no performance at all. so there is noalternative to exposing versions of the hardware's features and quirks to theend application.

Traditionally, video drivers have includedIOCTL ()Functions ofapproximately the same length as a Neal Stephen enson novel; while thefunctions often come to more satisfying conclusions than the novels, theydo tend to drag a lot in the middle. So
V4l2 API was changed in2.6.18; the interminableIOCTL ()Function has been replaced with aLarge set of callbacks which implement the individual
IOCTL ()Functions. There are, in fact, 79 of them in 2.6.19-rc3. Fortunately, most drivers need not implement all-or even most-of the possiblecallbacks.

What has really happened is that the longIOCTL ()Function hasbeen moved
Drivers/Media/Video/videodev. c. This Code handlesthe movement of data between user and kernel space and dispatchesindividual
IOCTL ()Callto the driver. To use it, the driverneed only useVideo_ioctl2 ()As its
IOCTL ()Method inVideo_deviceStructure. Actually, most drivers shocould be able touse it
Unlocked_ioctl ()Instead; the locking within thevideo4linux2 layer can handle it, and drivers shoshould have proper locking inplace as well.

The first callback your driver is likely to implement is:

 

    int (*vidioc_querycap)(struct file *file, void *priv,                            struct v4l2_capability *cap);

This function handlesVidioc_querycap IOCTL (), Whichasks a simple "who are you and what can you do? "Question. Implementing itis mandatory for v4l2 drivers. In this function, as with all other v4l2callbacks,
PrivArgument is the contentsFile-> private_dataField; the usual practice is to point it atthe driver's internal structure representing the device
Open ()Time.

The driver shocould respond by filling in thestructureCapAnd returning the usual "zero or negative errorcode" value. On successful return, the v4l2 layer will take care ofcopying the response back into user space.

TheV4l2_capabilityStructure (defined in<Linux/videodev2.h>) Looks like this:

 

    struct v4l2_capability    {__u8driver[16];/* i.e. "bttv" */__u8card[32];/* i.e. "Hauppauge WinTV" */__u8bus_info[32];/* "PCI:" + pci_name(pci_dev) */__u32   version;        /* should use KERNEL_VERSION() */__u32capabilities;/* Device capabilities */__u32reserved[4];    };

TheDriverField shoshould be filled in with the name of the devicedriver, while
CardField shoshould have a description of thehardware behind this particle device. Not all drivers bother withBus_infoField; those that do usually use something like:

 

    sprintf(cap->bus_info, "PCI:%s", pci_name(&my_dev));

TheVersionField holds a version number for the driver.CapabilitiesField is a bitmask describing various things that thedriver can do:

 

• V4l2_cap_video_capture: The device can capture video data.
• V4l2_cap_video_output: The device can perform video output.
• V4l2_cap_video_overlay: It can do video overlay onto the frame buffer.
• V4l2_cap_vbi_capture: It can capture raw video blanking interval data.
• V4l2_cap_vbi_output: It can do raw VBI output.
• V4l2_cap_sliced_vbi_capture: It can do sliced VBI capture.
• V4l2_cap_sliced_vbi_output: It can do sliced VBI output.
• V4l2_cap_rds_capture: It can capture Radio Data System (RDS) data.
• V4l2_cap_tuner: It has a computer-controllable tuner.
• V4l2_cap_audio: It can capture audio data.
• V4l2_cap_radio: It is a radio device.
• V4l2_cap_readwrite: It supportsRead ()And/orWrite ()System CILS; very few devices will support both. It makes little sense to write to a camera, normally.
• V4l2_cap_asyncio: It supports asynchronous I/O. Unfortunately, the v4l2 layer as a whole does not yet support asynchronous I/O, so this capability is not meaningful.
• V4l2_cap_streaming: It supportsIOCTL ()-Controlled streaming I/O.

The final field (Reserved) Shoshould be left alone. The v4l2specification requires that
ReservedBe set to zero, but, sinceVideo_ioctl2 ()Sets the entire structure to zero, That Is nicelytaken care.

A fairly typical implementation can be found in the "Vivi" Driver:

 

    static int vidioc_querycap (struct file *file, void  *priv,struct v4l2_capability *cap)    {strcpy(cap->driver, "vivi");strcpy(cap->card, "vivi");cap->version = VIVI_VERSION;cap->capabilities =V4L2_CAP_VIDEO_CAPTURE |V4L2_CAP_STREAMING     |V4L2_CAP_READWRITE;return 0;    }

Given the presence of this call, one wowould procedure CT that applications woulduse it and avoid asking specific devices to perform functions that they arenot capable. in your editor's limited experience, however, applicationstend not to pay much attention
TheVidioc_querycapCall.

Another callback, which is optional and not often implemented, is:

 

    int (*vidioc_log_status) (struct file *file, void *priv);

This function, implementingVidioc_log_status, Is intended to be adebugging aid for video application writers. When called, it shoshould printinformation describing the current status of the driver and its hardware. This information shoshould be sufficiently
Verbose to help a confusedapplication developer figure out why the video display is coming up blank. Your editor wocould also recommend, however, that it be moderated with a callto
Printk_ratelimit ()To keep it from being used to slow thesystem and fill the logfiles with junk.

The next installment will start in on the remaining 77 Callbacks. inparticipant ular, we will begin to look at the long process of negotiating a setof operating modes with the hardware.