Documentation/media/uapi/v4l/v4l2.rst

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