Soon after the V4L API was added to the kernel it was criticised as too inflexible. In August 1998 Bill Dirks proposed a number of improvements and began to work on documentation, example drivers and applications. With the help of other volunteers this eventually became the V4L2 API, not just an extension but a replacement for the V4L API. However it took another four years and two stable kernel releases until the new API was finally accepted for inclusion into the kernel in its present form.
1998-08-20: First version.
select() function was introduced.
1998-09-10: New video standard interface.
was replaced by the otherwise meaningless
open() flag, and the aliases
O_NOIO were defined. Applications can set this
flag if they intend to access controls only, as opposed to capture
applications which need exclusive access. The
VIDEO_STD_XXX identifiers are now ordinals
instead of flags, and the
helper function takes id and transmission arguments.
1998-09-28: Revamped video standard. Made video controls individually enumerable.
id field was
removed from struct
video_standard and the
color subcarrier fields were renamed. The
VIDIOC_QUERYSTD ioctl was
first draft of the Codec API was released.
1998-11-08: Many minor changes. Most symbols have been renamed. Some material changes to struct v4l2_capability.
1998-11-12: The read/write directon of some ioctls was misdefined.
V4L2_PIX_FMT_RGB32 changed to
V4L2_PIX_FMT_BGR32. Audio controls are now
accessible with the
VIDIOC_S_CTRL ioctls under
names starting with
V4L2_MAJOR define was removed from
videodev.h since it was only used once in the
videodev kernel module. The
image formats were added.
1998-11-28: A few ioctl symbols changed. Interfaces for codecs and video output devices were added.
1999-01-14: A raw VBI capture interface was added.
1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added digital zoom (cropping) controls.
Added a v4l to V4L2 ioctl compatibility layer to videodev.c. Driver writers, this changes how you implement your ioctl handler. See the Driver Writer's Guide. Added some more control id codes.
1999-03-18: Fill in the category and catname fields of v4l2_queryctrl objects before passing them to the driver. Required a minor change to the VIDIOC_QUERYCTRL handlers in the sample drivers.
1999-03-31: Better compatibility for v4l memory capture ioctls. Requires changes to drivers to fully support new compatibility features, see Driver Writer's Guide and v4l2cap.c. Added new control IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P, and _YUV411P to _YUV411P.
1999-04-04: Added a few more control IDs.
1999-04-07: Added the button control type.
1999-05-02: Fixed a typo in videodev.h, and added the V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.
1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing a malfunction of this ioctl.
1999-06-05: Changed the value of V4L2_CID_WHITENESS.
Version 0.20 introduced a number of changes which were not backward compatible with 0.19 and earlier versions. Purpose of these changes was to simplify the API, while making it more extensible and following common Linux driver API conventions.
Some typos in
symbols were fixed. struct v4l2_clip was changed for compatibility with
V4L2_TUNER_SUB_LANG1 was added.
All ioctl() commands that used an integer argument now take a pointer to an integer. Where it makes sense, ioctls will return the actual new value in the integer pointed to by the argument, a common convention in the V4L2 API. The affected ioctls are: VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ, VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);becomes
int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);
All the different get- and set-format commands were
swept into one
VIDIOC_S_FMT ioctl taking a union
and a type field selecting the union member as parameter. Purpose is to
simplify the API by eliminating several ioctls and to allow new and
driver private data streams without adding new ioctls.
This change obsoletes the following ioctls:
VIDIOC_G_VBIFMT. The image format structure
v4l2_format was renamed to struct v4l2_pix_format,
while struct v4l2_format is now the envelopping structure for all format
Similar to the changes above, the
VIDIOC_S_PARM ioctls were merged with
type field in the new struct v4l2_streamparm
selects the respective union member.
This change obsoletes the
Control enumeration was simplified, and two new
control flags were introduced and one dropped. The
catname field was replaced by a
Drivers can now flag unsupported and temporarily
unavailable controls with
V4L2_CTRL_FLAG_GRABBED respectively. The
group name indicates a possibly narrower
classification than the
category. In other
words, there may be multiple groups within a category. Controls within
a group would typically be drawn within a group box. Controls in
different categories might have a greater separation, or may even
appear in separate windows.
The struct v4l2_buffer
was changed to a 64 bit integer, containing the sampling or output
time of the frame in nanoseconds. Additionally timestamps will be in
absolute system time, not starting from zero at the beginning of a
stream. The data type name for timestamps is stamp_t, defined as a
signed 64-bit integer. Output devices should not send a buffer out
until the time in the timestamp field has arrived. I would like to
follow SGI's lead, and adopt a multimedia timestamping system like
their UST (Unadjusted System Time). See
http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is
no longer valid.] UST uses timestamps that are 64-bit signed integers
(not struct timeval's) and given in nanosecond units. The UST clock
starts at zero when the system is booted and runs continuously and
uniformly. It takes a little over 292 years for UST to overflow. There
is no way to set the UST clock. The regular Linux time-of-day clock
can be changed periodically, which would cause errors if it were being
used for timestamping a multimedia stream. A real UST style clock will
require some support in the kernel that is not there yet. But in
anticipation, I will change the timestamp field to a 64-bit integer,
and I will change the v4l2_masterclock_gettime() function (used only
by drivers) to return a 64-bit integer.
sequence field was added
to struct v4l2_buffer. The
sequence field counts
captured frames, it is ignored by output devices. When a capture
driver drops a frame, the sequence number of that frame is
1999-12-23: In struct v4l2_vbi_format the
reserved1 field became
offset. Previously drivers were required to
V4L2_FMT_FLAG_NOT_INTERLACED flag was added.
2000-07-31: The linux/poll.h header is now included by videodev.h for compatibility with the original videodev.h file.
V4L2_PIX_FMT_Y41P were added.
2000-12-04: A couple typos in symbol names were fixed.
2001-01-18: To avoid namespace conflicts the
fourcc macro defined in the
videodev.h header file was renamed to
2001-01-25: A possible driver-level compatibility problem between the videodev.h file in Linux 2.4.0 and the videodev.h file included in the videodevX patch was fixed. Users of an earlier version of videodevX on Linux 2.4.0 should recompile their V4L and V4L2 drivers.
2001-01-26: A possible kernel-level incompatibility between the videodev.h file in the videodevX patch and the videodev.h file in Linux 2.2.x with devfs patches applied was fixed.
2001-03-02: Certain V4L ioctls which pass data in both direction although they are defined with read-only parameter, did not work correctly through the backward compatibility layer. [Solution?]
2001-04-13: Big endian 16-bit RGB formats were added.
added. This may break compatibility as the
VIDIOC_S_FMT ioctls may fail now if the struct
field does not contain
V4L2_BUF_TYPE_VBI. In the
documentation of the struct v4l2_vbi_format
offset field the ambiguous phrase "rising
edge" was changed to "leading edge".
A number of changes were made to the raw VBI interface.
Figures clarifying the line numbering scheme were
added to the V4L2 API specification. The
start fields no longer count line
numbers beginning at zero. Rationale: a) The previous definition was
unclear. b) The
start values are ordinal
numbers. c) There is no point in inventing a new line numbering
scheme. We now use line number as defined by ITU-R, period.
Compatibility: Add one to the start values. Applications depending on
the previous semantics may not function correctly.
The restriction "count > 0 and count > 0"
has been relaxed to "(count + count) > 0". Rationale:
Drivers may allocate resources at scan line granularity and some data
services are transmitted only on the first field. The comment that
count values will usually be equal is
misleading and pointless and has been removed. This change
breaks compatibility with earlier versions:
Drivers may return EINVAL, applications may not function
Drivers are again permitted to return negative
(unknown) start values as proposed earlier. Why this feature was
dropped is unclear. This change may break
compatibility with applications depending on the start
values being positive. The use of
EINVAL error codes with the
was clarified. The EBUSY error code was finally documented, and the
reserved2 field which was previously
mentioned only in the videodev.h header
New buffer types
V4L2_TYPE_VBI_OUTPUT were added. The former is an
alias for the old
V4L2_TYPE_VBI, the latter was
missing in the videodev.h file.
Added sliced VBI interface proposal.
Around October-November 2002, prior to an announced feature freeze of Linux 2.5, the API was revised, drawing from experience with V4L2 0.20. This unnamed version was finally merged into Linux 2.5.46.
As specified in Section 1.1.2, drivers must make related device functions available under all minor device numbers.
open() function requires access mode
O_RDWR regardless of the device type. All V4L2
drivers exchanging data with applications must support the
O_NONBLOCK flag. The
flag, a V4L2 symbol which aliased the meaningless
O_TRUNC to indicate accesses without data
exchange (panel applications) was dropped. Drivers must stay in "panel
mode" until the application attempts to initiate a data exchange, see
The struct v4l2_capability changed dramatically. Note that
also the size of the structure changed, which is encoded in the ioctl
request code, thus older V4L2 devices will respond with an EINVAL error code to
There are new fields to identify the driver, a new (as
of yet unspecified) device function
V4L2_CAP_AUDIO flag indicates if the device has
any audio connectors, another I/O capability
V4L2_CAP_ASYNCIO can be flagged. In response to
these changes the
type field became a bit
set and was merged into the
V4L2_FLAG_TUNER was renamed to
V4L2_FLAG_WRITE were merged into
The somewhat volatile and therefore barely useful
maxframerate were removed. This information
is available as described in Section 1.10 and
V4L2_FLAG_SELECT was removed. We
believe the select() function is important enough to require support
of it in all V4L2 drivers exchanging data with applications. The
V4L2_FLAG_MONOCHROME flag was removed,
this information is available as described in Section 1.10.
In struct v4l2_input the
assoc_audio field and the
capability field and its only flag
V4L2_INPUT_CAP_AUDIO was replaced by the new
audioset field. Instead of linking one
video input to one audio input this field reports all audio inputs
this video input combines with.
New fields are
(reversing the former link from tuners to video inputs),
Accordingly struct v4l2_output lost its
std where added instead.
The struct v4l2_audio field
audio was renamed to
index, for consistency with other
structures. A new capability flag
V4L2_AUDCAP_STEREO was added to indicated if the
audio input in question supports stereo sound.
V4L2_AUDCAP_EFFECTS and the corresponding
V4L2_AUDMODE flags where removed. This can be
easily implemented using controls. (However the same applies to AVL
which is still there.)
Again for consistency the struct v4l2_audioout field
audio was renamed to
The struct v4l2_tuner
input field was replaced by an
index field, permitting devices with
multiple tuners. The link between video inputs and tuners is now
reversed, inputs point to their tuner. The
std substructure became a
simple set (more about this below) and moved into struct v4l2_input. A
type field was added.
Accordingly in struct v4l2_modulator the
output was replaced by an
In struct v4l2_frequency the
port field was replaced by a
tuner field containing the respective tuner
or modulator index number. A tuner
field was added and the
became larger for future extensions (satellite tuners in
The idea of completely transparent video standards was
dropped. Experience showed that applications must be able to work with
video standards beyond presenting the user a menu. Instead of
enumerating supported standards with an ioctl applications can now
refer to standards by v4l2_std_id and symbols defined in the
videodev2.h header file. For details see Section 1.7. The
VIDIOC_S_STD now take a pointer to this type as argument.
VIDIOC_QUERYSTD was added to autodetect the received standard, if
the hardware has this capability. In struct v4l2_standard an
index field was added for
A v4l2_std_id field named
id was added as
machine readable identifier, also replacing the
transmission field. The misleading
framerate field was renamed
frameperiod. The now obsolete
colorstandard information, originally
needed to distguish between variations of standards, were
v4l2_enumstd ceased to
VIDIOC_ENUMSTD now takes a pointer to a struct v4l2_standard
directly. The information which standards are supported by a
particular video input or output moved into struct v4l2_input and
struct v4l2_output fields named
The struct v4l2_queryctrl fields
group did not catch on and/or were not
implemented as expected and therefore removed.
In struct v4l2_format the
union was extended to contain struct v4l2_window. All image format
negotiations are now possible with
VIDIOC_TRY_FMT; ioctl. The
VIDIOC_S_WIN ioctls to prepare for a video
overlay were removed. The
changed to type enum v4l2_buf_type and the buffer type names changed as
|Old defines||enum v4l2_buf_type|
|Omitted for now|
|Omitted for now|
|Omitted for now|
|Omitted for now|
|Omitted for now|
In struct v4l2_fmtdesc a enum v4l2_buf_type field named
type was added as in struct v4l2_format. The
VIDIOC_ENUM_FBUFFMT ioctl is no longer needed and
was removed. These calls can be replaced by
In struct v4l2_pix_format the
depth field was removed, assuming
applications which recognize the format by its four-character-code
already know the color depth, and others do not care about it. The
same rationale lead to the removal of the
V4L2_FMT_FLAG_COMPRESSED flag. The
V4L2_FMT_FLAG_SWCONVECOMPRESSED flag was removed
because drivers are not supposed to convert images in kernel space. A
user library of conversion functions should be provided instead. The
V4L2_FMT_FLAG_BYTESPERLINE flag was redundant.
Applications can set the
to zero to get a reasonable default. Since the remaining flags were
replaced as well, the
flags field itself
The interlace flags were replaced by a enum v4l2_field
value in a newly added
|Old flag||enum v4l2_field|
The color space flags were replaced by a
enum v4l2_colorspace value in a newly added
colorspace field, where one of
In struct v4l2_requestbuffers the
type field was properly defined as
enum v4l2_buf_type. Buffer types changed as mentioned above. A new
memory field of type enum v4l2_memory was
added to distinguish between I/O methods using buffers allocated
by the driver or the application. See Chapter 3 for
In struct v4l2_buffer the
field was properly defined as enum v4l2_buf_type. Buffer types changed as
mentioned above. A
field field of type
enum v4l2_field was added to indicate if a buffer contains a top or
bottom field. The old field flags were removed. Since no unadjusted
system time clock was added to the kernel as planned, the
timestamp field changed back from type
stamp_t, an unsigned 64 bit integer expressing the sample time in
nanoseconds, to struct
timeval. With the
addition of a second memory mapping method the
offset field moved into union
m, and a new
memory field of type enum v4l2_memory was
added to distinguish between I/O methods. See Chapter 3
flag was used by the V4L compatibility layer, after changes to this
code it was no longer needed. The
V4L2_BUF_ATTR_DEVICEMEM flag would indicate if
the buffer was indeed allocated in device memory rather than DMA-able
system memory. It was barely useful and so was removed.
In struct v4l2_framebuffer the
base array anticipating double- and
triple-buffering in off-screen video memory, however without defining
a synchronization mechanism, was replaced by a single pointer. The
V4L2_FBUF_CAP_SCALEDOWN flags were removed.
Applications can determine this capability more accurately using the
new cropping and scaling interface. The
V4L2_FBUF_CAP_CLIPPING flag was replaced by
In struct v4l2_clip the
height field moved into a
c substructure of type struct v4l2_rect. The
were renamed to
top, i. e. offsets to a context dependent
In struct v4l2_window the
height field moved into a
w substructure as above. A
field field of type %v4l2-field; was added
to distinguish between field and frame (interlaced) overlay.
The digital zoom interface, including struct
V4L2_ZOOM_WHILESTREAMING was replaced by a new
cropping and scaling interface. The previously unused struct
v4l2_crop where redefined for this purpose.
See Section 1.11 for details.
In struct v4l2_vbi_format the
SAMPLE_FORMAT field now contains a
four-character-code as used to identify video image formats and
V4L2_PIX_FMT_GREY replaces the
V4L2_VBI_SF_UBYTE define. The
reserved field was extended.
In struct v4l2_captureparm the type of the
timeperframe field changed from unsigned
long to struct v4l2_fract. This allows the accurate expression of multiples
of the NTSC-M frame rate 30000 / 1001. A new field
readbuffers was added to control the driver
behaviour in read I/O mode.
Similar changes were made to struct v4l2_outputparm.
VIDIOC_G_PERF ioctl were dropped. Except when
using the read/write I/O method, which is
limited anyway, this information is already available to
The example transformation from RGB to YCbCr color space in the old V4L2 documentation was inaccurate, this has been corrected in Chapter 2.
A new capability flag
V4L2_CAP_RADIO was added for radio devices. Prior
to this change radio devices would identify solely by having exactly one
tuner whose type field reads
An optional driver access priority mechanism was added, see Section 1.3 for details.
The audio input and output interface was found to be incomplete.
ioctl would enumerate the available audio inputs. An ioctl to
determine the current audio input, if more than one combines with the
current video input, did not exist. So
VIDIOC_G_AUDIO was renamed to
VIDIOC_G_AUDIO_OLD, this ioctl will be removed in
the future. The
VIDIOC_ENUMAUDIO ioctl was added to enumerate
audio inputs, while
VIDIOC_G_AUDIO now reports the current audio
Until further the "videodev" module will automatically translate between the old and new ioctls, but drivers and applications must be updated to successfully compile again.
VIDIOC_OVERLAY ioctl was incorrectly defined with
write-read parameter. It was changed to write-only, while the write-read
version was renamed to
VIDIOC_OVERLAY_OLD. The old
ioctl will be removed in the future. Until further the "videodev"
kernel module will automatically translate to the new version, so drivers
must be recompiled, but not applications.
Section 4.2 incorrectly stated that clipping rectangles define regions where the video can be seen. Correct is that clipping rectangles define regions where no video shall be displayed and so the graphics surface can be seen.
VIDIOC_S_CTRL ioctls were
defined with write-only parameter, inconsistent with other ioctls
modifying their argument. They were changed to write-read, while a
_OLD suffix was added to the write-only versions.
The old ioctls will be removed in the future. Drivers and
applications assuming a constant parameter need an update.
In Section 2.4 the following pixel formats were incorrectly transferred from Bill Dirks' V4L2 specification. Descriptions below refer to bytes in memory, in ascending address order.
|Symbol||In this document prior to revision 0.5||Corrected|
|B, G, R||R, G, B|
|R, G, B||B, G, R|
|B, G, R, X||R, G, B, X|
|R, G, B, X||B, G, R, X|
V4L2_PIX_FMT_BGR24example was always correct.
In Section 6.1.5 the mapping
of the V4L
VIDEO_PALETTE_RGB32 formats to V4L2 pixel formats
was accordingly corrected.
Unrelated to the fixes above, drivers may still interpret some V4L2 RGB pixel formats differently. These issues have yet to be addressed, for details see Section 2.4.
VIDIOC_CROPCAP ioctl was incorrectly defined
with read-only parameter. It is now defined as write-read ioctl, while
the read-only version was renamed to
VIDIOC_CROPCAP_OLD. The old ioctl will be removed
in the future.
A new field
reserved) was added to the struct v4l2_buffer
structure. Purpose of this field is to alternate between video inputs
(e. g. cameras) in step with the video capturing process. This function
must be enabled with the new
flags field is no longer
The return value of the V4L2 open()(2) function was incorrectly documented.
Audio output ioctls end in -AUDOUT, not -AUDIOOUT.
In the Current Audio Input example the
VIDIOC_G_AUDIO ioctl took the wrong
The documentation of the
VIDIOC_DQBUF ioctls did not mention the struct v4l2_buffer
memory field. It was also missing from
examples. Also on the
VIDIOC_DQBUF page the EIO error code
was not documented.
A new sliced VBI interface was added. It is documented in Section 4.8 and replaces the interface first proposed in V4L2 specification 0.8.
VIDIOC_LOG_STATUS ioctl was added.
New video standards
V4L2_STD_SECAM_DK (a set of SECAM D, K and K1),
V4L2_STD_ATSC (a set of
V4L2_STD_ATSC_16_VSB) were defined. Note the
V4L2_STD_525_60 set now includes
V4L2_STD_NTSC_443. See also Table 3.
VIDIOC_S_COMP ioctl were renamed to
VIDIOC_S_MPEGCOMP respectively. Their argument
was replaced by a struct
v4l2_mpeg_compression pointer. (The
VIDIOC_S_MPEGCOMP ioctls where removed in Linux
The capture example in Appendix B
VIDIOC_S_CROP ioctl without checking if cropping is
supported. In the video standard selection example in
Section 1.7 the
VIDIOC_S_STD call used the wrong
V4L2_IN_ST_COLOR_KILL flag in
struct v4l2_input not only indicates if the color killer is enabled, but
also if it is active. (The color killer disables color decoding when
it detects no color in the video signal to improve the image
VIDIOC_S_PARM is a write-read ioctl, not write-only as
stated on its reference page. The ioctl changed in 2003 as noted above.
New video standard macros were added:
V4L2_STD_NTSC_M_KR (NTSC M South Korea), and the
V4L2_STD_SECAM sets now include
was defined to record both languages of a bilingual program. The
V4L2_TUNER_MODE_STEREO for this purpose
is deprecated now. See the
VIDIOC_G_TUNER section for
In various places
V4L2_BUF_TYPE_SLICED_VBI_OUTPUT of the sliced VBI
interface were not mentioned along with other buffer types.
ioctl VIDIOC_QUERYCAP(2) did not mention the sliced VBI and radio capability flags.
in struct v4l2_requestbuffers has 2 elements, not 32.
With Linux 2.6.15 the possible range for VBI device minor numbers was extended from 224-239 to 224-255. Accordingly device file names /dev/vbi0 to /dev/vbi31 are possible now.
VIDIOC_TRY_EXT_CTRLS were added, a flag to skip unsupported
VIDIOC_QUERYCTRL, new control types
V4L2_CTRL_TYPE_CTRL_CLASS (Table 3), and new control flags
V4L2_CTRL_FLAG_SLIDER (Table 4). See Section 1.9 for details.
In struct v4l2_sliced_vbi_cap a buffer type field was added
replacing a reserved field. Note on architectures where the size of
enum types differs from int types the size of the structure changed.
VIDIOC_G_SLICED_VBI_CAP ioctl was redefined from being read-only
to write-read. Applications must initialize the type field and clear
the reserved fields now. These changes may break the
compatibility with older drivers and applications.
A new pixel format
V4L2_PIX_FMT_RGB444 (Table 2-1) was added.
V4L2_PIX_FMT_HM12 (Table 2-8) is a YUV 4:2:0, not 4:2:2 format.
The videodev2.h header file is now dual licensed under GNU General Public License version two or later, and under a 3-clause BSD-style license.
Two new field orders
added. See Table 3-8 for details.
Three new clipping/blending methods with a global or
straight or inverted local alpha value were added to the video overlay
interface. See the description of the
VIDIOC_S_FBUF ioctls for details.
was added to
extending the structure. This may break
compatibility with applications using a struct
v4l2_window directly. However the VIDIOC_G/S/TRY_FMT ioctls, which take a
pointer to a v4l2_format parent
structure with padding bytes at the end, are not affected.
The format of the
field in struct v4l2_window changed from "host order RGB32" to a pixel
value in the same format as the framebuffer. This may break
compatibility with existing applications. Drivers
supporting the "host order RGB32" format are not known.
The pixel formats
V4L2_PIX_FMT_YUV32 were added.
V4L2_CID_BACKLIGHT_COMPENSATION were added. The
V4L2_CID_VCENTER were deprecated.
A Camera controls
class was added, with the new controls
VIDIOC_S_MPEGCOMP ioctls, which were superseded
by the extended controls
interface in Linux 2.6.18, where finally removed from the
videodev2.h header file.