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