Video4Linux loopback API

Author: Jeroen Vreeken (pe1rxq@amsat.org)
Version: 0.90
Date: 31-01-2001

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:

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