1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. include:: <isonum.txt> 3 4.. _v4l2spec: 5 6############################ 7Part I - Video for Linux API 8############################ 9 10This part describes the Video for Linux API version 2 (V4L2 API) specification. 11 12**Revision 4.5** 13 14.. toctree:: 15 :caption: Table of Contents 16 :numbered: 17 :maxdepth: 5 18 19 common 20 pixfmt 21 io 22 devices 23 libv4l 24 compat 25 user-func 26 common-defs 27 videodev 28 capture-example 29 v4l2grab-example 30 biblio 31 32 33********************** 34Revision and Copyright 35********************** 36 37Authors, in alphabetical order: 38 39- Ailus, Sakari <sakari.ailus@iki.fi> 40 41 - Subdev selections API. 42 43- Carvalho Chehab, Mauro <mchehab+samsung@kernel.org> 44 45 - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter. 46 47- Dirks, Bill 48 49 - Original author of the V4L2 API and documentation. 50 51- Figa, Tomasz <tfiga@chromium.org> 52 53 - Documented the memory-to-memory decoder interface. 54 - Documented the memory-to-memory encoder interface. 55 56- H Schimek, Michael <mschimek@gmx.at> 57 58 - Original author of the V4L2 API and documentation. 59 60- Karicheri, Muralidharan <m-karicheri2@ti.com> 61 62 - Documented the Digital Video timings API. 63 64- Osciak, Pawel <posciak@chromium.org> 65 66 - Documented the memory-to-memory decoder interface. 67 - Documented the memory-to-memory encoder interface. 68 69- Osciak, Pawel <pawel@osciak.com> 70 71 - Designed and documented the multi-planar API. 72 73- Palosaari, Antti <crope@iki.fi> 74 75 - SDR API. 76 77- Ribalda, Ricardo 78 79 - Introduce HSV formats and other minor changes. 80 81- Rubli, Martin 82 83 - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls. 84 85- Walls, Andy <awalls@md.metrocast.net> 86 87 - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification. 88 89- Verkuil, Hans <hverkuil@xs4all.nl> 90 91 - Designed and documented the VIDIOC_LOG_STATUS ioctl, the extended control ioctls, major parts of the sliced VBI API, the MPEG encoder and decoder APIs and the DV Timings API. 92 93**Copyright** |copy| 1999-2018: Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, Pawel Osciak, Sakari Ailus & Antti Palosaari, Tomasz Figa 94 95Except when explicitly stated as GPL, programming examples within this 96part can be used and distributed without restrictions. 97 98**************** 99Revision History 100**************** 101 102:revision: 4.10 / 2016-07-15 (*rr*) 103 104Introduce HSV formats. 105 106 107:revision: 4.5 / 2015-10-29 (*rr*) 108 109Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with 110ctrl_class and which. Which is used to select the current value of the 111control or the default value. 112 113 114:revision: 4.4 / 2015-05-26 (*ap*) 115 116Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added 117V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for 118Software Defined Radio (SDR) Interface. 119 120 121:revision: 4.1 / 2015-02-13 (*mcc*) 122 123Fix documentation for media controller device nodes and add support for 124DVB device nodes. Add support for Tuner sub-device. 125 126 127:revision: 3.19 / 2014-12-05 (*hv*) 128 129Rewrote Colorspace chapter, added new enum 130:c:type:`v4l2_ycbcr_encoding` and enum 131:c:type:`v4l2_quantization` fields to struct 132:c:type:`v4l2_pix_format`, struct 133:c:type:`v4l2_pix_format_mplane` and struct 134:c:type:`v4l2_mbus_framefmt`. 135 136 137:revision: 3.17 / 2014-08-04 (*lp, hv*) 138 139Extended struct :c:type:`v4l2_pix_format`. Added 140format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL. 141 142 143:revision: 3.15 / 2014-02-03 (*hv, ap*) 144 145Update several sections of "Common API Elements": "Opening and Closing 146Devices" "Querying Capabilities", "Application Priority", "Video Inputs 147and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video 148Standards" and "Digital Video (DV) Timings". Added SDR API. 149 150 151:revision: 3.14 / 2013-11-25 (*rr*) 152 153Set width and height as unsigned on v4l2_rect. 154 155 156:revision: 3.11 / 2013-05-26 (*hv*) 157 158Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl. 159 160 161:revision: 3.10 / 2013-03-25 (*hv*) 162 163Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET, 164VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and 165VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output 166capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. 167Added VIDIOC_DBG_G_CHIP_INFO. 168 169 170:revision: 3.9 / 2012-12-03 (*sa, sn*) 171 172Added timestamp types to v4l2_buffer. Added 173V4L2_EVENT_CTRL_CH_RANGE control event changes flag. 174 175 176:revision: 3.6 / 2012-07-02 (*hv*) 177 178Added VIDIOC_ENUM_FREQ_BANDS. 179 180 181:revision: 3.5 / 2012-05-07 (*sa, sn, hv*) 182 183Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. 184Improved the description of V4L2_CID_COLORFX control, added 185V4L2_CID_COLORFX_CBCR control. Added camera controls 186V4L2_CID_AUTO_EXPOSURE_BIAS, 187V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE, 188V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY, 189V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING, 190V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK, 191V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, 192V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added 193VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and 194VIDIOC_DV_TIMINGS_CAP. 195 196 197:revision: 3.4 / 2012-01-25 (*sn*) 198 199Added :ref:`JPEG compression control class. <jpeg-controls>` 200 201 202:revision: 3.3 / 2012-01-11 (*hv*) 203 204Added device_caps field to struct v4l2_capabilities. 205 206 207:revision: 3.2 / 2011-08-26 (*hv*) 208 209Added V4L2_CTRL_FLAG_VOLATILE. 210 211 212:revision: 3.1 / 2011-06-27 (*mcc, po, hv*) 213 214Documented that VIDIOC_QUERYCAP now returns a per-subsystem version 215instead of a per-driver one. Standardize an error code for invalid 216ioctl. Added V4L2_CTRL_TYPE_BITMASK. 217 218 219:revision: 2.6.39 / 2011-03-01 (*mcc, po*) 220 221Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect 222latest changes. Added the :ref:`multi-planar API <planar-apis>`. 223 224 225:revision: 2.6.37 / 2010-08-06 (*hv*) 226 227Removed obsolete vtx (videotext) API. 228 229 230:revision: 2.6.33 / 2009-12-03 (*mk*) 231 232Added documentation for the Digital Video timings API. 233 234 235:revision: 2.6.32 / 2009-08-31 (*mcc*) 236 237Now, revisions will match the kernel version where the V4L2 API changes 238will be used by the Linux Kernel. Also added Remote Controller chapter. 239 240 241:revision: 0.29 / 2009-08-26 (*ev*) 242 243Added documentation for string controls and for FM Transmitter controls. 244 245 246:revision: 0.28 / 2009-08-26 (*gl*) 247 248Added V4L2_CID_BAND_STOP_FILTER documentation. 249 250 251:revision: 0.27 / 2009-08-15 (*mcc*) 252 253Added libv4l and Remote Controller documentation; added v4l2grab and 254keytable application examples. 255 256 257:revision: 0.26 / 2009-07-23 (*hv*) 258 259Finalized the RDS capture API. Added modulator and RDS encoder 260capabilities. Added support for string controls. 261 262 263:revision: 0.25 / 2009-01-18 (*hv*) 264 265Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls 266VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera 267controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE, 268V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY. 269 270 271:revision: 0.24 / 2008-03-04 (*mhs*) 272 273Added pixel formats Y16 and SBGGR16, new controls and a camera controls 274class. Removed VIDIOC_G/S_MPEGCOMP. 275 276 277:revision: 0.23 / 2007-08-30 (*mhs*) 278 279Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of 280packed pixel formats. 281 282 283:revision: 0.22 / 2007-08-29 (*mhs*) 284 285Added the Video Output Overlay interface, new MPEG controls, 286V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT, 287VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD, 288VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats. 289Clarifications in the cropping chapter, about RGB pixel formats, the 290mmap(), poll(), select(), read() and write() functions. Typographical 291fixes. 292 293 294:revision: 0.21 / 2006-12-19 (*mhs*) 295 296Fixed a link in the VIDIOC_G_EXT_CTRLS section. 297 298 299:revision: 0.20 / 2006-11-24 (*mhs*) 300 301Clarified the purpose of the audioset field in struct v4l2_input and 302v4l2_output. 303 304 305:revision: 0.19 / 2006-10-19 (*mhs*) 306 307Documented V4L2_PIX_FMT_RGB444. 308 309 310:revision: 0.18 / 2006-10-18 (*mhs*) 311 312Added the description of extended controls by Hans Verkuil. Linked 313V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE. 314 315 316:revision: 0.17 / 2006-10-12 (*mhs*) 317 318Corrected V4L2_PIX_FMT_HM12 description. 319 320 321:revision: 0.16 / 2006-10-08 (*mhs*) 322 323VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part 324of the API. 325 326 327:revision: 0.15 / 2006-09-23 (*mhs*) 328 329Cleaned up the bibliography, added BT.653 and BT.1119. 330capture.c/start_capturing() for user pointer I/O did not initialize the 331buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and 332V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See 333the history chapter for API changes. 334 335 336:revision: 0.14 / 2006-09-14 (*mr*) 337 338Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal 339for frame format enumeration of digital devices. 340 341 342:revision: 0.13 / 2006-04-07 (*mhs*) 343 344Corrected the description of struct v4l2_window clips. New V4L2_STD\_ 345and V4L2_TUNER_MODE_LANG1_LANG2 defines. 346 347 348:revision: 0.12 / 2006-02-03 (*mhs*) 349 350Corrected the description of struct v4l2_captureparm and 351v4l2_outputparm. 352 353 354:revision: 0.11 / 2006-01-27 (*mhs*) 355 356Improved the description of struct v4l2_tuner. 357 358 359:revision: 0.10 / 2006-01-10 (*mhs*) 360 361VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications. 362 363 364:revision: 0.9 / 2005-11-27 (*mhs*) 365 366Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the 367sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page. 368Fixed VIDIOC_S_STD call in the video standard selection example. 369Various updates. 370 371 372:revision: 0.8 / 2004-10-04 (*mhs*) 373 374Somehow a piece of junk slipped into the capture example, removed. 375 376 377:revision: 0.7 / 2004-09-19 (*mhs*) 378 379Fixed video standard selection, control enumeration, downscaling and 380aspect example. Added read and user pointer i/o to video capture 381example. 382 383 384:revision: 0.6 / 2004-08-01 (*mhs*) 385 386v4l2_buffer changes, added video capture example, various corrections. 387 388 389:revision: 0.5 / 2003-11-05 (*mhs*) 390 391Pixel format erratum. 392 393 394:revision: 0.4 / 2003-09-17 (*mhs*) 395 396Corrected source and Makefile to generate a PDF. SGML fixes. Added 397latest API changes. Closed gaps in the history chapter. 398 399 400:revision: 0.3 / 2003-02-05 (*mhs*) 401 402Another draft, more corrections. 403 404 405:revision: 0.2 / 2003-01-15 (*mhs*) 406 407Second draft, with corrections pointed out by Gerd Knorr. 408 409 410:revision: 0.1 / 2002-12-01 (*mhs*) 411 412First draft, based on documentation by Bill Dirks and discussions on the 413V4L mailing list. 414