Table of Contents
The V4L2 API defines several different methods to read from or write to a device. All drivers exchanging data with applications must support at least one of them.
The classic I/O method using the read()
and write() function is automatically selected
after opening a V4L2 device. When the driver does not support this
method attempts to read or write will fail at any time.
Other methods must be negotiated. To select the streaming I/O
method with memory mapped or user buffers applications call the
VIDIOC_REQBUFS ioctl. The asynchronous I/O method is not defined
yet.
Video overlay can be considered another I/O method, although
the application does not directly receive the image data. It is
selected by initiating video overlay with the VIDIOC_S_FMT ioctl.
For more information see the section called “Video Overlay Interface”.
Generally exactly one I/O method, including overlay, is associated with each file descriptor. The only exceptions are applications not exchanging data with a driver ("panel applications", see the section called “Opening and Closing Devices”) and drivers permitting simultaneous video capturing and overlay using the same file descriptor, for compatibility with V4L and earlier versions of V4L2.
VIDIOC_S_FMT and
VIDIOC_REQBUFS would permit this to some degree,
but for simplicity drivers need not support switching the I/O method
(after first switching away from read/write) other than by closing
and reopening the device.
The following sections describe the various I/O methods in more detail.
Input and output devices support the
read() and write() function,
respectively, when the V4L2_CAP_READWRITE flag in
the capabilities field of struct v4l2_capability
returned by the VIDIOC_QUERYCAP ioctl is set.
Drivers may need the CPU to copy the data, but they may also support DMA to or from user memory, so this I/O method is not necessarily less efficient than other methods merely exchanging buffer pointers. It is considered inferior though because no meta-information like frame counters or timestamps are passed. This information is necessary to recognize frame dropping and to synchronize with other data streams. However this is also the simplest I/O method, requiring little or no setup to exchange data. It permits command line stunts like this (the vidctrl tool is fictitious):
> vidctrl /dev/video --input=0 --format=YUYV --size=352x288 > dd if=/dev/video of=myimage.422 bs=202752 count=1
To read from the device applications use the
read() function, to write the write() function.
Drivers must implement one I/O method if they
exchange data with applications, but it need not be this.[8] When reading or writing is supported, the driver
must also support the select() and poll()
function.[9]
[8] It would be desirable if applications could depend on drivers supporting all I/O interfaces, but as much as the complex memory mapping I/O can be inadequate for some devices we have no reason to require this interface, which is most useful for simple applications capturing still images.
[9] At the driver level select() and
poll() are the same, and
select() is too important to be optional.