Video4Linux Loopback Device API

Original Author: JeroenVreeken Written for Version: 0.90 Date: 31-01-2001

Translated to TWiki -- KennethLavrsen - 05 Oct 2004

Introduction:

This document describes the API for the Video4Linux loopback driver. The driver implements a video pipe using two video4linux devices. The first device is used by the program supplying the data, from now on this program will be refered to with pusher.

The second device acts as if it were a normall video4linux device, it should be usable by any application that honours the video4linux specifications. This application will from now on be refered to as client.

The calls and ioctls mentioned in this document refer to those as described in the Video4Linux API.

The loopback device has two operating modes:

• A simple one-copy mode in which pusher specifies the size of the images and the used palette and uses write to push its images to the pipe.
  This mode is mostly for feeding fixed size images without any knowledge about client.

• A zero-copy mode in which pusher regularly polls the device if client does an ioctl.
  In this mode pusher has almost complete control over the devices behaviour and it will be mainly used to implement complex multiple tuner/channel/size configurations. With this mode it should be possible to use the Xvideo extensions as normal video4linux capture devices.

Locating a free pipe

In order to find an unused pipe pusher will have to scan the contents of /proc/video/vloopback/

Each pipe will have its own entry in the form of vloopback0 to vloopbackN, N being the total number of available pipes-1.

There will also be a general vloopbacks file which will contain information on all entries.

Each of these files will have references to the input and output video device and will also indicate if either of them is currently in use.

Once pusher has found a free pipe it can claim it by simply opening the input device.

One-copy mode

In this mode pusher only has to provide images using the write() call, the driver will handle the communication with client or will drop the images if the output is unused. To client the device will closely resemble a webcam driver.

In order to use it pusher will open the input device. Before writing it will first have to set the palette it is going to use by calling VIDIOCSPICT, and the size by calling VIDIOCSWIN. After this it can call write() for each frame it wants to send to the pipe.

When there is no application using the device the driver will simply drop the frames which will result in a 'no-copy' situation while writing to an unused pipe.

Note: when client is using read() instead of mmap() the driver will actually use a double copy.

Zero-copy mode

In this mode the driver will forward nearly all ioctls to pusher.

To initiate this mode pusher will have to call mmap() with the size of the requested buffer. The driver will allocate memory for this buffer and pusher will gain access to it.

Note: as the allocated memory might be in use by client, pusher is NOT allowed to touch it under any circumstances with the only exception being between VIDIOCMCAPTURE and VIDIOCSYNC.

Handling ioctls

When client has issued an ioctl pusher will receive a SIGIO signal. Pusher may check to see if it is comming from vloopback by calling poll() first. It then has to respond by calling read() with a large enough buffer for the largest possible ioctl data structure plus sizeof(unsigned long int). (The largest ioctl data structure is 280 bytes in linux kernel 2.4.0-test10pre1, a buffer of 1024 bytes is recommended.)

The first bytes of this buffer will be the ioctl number. This number is an unsigned long int, the remaining data is the data supplied by client. Pusher will now have to handle this ioctl.

If it is an ioctl requesting data pusher will answer it by calling the ioctl with the requested data.

If it is an ioctl setting data pusher will call the ioctl with the exact same data to accept it.

Handling read

Pusher will not need to handle any read requests because the kernel module will fake an mmap and sync call for it.

Starting and stopping capture

The first time VIDIOCMCAPTURE is called pusher should initialize capture and start capturing of the requested frames into the mmapped buffer.

When client closes its device an ioctl 0 will be send with no data, pusher will tell the hardware to stop.

-- KennethLavrsen - 05 Oct 2004