Documentation/media/uapi/v4l/v4l2.rst

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