summaryrefslogtreecommitdiff
path: root/Documentation/media/uapi/v4l
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/media/uapi/v4l')
-rw-r--r--Documentation/media/uapi/v4l/app-pri.rst30
-rw-r--r--Documentation/media/uapi/v4l/async.rst9
-rw-r--r--Documentation/media/uapi/v4l/audio.rst90
-rw-r--r--Documentation/media/uapi/v4l/biblio.rst381
-rw-r--r--Documentation/media/uapi/v4l/buffer.rst979
-rw-r--r--Documentation/media/uapi/v4l/capture-example.rst13
-rw-r--r--Documentation/media/uapi/v4l/capture.c.rst664
-rw-r--r--Documentation/media/uapi/v4l/colorspaces.rst163
-rw-r--r--Documentation/media/uapi/v4l/common-defs.rst13
-rw-r--r--Documentation/media/uapi/v4l/common.rst46
-rw-r--r--Documentation/media/uapi/v4l/compat.rst18
-rw-r--r--Documentation/media/uapi/v4l/control.rst533
-rw-r--r--Documentation/media/uapi/v4l/crop.rst294
-rw-r--r--Documentation/media/uapi/v4l/crop_files/crop.gifbin0 -> 5967 bytes
-rw-r--r--Documentation/media/uapi/v4l/crop_files/crop.pdfbin0 -> 5846 bytes
-rw-r--r--Documentation/media/uapi/v4l/depth-formats.rst15
-rw-r--r--Documentation/media/uapi/v4l/dev-capture.rst102
-rw-r--r--Documentation/media/uapi/v4l/dev-codec.rst32
-rw-r--r--Documentation/media/uapi/v4l/dev-effect.rst22
-rw-r--r--Documentation/media/uapi/v4l/dev-event.rst47
-rw-r--r--Documentation/media/uapi/v4l/dev-osd.rst146
-rw-r--r--Documentation/media/uapi/v4l/dev-output.rst99
-rw-r--r--Documentation/media/uapi/v4l/dev-overlay.rst316
-rw-r--r--Documentation/media/uapi/v4l/dev-radio.rst52
-rw-r--r--Documentation/media/uapi/v4l/dev-raw-vbi.rst350
-rw-r--r--Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gifbin0 -> 4741 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdfbin0 -> 3395 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gifbin0 -> 5095 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdfbin0 -> 3683 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gifbin0 -> 2400 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdfbin0 -> 7405 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-rds.rst255
-rw-r--r--Documentation/media/uapi/v4l/dev-sdr.rst120
-rw-r--r--Documentation/media/uapi/v4l/dev-sliced-vbi.rst822
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev.rst491
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdfbin0 -> 20276 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pngbin0 -> 12130 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdfbin0 -> 20729 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg63
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdfbin0 -> 46311 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg163
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdfbin0 -> 36714 bytes
-rw-r--r--Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg116
-rw-r--r--Documentation/media/uapi/v4l/dev-teletext.rst34
-rw-r--r--Documentation/media/uapi/v4l/devices.rst26
-rw-r--r--Documentation/media/uapi/v4l/diff-v4l.rst954
-rw-r--r--Documentation/media/uapi/v4l/dmabuf.rst155
-rw-r--r--Documentation/media/uapi/v4l/driver.rst9
-rw-r--r--Documentation/media/uapi/v4l/dv-timings.rst38
-rw-r--r--Documentation/media/uapi/v4l/extended-controls.rst4524
-rw-r--r--Documentation/media/uapi/v4l/field-order.rst205
-rw-r--r--Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gifbin0 -> 25430 bytes
-rw-r--r--Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdfbin0 -> 9185 bytes
-rw-r--r--Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gifbin0 -> 25323 bytes
-rw-r--r--Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdfbin0 -> 9173 bytes
-rw-r--r--Documentation/media/uapi/v4l/format.rst92
-rw-r--r--Documentation/media/uapi/v4l/func-close.rst49
-rw-r--r--Documentation/media/uapi/v4l/func-ioctl.rst62
-rw-r--r--Documentation/media/uapi/v4l/func-mmap.rst134
-rw-r--r--Documentation/media/uapi/v4l/func-munmap.rst58
-rw-r--r--Documentation/media/uapi/v4l/func-open.rst83
-rw-r--r--Documentation/media/uapi/v4l/func-poll.rst116
-rw-r--r--Documentation/media/uapi/v4l/func-read.rst131
-rw-r--r--Documentation/media/uapi/v4l/func-select.rst106
-rw-r--r--Documentation/media/uapi/v4l/func-write.rst82
-rw-r--r--Documentation/media/uapi/v4l/hist-v4l2.rst1480
-rw-r--r--Documentation/media/uapi/v4l/io.rst51
-rw-r--r--Documentation/media/uapi/v4l/libv4l-introduction.rst169
-rw-r--r--Documentation/media/uapi/v4l/libv4l.rst13
-rw-r--r--Documentation/media/uapi/v4l/mmap.rst280
-rw-r--r--Documentation/media/uapi/v4l/open.rst158
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-002.rst196
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-003.rst166
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-004.rst51
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-006.rst280
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-007.rst894
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-008.rst32
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-013.rst129
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-grey.rst77
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-indexed.rst73
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-m420.rst219
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv12.rst221
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv12m.rst238
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv12mt.rst62
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gifbin0 -> 2108 bytes
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gifbin0 -> 6858 bytes
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv16.rst270
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv16m.rst277
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-nv24.rst171
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst1469
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst316
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-reserved.rst360
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-rgb.rst23
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sbggr16.rst113
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sbggr8.rst81
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst43
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst48
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst43
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst47
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst38
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst81
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst81
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-srggb10.rst120
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst26
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst28
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-srggb10p.rst103
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-srggb12.rst121
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-srggb8.rst81
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-uv8.rst76
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-uyvy.rst197
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-vyuy.rst195
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y10.rst110
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y10b.rst45
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y12.rst110
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y12i.rst44
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y16-be.rst111
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y16.rst111
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y41p.rst274
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-y8i.rst111
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuv410.rst208
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuv411p.rst214
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuv420.rst239
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuv420m.rst254
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuv422m.rst258
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuv422p.rst240
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuv444m.rst266
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yuyv.rst205
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-yvyu.rst195
-rw-r--r--Documentation/media/uapi/v4l/pixfmt-z16.rst111
-rw-r--r--Documentation/media/uapi/v4l/pixfmt.rst35
-rw-r--r--Documentation/media/uapi/v4l/planar-apis.rst61
-rw-r--r--Documentation/media/uapi/v4l/querycap.rst34
-rw-r--r--Documentation/media/uapi/v4l/rw.rst47
-rw-r--r--Documentation/media/uapi/v4l/sdr-formats.rst19
-rw-r--r--Documentation/media/uapi/v4l/selection-api-002.rst28
-rw-r--r--Documentation/media/uapi/v4l/selection-api-003.rst20
-rw-r--r--Documentation/media/uapi/v4l/selection-api-003_files/selection.pngbin0 -> 11716 bytes
-rw-r--r--Documentation/media/uapi/v4l/selection-api-004.rst137
-rw-r--r--Documentation/media/uapi/v4l/selection-api-005.rst34
-rw-r--r--Documentation/media/uapi/v4l/selection-api-006.rst81
-rw-r--r--Documentation/media/uapi/v4l/selection-api.rst16
-rw-r--r--Documentation/media/uapi/v4l/selections-common.rst23
-rw-r--r--Documentation/media/uapi/v4l/standard.rst179
-rw-r--r--Documentation/media/uapi/v4l/streaming-par.rst33
-rw-r--r--Documentation/media/uapi/v4l/subdev-formats.rst11688
-rw-r--r--Documentation/media/uapi/v4l/subdev-formats_files/bayer.pngbin0 -> 9725 bytes
-rw-r--r--Documentation/media/uapi/v4l/tuner.rst82
-rw-r--r--Documentation/media/uapi/v4l/user-func.rst81
-rw-r--r--Documentation/media/uapi/v4l/userp.rst117
-rw-r--r--Documentation/media/uapi/v4l/v4l2-selection-flags.rst71
-rw-r--r--Documentation/media/uapi/v4l/v4l2-selection-targets.rst135
-rw-r--r--Documentation/media/uapi/v4l/v4l2.rst395
-rw-r--r--Documentation/media/uapi/v4l/v4l2grab-example.rst17
-rw-r--r--Documentation/media/uapi/v4l/v4l2grab.c.rst169
-rw-r--r--Documentation/media/uapi/v4l/video.rst63
-rw-r--r--Documentation/media/uapi/v4l/videodev.rst9
-rw-r--r--Documentation/media/uapi/v4l/vidioc-create-bufs.rst146
-rw-r--r--Documentation/media/uapi/v4l/vidioc-cropcap.rst167
-rw-r--r--Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst204
-rw-r--r--Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst209
-rw-r--r--Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst271
-rw-r--r--Documentation/media/uapi/v4l/vidioc-dqevent.rst573
-rw-r--r--Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst250
-rw-r--r--Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst195
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst119
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enum-fmt.rst164
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst274
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst291
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst190
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enumaudio.rst56
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enumaudioout.rst59
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enuminput.rst367
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enumoutput.rst222
-rw-r--r--Documentation/media/uapi/v4l/vidioc-enumstd.rst442
-rw-r--r--Documentation/media/uapi/v4l/vidioc-expbuf.rst197
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-audio.rst162
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-audioout.rst122
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-crop.rst113
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-ctrl.rst105
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst417
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-edid.rst158
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-enc-index.rst210
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst488
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-fbuf.rst500
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-fmt.rst188
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-frequency.rst123
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-input.rst62
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst184
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-modulator.rst255
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-output.rst64
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-parm.rst349
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-priority.rst117
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-selection.rst209
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.pngbin0 -> 3313 bytes
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst276
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-std.rst68
-rw-r--r--Documentation/media/uapi/v4l/vidioc-g-tuner.rst715
-rw-r--r--Documentation/media/uapi/v4l/vidioc-log-status.rst46
-rw-r--r--Documentation/media/uapi/v4l/vidioc-overlay.rst55
-rw-r--r--Documentation/media/uapi/v4l/vidioc-prepare-buf.rst62
-rw-r--r--Documentation/media/uapi/v4l/vidioc-qbuf.rst150
-rw-r--r--Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst83
-rw-r--r--Documentation/media/uapi/v4l/vidioc-querybuf.rst81
-rw-r--r--Documentation/media/uapi/v4l/vidioc-querycap.rst434
-rw-r--r--Documentation/media/uapi/v4l/vidioc-queryctrl.rst780
-rw-r--r--Documentation/media/uapi/v4l/vidioc-querystd.rst66
-rw-r--r--Documentation/media/uapi/v4l/vidioc-reqbufs.rst125
-rw-r--r--Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst179
-rw-r--r--Documentation/media/uapi/v4l/vidioc-streamon.rst103
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst153
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst162
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst115
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst136
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst171
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst122
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst144
-rw-r--r--Documentation/media/uapi/v4l/vidioc-subscribe-event.rst135
-rw-r--r--Documentation/media/uapi/v4l/yuv-formats.rst55
218 files changed, 51817 insertions, 0 deletions
diff --git a/Documentation/media/uapi/v4l/app-pri.rst b/Documentation/media/uapi/v4l/app-pri.rst
new file mode 100644
index 000000000000..a8c41a7ec396
--- /dev/null
+++ b/Documentation/media/uapi/v4l/app-pri.rst
@@ -0,0 +1,30 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _app-pri:
+
+********************
+Application Priority
+********************
+
+When multiple applications share a device it may be desirable to assign
+them different priorities. Contrary to the traditional "rm -rf /" school
+of thought a video recording application could for example block other
+applications from changing video controls or switching the current TV
+channel. Another objective is to permit low priority applications
+working in background, which can be preempted by user controlled
+applications and automatically regain control of the device at a later
+time.
+
+Since these features cannot be implemented entirely in user space V4L2
+defines the :ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` and
+:ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctls to request and
+query the access priority associate with a file descriptor. Opening a
+device assigns a medium priority, compatible with earlier versions of
+V4L2 and drivers not supporting these ioctls. Applications requiring a
+different priority will usually call :ref:`VIDIOC_S_PRIORITY
+<VIDIOC_G_PRIORITY>` after verifying the device with the
+:ref:`VIDIOC_QUERYCAP` ioctl.
+
+Ioctls changing driver properties, such as
+:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>`, return an ``EBUSY`` error code
+after another application obtained higher priority.
diff --git a/Documentation/media/uapi/v4l/async.rst b/Documentation/media/uapi/v4l/async.rst
new file mode 100644
index 000000000000..5affc0adb95b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/async.rst
@@ -0,0 +1,9 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _async:
+
+****************
+Asynchronous I/O
+****************
+
+This method is not defined yet.
diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst
new file mode 100644
index 000000000000..71502f0bf8bd
--- /dev/null
+++ b/Documentation/media/uapi/v4l/audio.rst
@@ -0,0 +1,90 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _audio:
+
+************************
+Audio Inputs and Outputs
+************************
+
+Audio inputs and outputs are physical connectors of a device. Video
+capture devices have inputs, output devices have outputs, zero or more
+each. Radio devices have no audio inputs or outputs. They have exactly
+one tuner which in fact *is* an audio source, but this API associates
+tuners with video inputs or outputs only, and radio devices have none of
+these. [1]_ A connector on a TV card to loop back the received audio
+signal to a sound card is not considered an audio output.
+
+Audio and video inputs and outputs are associated. Selecting a video
+source also selects an audio source. This is most evident when the video
+and audio source is a tuner. Further audio connectors can combine with
+more than one video input or output. Assumed two composite video inputs
+and two audio inputs exist, there may be up to four valid combinations.
+The relation of video and audio connectors is defined in the
+``audioset`` field of the respective struct
+:ref:`v4l2_input <v4l2-input>` or struct
+:ref:`v4l2_output <v4l2-output>`, where each bit represents the index
+number, starting at zero, of one audio input or output.
+
+To learn about the number and attributes of the available inputs and
+outputs applications can enumerate them with the
+:ref:`VIDIOC_ENUMAUDIO` and
+:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` ioctl, respectively.
+The struct :ref:`v4l2_audio <v4l2-audio>` returned by the
+:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal
+:status information applicable when the current audio input is queried.
+
+The :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
+:ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` ioctls report the current
+audio input and output, respectively. Note that, unlike
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` these ioctls return a
+structure as :ref:`VIDIOC_ENUMAUDIO` and
+:ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>` do, not just an index.
+
+To select an audio input and change its properties applications call the
+:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl. To select an audio
+output (which presently has no changeable properties) applications call
+the :ref:`VIDIOC_S_AUDOUT <VIDIOC_G_AUDOUT>` ioctl.
+
+Drivers must implement all audio input ioctls when the device has
+multiple selectable audio inputs, all audio output ioctls when the
+device has multiple selectable audio outputs. When the device has any
+audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag
+in the struct :ref:`v4l2_capability <v4l2-capability>` returned by
+the :ref:`VIDIOC_QUERYCAP` ioctl.
+
+
+.. code-block:: c
+ :caption: Example 1.3. Information about the current audio input
+
+ struct v4l2_audio audio;
+
+ memset(&audio, 0, sizeof(audio));
+
+ if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) {
+ perror("VIDIOC_G_AUDIO");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input: %s\\n", audio.name);
+
+
+.. code-block:: c
+ :caption: Example 1.4. Switching to the first audio input
+
+ struct v4l2_audio audio;
+
+ memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */
+
+ audio.index = 0;
+
+ if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) {
+ perror("VIDIOC_S_AUDIO");
+ exit(EXIT_FAILURE);
+ }
+
+.. [1]
+ Actually struct :ref:`v4l2_audio <v4l2-audio>` ought to have a
+ ``tuner`` field like struct :ref:`v4l2_input <v4l2-input>`, not
+ only making the API more consistent but also permitting radio devices
+ with multiple tuners.
diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst
new file mode 100644
index 000000000000..e911df972d40
--- /dev/null
+++ b/Documentation/media/uapi/v4l/biblio.rst
@@ -0,0 +1,381 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+**********
+References
+**********
+
+
+.. _cea608:
+
+CEA 608-E
+=========
+
+
+:title: CEA-608-E R-2014 "Line 21 Data Services"
+
+:author: Consumer Electronics Association (http://www.ce.org)
+
+.. _en300294:
+
+EN 300 294
+==========
+
+
+:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _ets300231:
+
+ETS 300 231
+===========
+
+
+:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _ets300706:
+
+ETS 300 706
+===========
+
+
+:title: ETS 300 706 "Enhanced Teletext specification"
+
+:author: European Telecommunication Standards Institute (http://www.etsi.org)
+
+.. _mpeg2part1:
+
+ISO 13818-1
+===========
+
+
+:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems"
+
+:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
+
+.. _mpeg2part2:
+
+ISO 13818-2
+===========
+
+
+:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video"
+
+:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch)
+
+.. _itu470:
+
+ITU BT.470
+==========
+
+
+:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu601:
+
+ITU BT.601
+==========
+
+
+:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu653:
+
+ITU BT.653
+==========
+
+
+:title: ITU-R Recommendation BT.653-3 "Teletext systems"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu709:
+
+ITU BT.709
+==========
+
+
+:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _itu1119:
+
+ITU BT.1119
+===========
+
+
+:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _jfif:
+
+JFIF
+====
+
+
+:title: JPEG File Interchange Format
+:subtitle: Version 1.02
+
+:author: Independent JPEG Group (http://www.ijg.org)
+
+.. _itu-t81:
+
+ITU-T.81
+========
+
+
+:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines"
+
+:author: International Telecommunication Union (http://www.itu.int)
+
+.. _w3c-jpeg-jfif:
+
+W3C JPEG JFIF
+=============
+
+
+:title: JPEG JFIF
+
+:author: The World Wide Web Consortium (http://www.w3.org)
+
+.. _smpte12m:
+
+SMPTE 12M
+=========
+
+
+:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte170m:
+
+SMPTE 170M
+==========
+
+
+:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte240m:
+
+SMPTE 240M
+==========
+
+
+:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte431:
+
+SMPTE RP 431-2
+==============
+
+
+:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _smpte2084:
+
+SMPTE ST 2084
+=============
+
+
+:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays"
+
+:author: Society of Motion Picture and Television Engineers (http://www.smpte.org)
+
+.. _srgb:
+
+sRGB
+====
+
+
+:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _sycc:
+
+sYCC
+====
+
+
+:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _xvycc:
+
+xvYCC
+=====
+
+
+:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _adobergb:
+
+AdobeRGB
+========
+
+
+:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05
+
+:author: Adobe Systems Incorporated (http://www.adobe.com)
+
+.. _oprgb:
+
+opRGB
+=====
+
+
+:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _itu2020:
+
+ITU BT.2020
+===========
+
+
+:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange"
+
+:author: International Telecommunication Union (http://www.itu.ch)
+
+.. _tech3213:
+
+EBU Tech 3213
+=============
+
+
+:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"
+
+:author: European Broadcast Union (http://www.ebu.ch)
+
+.. _iec62106:
+
+IEC 62106
+=========
+
+
+:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz
+
+:author: International Electrotechnical Commission (http://www.iec.ch)
+
+.. _nrsc4:
+
+NRSC-4-B
+========
+
+
+:title: NRSC-4-B: United States RBDS Standard
+
+:author: National Radio Systems Committee (http://www.nrscstandards.org)
+
+.. _iso12232:
+
+ISO 12232:2006
+==============
+
+
+:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index
+
+:author: International Organization for Standardization (http://www.iso.org)
+
+.. _cea861:
+
+CEA-861-E
+=========
+
+
+:title: A DTV Profile for Uncompressed High Speed Digital Interfaces
+
+:author: Consumer Electronics Association (http://www.ce.org)
+
+.. _vesadmt:
+
+VESA DMT
+========
+
+
+:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _vesaedid:
+
+EDID
+====
+
+
+:title: VESA Enhanced Extended Display Identification Data Standard
+:subtitle: Release A, Revision 2
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _hdcp:
+
+HDCP
+====
+
+
+:title: High-bandwidth Digital Content Protection System
+:subtitle: Revision 1.3
+
+:author: Digital Content Protection LLC (http://www.digital-cp.com)
+
+.. _hdmi:
+
+HDMI
+====
+
+
+:title: High-Definition Multimedia Interface
+:subtitle: Specification Version 1.4a
+
+:author: HDMI Licensing LLC (http://www.hdmi.org)
+
+.. _dp:
+
+DP
+==
+
+
+:title: VESA DisplayPort Standard
+:subtitle: Version 1, Revision 2
+
+:author: Video Electronics Standards Association (http://www.vesa.org)
+
+.. _poynton:
+
+poynton
+=======
+
+
+:title: Digital Video and HDTV, Algorithms and Interfaces
+
+:author: Charles Poynton
+
+.. _colimg:
+
+colimg
+======
+
+
+:title: Color Imaging: Fundamentals and Applications
+
+:author: Erik Reinhard et al.
diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst
new file mode 100644
index 000000000000..b195eb5b63a1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/buffer.rst
@@ -0,0 +1,979 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _buffer:
+
+*******
+Buffers
+*******
+
+A buffer contains data exchanged by application and driver using one of
+the Streaming I/O methods. In the multi-planar API, the data is held in
+planes, while the buffer structure acts as a container for the planes.
+Only pointers to buffers (planes) are exchanged, the data itself is not
+copied. These pointers, together with meta-information like timestamps
+or field parity, are stored in a struct :ref:`struct v4l2_buffer <v4l2-buffer>`,
+argument to the :ref:`VIDIOC_QUERYBUF`,
+:ref:`VIDIOC_QBUF` and
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. In the multi-planar API,
+some plane-specific members of struct :ref:`struct v4l2_buffer <v4l2-buffer>`,
+such as pointers and sizes for each plane, are stored in struct
+:ref:`struct v4l2_plane <v4l2-plane>` instead. In that case, struct
+:ref:`struct v4l2_buffer <v4l2-buffer>` contains an array of plane structures.
+
+Dequeued video buffers come with timestamps. The driver decides at which
+part of the frame and with which clock the timestamp is taken. Please
+see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and
+``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags
+are always valid and constant across all buffers during the whole video
+stream. Changes in these flags may take place as a side effect of
+:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` or
+:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` however. The
+``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on
+mem-to-mem devices is an exception to the rule: the timestamp source
+flags are copied from the OUTPUT video buffer to the CAPTURE video
+buffer.
+
+
+.. _v4l2-buffer:
+
+struct v4l2_buffer
+==================
+
+.. flat-table:: struct v4l2_buffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - Number of the buffer, set by the application except when calling
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, then it is set by the
+ driver. This field can range from zero to the number of buffers
+ allocated with the :ref:`VIDIOC_REQBUFS` ioctl
+ (struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>`
+ ``count``), plus any buffers allocated with
+ :ref:`VIDIOC_CREATE_BUFS` minus one.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the buffer, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` or struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
+ by the application. See :ref:`v4l2-buf-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``bytesused``
+
+ -
+ - The number of bytes occupied by the data in the buffer. It depends
+ on the negotiated data format and may change with each buffer for
+ compressed variable size data like JPEG images. Drivers must set
+ this field when ``type`` refers to a capture stream, applications
+ when it refers to an output stream. If the application sets this
+ to 0 for an output stream, then ``bytesused`` will be set to the
+ size of the buffer (see the ``length`` field of this struct) by
+ the driver. For multiplanar formats this field is ignored and the
+ ``planes`` pointer is used instead.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - Flags set by the application or driver, see :ref:`buffer-flags`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``field``
+
+ -
+ - Indicates the field order of the image in the buffer, see
+ :ref:`v4l2-field`. This field is not used when the buffer
+ contains VBI data. Drivers must set it when ``type`` refers to a
+ capture stream, applications when it refers to an output stream.
+
+ - .. row 6
+
+ - struct timeval
+
+ - ``timestamp``
+
+ -
+ - For capture streams this is time when the first data byte was
+ captured, as returned by the :c:func:`clock_gettime()` function
+ for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in
+ :ref:`buffer-flags`. For output streams the driver stores the
+ time at which the last data byte was actually sent out in the
+ ``timestamp`` field. This permits applications to monitor the
+ drift between the video and system clock. For output streams that
+ use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill
+ in the timestamp which will be copied by the driver to the capture
+ stream.
+
+ - .. row 7
+
+ - struct :ref:`v4l2_timecode <v4l2-timecode>`
+
+ - ``timecode``
+
+ -
+ - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the
+ ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this
+ structure contains a frame timecode. In
+ :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
+ bottom field contain the same timecode. Timecodes are intended to
+ help video editing and are typically recorded on video tapes, but
+ also embedded in compressed formats like MPEG. This field is
+ independent of the ``timestamp`` and ``sequence`` fields.
+
+ - .. row 8
+
+ - __u32
+
+ - ``sequence``
+
+ -
+ - Set by the driver, counting the frames (not fields!) in sequence.
+ This field is set for both input and output devices.
+
+ - .. row 9
+
+ - :cspan:`3`
+
+ In :ref:`V4L2_FIELD_ALTERNATE <v4l2-field>` mode the top and
+ bottom field have the same sequence number. The count starts at
+ zero and includes dropped or repeated frames. A dropped frame was
+ received by an input device but could not be stored due to lack of
+ free buffer space. A repeated frame was displayed again by an
+ output device because the application did not pass new data in
+ time.
+
+ Note this may count the frames received e.g. over USB, without
+ taking into account the frames dropped by the remote hardware due
+ to limited compression throughput or bus bandwidth. These devices
+ identify by not enumerating any video standards, see
+ :ref:`standard`.
+
+ - .. row 10
+
+ - __u32
+
+ - ``memory``
+
+ -
+ - This field must be set by applications and/or drivers in
+ accordance with the selected I/O method. See :ref:`v4l2-memory`
+
+ - .. row 11
+
+ - union
+
+ - ``m``
+
+ - .. row 12
+
+ -
+ - __u32
+
+ - ``offset``
+
+ - For the single-planar API and when ``memory`` is
+ ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the
+ start of the device memory. The value is returned by the driver
+ and apart of serving as parameter to the
+ :ref:`mmap() <func-mmap>` function not useful for applications.
+ See :ref:`mmap` for details
+
+ - .. row 13
+
+ -
+ - unsigned long
+
+ - ``userptr``
+
+ - For the single-planar API and when ``memory`` is
+ ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to
+ unsigned long type) in virtual memory, set by the application. See
+ :ref:`userp` for details.
+
+ - .. row 14
+
+ -
+ - struct v4l2_plane
+
+ - ``*planes``
+
+ - When using the multi-planar API, contains a userspace pointer to
+ an array of struct :ref:`v4l2_plane <v4l2-plane>`. The size of
+ the array should be put in the ``length`` field of this
+ :ref:`struct v4l2_buffer <v4l2-buffer>` structure.
+
+ - .. row 15
+
+ -
+ - int
+
+ - ``fd``
+
+ - For the single-plane API and when ``memory`` is
+ ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with
+ a DMABUF buffer.
+
+ - .. row 16
+
+ - __u32
+
+ - ``length``
+
+ -
+ - Size of the buffer (not the payload) in bytes for the
+ single-planar API. This is set by the driver based on the calls to
+ :ref:`VIDIOC_REQBUFS` and/or
+ :ref:`VIDIOC_CREATE_BUFS`. For the
+ multi-planar API the application sets this to the number of
+ elements in the ``planes`` array. The driver will fill in the
+ actual number of valid elements in that array.
+
+ - .. row 17
+
+ - __u32
+
+ - ``reserved2``
+
+ -
+ - A place holder for future extensions. Drivers and applications
+ must set this to 0.
+
+ - .. row 18
+
+ - __u32
+
+ - ``reserved``
+
+ -
+ - A place holder for future extensions. Drivers and applications
+ must set this to 0.
+
+
+
+.. _v4l2-plane:
+
+struct v4l2_plane
+=================
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``bytesused``
+
+ -
+ - The number of bytes occupied by data in the plane (its payload).
+ Drivers must set this field when ``type`` refers to a capture
+ stream, applications when it refers to an output stream. If the
+ application sets this to 0 for an output stream, then
+ ``bytesused`` will be set to the size of the plane (see the
+ ``length`` field of this struct) by the driver. Note that the
+ actual image data starts at ``data_offset`` which may not be 0.
+
+ - .. row 2
+
+ - __u32
+
+ - ``length``
+
+ -
+ - Size in bytes of the plane (not its payload). This is set by the
+ driver based on the calls to
+ :ref:`VIDIOC_REQBUFS` and/or
+ :ref:`VIDIOC_CREATE_BUFS`.
+
+ - .. row 3
+
+ - union
+
+ - ``m``
+
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __u32
+
+ - ``mem_offset``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_MMAP``, this
+ is the value that should be passed to :ref:`mmap() <func-mmap>`,
+ similar to the ``offset`` field in struct
+ :ref:`v4l2_buffer <v4l2-buffer>`.
+
+ - .. row 5
+
+ -
+ - unsigned long
+
+ - ``userptr``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_USERPTR``,
+ this is a userspace pointer to the memory allocated for this plane
+ by an application.
+
+ - .. row 6
+
+ -
+ - int
+
+ - ``fd``
+
+ - When the memory type in the containing struct
+ :ref:`v4l2_buffer <v4l2-buffer>` is ``V4L2_MEMORY_DMABUF``,
+ this is a file descriptor associated with a DMABUF buffer, similar
+ to the ``fd`` field in struct :ref:`v4l2_buffer <v4l2-buffer>`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``data_offset``
+
+ -
+ - Offset in bytes to video data in the plane. Drivers must set this
+ field when ``type`` refers to a capture stream, applications when
+ it refers to an output stream. Note that data_offset is included
+ in ``bytesused``. So the size of the image in the plane is
+ ``bytesused``-``data_offset`` at offset ``data_offset`` from the
+ start of the plane.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved[11]``
+
+ -
+ - Reserved for future use. Should be zeroed by drivers and
+ applications.
+
+
+
+.. _v4l2-buf-type:
+
+enum v4l2_buf_type
+==================
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
+
+ - 1
+
+ - Buffer of a single-planar video capture stream, see
+ :ref:`capture`.
+
+ - .. row 2
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``
+
+ - 9
+
+ - Buffer of a multi-planar video capture stream, see
+ :ref:`capture`.
+
+ - .. row 3
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+
+ - 2
+
+ - Buffer of a single-planar video output stream, see
+ :ref:`output`.
+
+ - .. row 4
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
+
+ - 10
+
+ - Buffer of a multi-planar video output stream, see :ref:`output`.
+
+ - .. row 5
+
+ - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
+
+ - 3
+
+ - Buffer for video overlay, see :ref:`overlay`.
+
+ - .. row 6
+
+ - ``V4L2_BUF_TYPE_VBI_CAPTURE``
+
+ - 4
+
+ - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`.
+
+ - .. row 7
+
+ - ``V4L2_BUF_TYPE_VBI_OUTPUT``
+
+ - 5
+
+ - Buffer of a raw VBI output stream, see :ref:`raw-vbi`.
+
+ - .. row 8
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
+
+ - 6
+
+ - Buffer of a sliced VBI capture stream, see :ref:`sliced`.
+
+ - .. row 9
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
+
+ - 7
+
+ - Buffer of a sliced VBI output stream, see :ref:`sliced`.
+
+ - .. row 10
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``
+
+ - 8
+
+ - Buffer for video output overlay (OSD), see :ref:`osd`.
+
+ - .. row 11
+
+ - ``V4L2_BUF_TYPE_SDR_CAPTURE``
+
+ - 11
+
+ - Buffer for Software Defined Radio (SDR) capture stream, see
+ :ref:`sdr`.
+
+ - .. row 12
+
+ - ``V4L2_BUF_TYPE_SDR_OUTPUT``
+
+ - 12
+
+ - Buffer for Software Defined Radio (SDR) output stream, see
+ :ref:`sdr`.
+
+
+
+.. _buffer-flags:
+
+Buffer Flags
+============
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BUF_FLAG_MAPPED``
+
+ - 0x00000001
+
+ - The buffer resides in device memory and has been mapped into the
+ application's address space, see :ref:`mmap` for details.
+ Drivers set or clear this flag when the
+ :ref:`VIDIOC_QUERYBUF`,
+ :ref:`VIDIOC_QBUF` or
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Set by the
+ driver.
+
+ - .. row 2
+
+ - ``V4L2_BUF_FLAG_QUEUED``
+
+ - 0x00000002
+
+ - Internally drivers maintain two buffer queues, an incoming and
+ outgoing queue. When this flag is set, the buffer is currently on
+ the incoming queue. It automatically moves to the outgoing queue
+ after the buffer has been filled (capture devices) or displayed
+ (output devices). Drivers set or clear this flag when the
+ ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling
+ the ``VIDIOC_QBUF``\ ioctl it is always set and after
+ ``VIDIOC_DQBUF`` always cleared.
+
+ - .. row 3
+
+ - ``V4L2_BUF_FLAG_DONE``
+
+ - 0x00000004
+
+ - When this flag is set, the buffer is currently on the outgoing
+ queue, ready to be dequeued from the driver. Drivers set or clear
+ this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After
+ calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always
+ cleared. Of course a buffer cannot be on both queues at the same
+ time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag
+ are mutually exclusive. They can be both cleared however, then the
+ buffer is in "dequeued" state, in the application domain so to
+ say.
+
+ - .. row 4
+
+ - ``V4L2_BUF_FLAG_ERROR``
+
+ - 0x00000040
+
+ - When this flag is set, the buffer has been dequeued successfully,
+ although the data might have been corrupted. This is recoverable,
+ streaming may continue as normal and the buffer may be reused
+ normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is
+ called.
+
+ - .. row 5
+
+ - ``V4L2_BUF_FLAG_KEYFRAME``
+
+ - 0x00000008
+
+ - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF``
+ ioctl. It may be set by video capture devices when the buffer
+ contains a compressed image which is a key frame (or field), i. e.
+ can be decompressed on its own. Also known as an I-frame.
+ Applications can set this bit when ``type`` refers to an output
+ stream.
+
+ - .. row 6
+
+ - ``V4L2_BUF_FLAG_PFRAME``
+
+ - 0x00000010
+
+ - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames
+ or fields which contain only differences to a previous key frame.
+ Applications can set this bit when ``type`` refers to an output
+ stream.
+
+ - .. row 7
+
+ - ``V4L2_BUF_FLAG_BFRAME``
+
+ - 0x00000020
+
+ - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional
+ predicted frame or field which contains only the differences
+ between the current frame and both the preceding and following key
+ frames to specify its content. Applications can set this bit when
+ ``type`` refers to an output stream.
+
+ - .. row 8
+
+ - ``V4L2_BUF_FLAG_TIMECODE``
+
+ - 0x00000100
+
+ - The ``timecode`` field is valid. Drivers set or clear this flag
+ when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set
+ this bit and the corresponding ``timecode`` structure when
+ ``type`` refers to an output stream.
+
+ - .. row 9
+
+ - ``V4L2_BUF_FLAG_PREPARED``
+
+ - 0x00000400
+
+ - The buffer has been prepared for I/O and can be queued by the
+ application. Drivers set or clear this flag when the
+ :ref:`VIDIOC_QUERYBUF`,
+ :ref:`VIDIOC_PREPARE_BUF <VIDIOC_QBUF>`,
+ :ref:`VIDIOC_QBUF` or
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called.
+
+ - .. row 10
+
+ - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE``
+
+ - 0x00000800
+
+ - Caches do not have to be invalidated for this buffer. Typically
+ applications shall use this flag if the data captured in the
+ buffer is not going to be touched by the CPU, instead the buffer
+ will, probably, be passed on to a DMA-capable hardware unit for
+ further processing or output.
+
+ - .. row 11
+
+ - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN``
+
+ - 0x00001000
+
+ - Caches do not have to be cleaned for this buffer. Typically
+ applications shall use this flag for output buffers if the data in
+ this buffer has not been created by the CPU but by some
+ DMA-capable unit, in which case caches have not been used.
+
+ - .. row 12
+
+ - ``V4L2_BUF_FLAG_LAST``
+
+ - 0x00100000
+
+ - Last buffer produced by the hardware. mem2mem codec drivers set
+ this flag on the capture queue for the last buffer when the
+ :ref:`VIDIOC_QUERYBUF` or
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl is called. Due to
+ hardware limitations, the last buffer may be empty. In this case
+ the driver will set the ``bytesused`` field to 0, regardless of
+ the format. Any Any subsequent call to the
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
+ but return an ``EPIPE`` error code.
+
+ - .. row 13
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_MASK``
+
+ - 0x0000e000
+
+ - Mask for timestamp types below. To test the timestamp type, mask
+ out bits not belonging to timestamp type by performing a logical
+ and operation with buffer flags and timestamp mask.
+
+ - .. row 14
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN``
+
+ - 0x00000000
+
+ - Unknown timestamp type. This type is used by drivers before Linux
+ 3.9 and may be either monotonic (see below) or realtime (wall
+ clock). Monotonic clock has been favoured in embedded systems
+ whereas most of the drivers use the realtime clock. Either kinds
+ of timestamps are available in user space via
+ :c:func:`clock_gettime(2)` using clock IDs ``CLOCK_MONOTONIC``
+ and ``CLOCK_REALTIME``, respectively.
+
+ - .. row 15
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC``
+
+ - 0x00002000
+
+ - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC``
+ clock. To access the same clock outside V4L2, use
+ :c:func:`clock_gettime(2)`.
+
+ - .. row 16
+
+ - ``V4L2_BUF_FLAG_TIMESTAMP_COPY``
+
+ - 0x00004000
+
+ - The CAPTURE buffer timestamp has been taken from the corresponding
+ OUTPUT buffer. This flag applies only to mem2mem devices.
+
+ - .. row 17
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK``
+
+ - 0x00070000
+
+ - Mask for timestamp sources below. The timestamp source defines the
+ point of time the timestamp is taken in relation to the frame.
+ Logical 'and' operation between the ``flags`` field and
+ ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the
+ timestamp source. Applications must set the timestamp source when
+ ``type`` refers to an output stream and
+ ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set.
+
+ - .. row 18
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF``
+
+ - 0x00000000
+
+ - End Of Frame. The buffer timestamp has been taken when the last
+ pixel of the frame has been received or the last pixel of the
+ frame has been transmitted. In practice, software generated
+ timestamps will typically be read from the clock a small amount of
+ time after the last pixel has been received or transmitten,
+ depending on the system and other activity in it.
+
+ - .. row 19
+
+ - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE``
+
+ - 0x00010000
+
+ - Start Of Exposure. The buffer timestamp has been taken when the
+ exposure of the frame has begun. This is only valid for the
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type.
+
+
+
+.. _v4l2-memory:
+
+enum v4l2_memory
+================
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_MEMORY_MMAP``
+
+ - 1
+
+ - The buffer is used for :ref:`memory mapping <mmap>` I/O.
+
+ - .. row 2
+
+ - ``V4L2_MEMORY_USERPTR``
+
+ - 2
+
+ - The buffer is used for :ref:`user pointer <userp>` I/O.
+
+ - .. row 3
+
+ - ``V4L2_MEMORY_OVERLAY``
+
+ - 3
+
+ - [to do]
+
+ - .. row 4
+
+ - ``V4L2_MEMORY_DMABUF``
+
+ - 4
+
+ - The buffer is used for :ref:`DMA shared buffer <dmabuf>` I/O.
+
+
+
+Timecodes
+=========
+
+The :ref:`struct v4l2_timecode <v4l2-timecode>` structure is designed to hold a
+:ref:`smpte12m` or similar timecode. (struct
+:c:type:`struct timeval` timestamps are stored in struct
+:ref:`v4l2_buffer <v4l2-buffer>` field ``timestamp``.)
+
+
+.. _v4l2-timecode:
+
+struct v4l2_timecode
+--------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Frame rate the timecodes are based on, see :ref:`timecode-type`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ - Timecode flags, see :ref:`timecode-flags`.
+
+ - .. row 3
+
+ - __u8
+
+ - ``frames``
+
+ - Frame count, 0 ... 23/24/29/49/59, depending on the type of
+ timecode.
+
+ - .. row 4
+
+ - __u8
+
+ - ``seconds``
+
+ - Seconds count, 0 ... 59. This is a binary, not BCD number.
+
+ - .. row 5
+
+ - __u8
+
+ - ``minutes``
+
+ - Minutes count, 0 ... 59. This is a binary, not BCD number.
+
+ - .. row 6
+
+ - __u8
+
+ - ``hours``
+
+ - Hours count, 0 ... 29. This is a binary, not BCD number.
+
+ - .. row 7
+
+ - __u8
+
+ - ``userbits``\ [4]
+
+ - The "user group" bits from the timecode.
+
+
+
+.. _timecode-type:
+
+Timecode Types
+--------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TC_TYPE_24FPS``
+
+ - 1
+
+ - 24 frames per second, i. e. film.
+
+ - .. row 2
+
+ - ``V4L2_TC_TYPE_25FPS``
+
+ - 2
+
+ - 25 frames per second, i. e. PAL or SECAM video.
+
+ - .. row 3
+
+ - ``V4L2_TC_TYPE_30FPS``
+
+ - 3
+
+ - 30 frames per second, i. e. NTSC video.
+
+ - .. row 4
+
+ - ``V4L2_TC_TYPE_50FPS``
+
+ - 4
+
+ -
+
+ - .. row 5
+
+ - ``V4L2_TC_TYPE_60FPS``
+
+ - 5
+
+ -
+
+
+
+.. _timecode-flags:
+
+Timecode Flags
+--------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TC_FLAG_DROPFRAME``
+
+ - 0x0001
+
+ - Indicates "drop frame" semantics for counting frames in 29.97 fps
+ material. When set, frame numbers 0 and 1 at the start of each
+ minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
+ count.
+
+ - .. row 2
+
+ - ``V4L2_TC_FLAG_COLORFRAME``
+
+ - 0x0002
+
+ - The "color frame" flag.
+
+ - .. row 3
+
+ - ``V4L2_TC_USERBITS_field``
+
+ - 0x000C
+
+ - Field mask for the "binary group flags".
+
+ - .. row 4
+
+ - ``V4L2_TC_USERBITS_USERDEFINED``
+
+ - 0x0000
+
+ - Unspecified format.
+
+ - .. row 5
+
+ - ``V4L2_TC_USERBITS_8BITCHARS``
+
+ - 0x0008
+
+ - 8-bit ISO characters.
diff --git a/Documentation/media/uapi/v4l/capture-example.rst b/Documentation/media/uapi/v4l/capture-example.rst
new file mode 100644
index 000000000000..ac1cd057e25b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/capture-example.rst
@@ -0,0 +1,13 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _capture-example:
+
+*********************
+Video Capture Example
+*********************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ capture.c
diff --git a/Documentation/media/uapi/v4l/capture.c.rst b/Documentation/media/uapi/v4l/capture.c.rst
new file mode 100644
index 000000000000..56525a0fb2fa
--- /dev/null
+++ b/Documentation/media/uapi/v4l/capture.c.rst
@@ -0,0 +1,664 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+file: media/v4l/capture.c
+=========================
+
+.. code-block:: c
+
+ /*
+ * V4L2 video capture example
+ *
+ * This program can be used and distributed without restrictions.
+ *
+ * This program is provided with the V4L2 API
+ * see https://linuxtv.org/docs.php for more information
+ */
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <assert.h>
+
+ #include <getopt.h> /* getopt_long() */
+
+ #include <fcntl.h> /* low-level i/o */
+ #include <unistd.h>
+ #include <errno.h>
+ #include <sys/stat.h>
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/mman.h>
+ #include <sys/ioctl.h>
+
+ #include <linux/videodev2.h>
+
+ #define CLEAR(x) memset(&(x), 0, sizeof(x))
+
+ enum io_method {
+ IO_METHOD_READ,
+ IO_METHOD_MMAP,
+ IO_METHOD_USERPTR,
+ };
+
+ struct buffer {
+ void *start;
+ size_t length;
+ };
+
+ static char *dev_name;
+ static enum io_method io = IO_METHOD_MMAP;
+ static int fd = -1;
+ struct buffer *buffers;
+ static unsigned int n_buffers;
+ static int out_buf;
+ static int force_format;
+ static int frame_count = 70;
+
+ static void errno_exit(const char *s)
+ {
+ fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ static int xioctl(int fh, int request, void *arg)
+ {
+ int r;
+
+ do {
+ r = ioctl(fh, request, arg);
+ } while (-1 == r && EINTR == errno);
+
+ return r;
+ }
+
+ static void process_image(const void *p, int size)
+ {
+ if (out_buf)
+ fwrite(p, size, 1, stdout);
+
+ fflush(stderr);
+ fprintf(stderr, ".");
+ fflush(stdout);
+ }
+
+ static int read_frame(void)
+ {
+ struct v4l2_buffer buf;
+ unsigned int i;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("read");
+ }
+ }
+
+ process_image(buffers[0].start, buffers[0].length);
+ break;
+
+ case IO_METHOD_MMAP:
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+
+ if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("VIDIOC_DQBUF");
+ }
+ }
+
+ assert(buf.index < n_buffers);
+
+ process_image(buffers[buf.index].start, buf.bytesused);
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ break;
+
+ case IO_METHOD_USERPTR:
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_USERPTR;
+
+ if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) {
+ switch (errno) {
+ case EAGAIN:
+ return 0;
+
+ case EIO:
+ /* Could ignore EIO, see spec. */
+
+ /* fall through */
+
+ default:
+ errno_exit("VIDIOC_DQBUF");
+ }
+ }
+
+ for (i = 0; i < n_buffers; ++i)
+ if (buf.m.userptr == (unsigned long)buffers[i].start
+ && buf.length == buffers[i].length)
+ break;
+
+ assert(i < n_buffers);
+
+ process_image((void *)buf.m.userptr, buf.bytesused);
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ break;
+ }
+
+ return 1;
+ }
+
+ static void mainloop(void)
+ {
+ unsigned int count;
+
+ count = frame_count;
+
+ while (count-- > 0) {
+ for (;;) {
+ fd_set fds;
+ struct timeval tv;
+ int r;
+
+ FD_ZERO(&fds);
+ FD_SET(fd, &fds);
+
+ /* Timeout. */
+ tv.tv_sec = 2;
+ tv.tv_usec = 0;
+
+ r = select(fd + 1, &fds, NULL, NULL, &tv);
+
+ if (-1 == r) {
+ if (EINTR == errno)
+ continue;
+ errno_exit("select");
+ }
+
+ if (0 == r) {
+ fprintf(stderr, "select timeout\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ if (read_frame())
+ break;
+ /* EAGAIN - continue select loop. */
+ }
+ }
+ }
+
+ static void stop_capturing(void)
+ {
+ enum v4l2_buf_type type;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ /* Nothing to do. */
+ break;
+
+ case IO_METHOD_MMAP:
+ case IO_METHOD_USERPTR:
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type))
+ errno_exit("VIDIOC_STREAMOFF");
+ break;
+ }
+ }
+
+ static void start_capturing(void)
+ {
+ unsigned int i;
+ enum v4l2_buf_type type;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ /* Nothing to do. */
+ break;
+
+ case IO_METHOD_MMAP:
+ for (i = 0; i < n_buffers; ++i) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = i;
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
+ errno_exit("VIDIOC_STREAMON");
+ break;
+
+ case IO_METHOD_USERPTR:
+ for (i = 0; i < n_buffers; ++i) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_USERPTR;
+ buf.index = i;
+ buf.m.userptr = (unsigned long)buffers[i].start;
+ buf.length = buffers[i].length;
+
+ if (-1 == xioctl(fd, VIDIOC_QBUF, &buf))
+ errno_exit("VIDIOC_QBUF");
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (-1 == xioctl(fd, VIDIOC_STREAMON, &type))
+ errno_exit("VIDIOC_STREAMON");
+ break;
+ }
+ }
+
+ static void uninit_device(void)
+ {
+ unsigned int i;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ free(buffers[0].start);
+ break;
+
+ case IO_METHOD_MMAP:
+ for (i = 0; i < n_buffers; ++i)
+ if (-1 == munmap(buffers[i].start, buffers[i].length))
+ errno_exit("munmap");
+ break;
+
+ case IO_METHOD_USERPTR:
+ for (i = 0; i < n_buffers; ++i)
+ free(buffers[i].start);
+ break;
+ }
+
+ free(buffers);
+ }
+
+ static void init_read(unsigned int buffer_size)
+ {
+ buffers = calloc(1, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers[0].length = buffer_size;
+ buffers[0].start = malloc(buffer_size);
+
+ if (!buffers[0].start) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ static void init_mmap(void)
+ {
+ struct v4l2_requestbuffers req;
+
+ CLEAR(req);
+
+ req.count = 4;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_MMAP;
+
+ if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s does not support "
+ "memory mappingn", dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_REQBUFS");
+ }
+ }
+
+ if (req.count < 2) {
+ fprintf(stderr, "Insufficient buffer memory on %s\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(req.count, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
+ struct v4l2_buffer buf;
+
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = n_buffers;
+
+ if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf))
+ errno_exit("VIDIOC_QUERYBUF");
+
+ buffers[n_buffers].length = buf.length;
+ buffers[n_buffers].start =
+ mmap(NULL /* start anywhere */,
+ buf.length,
+ PROT_READ | PROT_WRITE /* required */,
+ MAP_SHARED /* recommended */,
+ fd, buf.m.offset);
+
+ if (MAP_FAILED == buffers[n_buffers].start)
+ errno_exit("mmap");
+ }
+ }
+
+ static void init_userp(unsigned int buffer_size)
+ {
+ struct v4l2_requestbuffers req;
+
+ CLEAR(req);
+
+ req.count = 4;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_USERPTR;
+
+ if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s does not support "
+ "user pointer i/on", dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_REQBUFS");
+ }
+ }
+
+ buffers = calloc(4, sizeof(*buffers));
+
+ if (!buffers) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ for (n_buffers = 0; n_buffers < 4; ++n_buffers) {
+ buffers[n_buffers].length = buffer_size;
+ buffers[n_buffers].start = malloc(buffer_size);
+
+ if (!buffers[n_buffers].start) {
+ fprintf(stderr, "Out of memory\\n");
+ exit(EXIT_FAILURE);
+ }
+ }
+ }
+
+ static void init_device(void)
+ {
+ struct v4l2_capability cap;
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+ struct v4l2_format fmt;
+ unsigned int min;
+
+ if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) {
+ if (EINVAL == errno) {
+ fprintf(stderr, "%s is no V4L2 device\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ } else {
+ errno_exit("VIDIOC_QUERYCAP");
+ }
+ }
+
+ if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) {
+ fprintf(stderr, "%s is no video capture device\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ switch (io) {
+ case IO_METHOD_READ:
+ if (!(cap.capabilities & V4L2_CAP_READWRITE)) {
+ fprintf(stderr, "%s does not support read i/o\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+ break;
+
+ case IO_METHOD_MMAP:
+ case IO_METHOD_USERPTR:
+ if (!(cap.capabilities & V4L2_CAP_STREAMING)) {
+ fprintf(stderr, "%s does not support streaming i/o\\n",
+ dev_name);
+ exit(EXIT_FAILURE);
+ }
+ break;
+ }
+
+
+ /* Select video input, video standard and tune here. */
+
+
+ CLEAR(cropcap);
+
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) {
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ crop.c = cropcap.defrect; /* reset to default */
+
+ if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) {
+ switch (errno) {
+ case EINVAL:
+ /* Cropping not supported. */
+ break;
+ default:
+ /* Errors ignored. */
+ break;
+ }
+ }
+ } else {
+ /* Errors ignored. */
+ }
+
+
+ CLEAR(fmt);
+
+ fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ if (force_format) {
+ fmt.fmt.pix.width = 640;
+ fmt.fmt.pix.height = 480;
+ fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
+ fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
+
+ if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt))
+ errno_exit("VIDIOC_S_FMT");
+
+ /* Note VIDIOC_S_FMT may change width and height. */
+ } else {
+ /* Preserve original settings as set by v4l2-ctl for example */
+ if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt))
+ errno_exit("VIDIOC_G_FMT");
+ }
+
+ /* Buggy driver paranoia. */
+ min = fmt.fmt.pix.width * 2;
+ if (fmt.fmt.pix.bytesperline < min)
+ fmt.fmt.pix.bytesperline = min;
+ min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
+ if (fmt.fmt.pix.sizeimage < min)
+ fmt.fmt.pix.sizeimage = min;
+
+ switch (io) {
+ case IO_METHOD_READ:
+ init_read(fmt.fmt.pix.sizeimage);
+ break;
+
+ case IO_METHOD_MMAP:
+ init_mmap();
+ break;
+
+ case IO_METHOD_USERPTR:
+ init_userp(fmt.fmt.pix.sizeimage);
+ break;
+ }
+ }
+
+ static void close_device(void)
+ {
+ if (-1 == close(fd))
+ errno_exit("close");
+
+ fd = -1;
+ }
+
+ static void open_device(void)
+ {
+ struct stat st;
+
+ if (-1 == stat(dev_name, &st)) {
+ fprintf(stderr, "Cannot identify '%s': %d, %s\\n",
+ dev_name, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+
+ if (!S_ISCHR(st.st_mode)) {
+ fprintf(stderr, "%s is no devicen", dev_name);
+ exit(EXIT_FAILURE);
+ }
+
+ fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
+
+ if (-1 == fd) {
+ fprintf(stderr, "Cannot open '%s': %d, %s\\n",
+ dev_name, errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ static void usage(FILE *fp, int argc, char **argv)
+ {
+ fprintf(fp,
+ "Usage: %s [options]\\n\\n"
+ "Version 1.3\\n"
+ "Options:\\n"
+ "-d | --device name Video device name [%s]n"
+ "-h | --help Print this messagen"
+ "-m | --mmap Use memory mapped buffers [default]n"
+ "-r | --read Use read() callsn"
+ "-u | --userp Use application allocated buffersn"
+ "-o | --output Outputs stream to stdoutn"
+ "-f | --format Force format to 640x480 YUYVn"
+ "-c | --count Number of frames to grab [%i]n"
+ "",
+ argv[0], dev_name, frame_count);
+ }
+
+ static const char short_options[] = "d:hmruofc:";
+
+ static const struct option
+ long_options[] = {
+ { "device", required_argument, NULL, 'd' },
+ { "help", no_argument, NULL, 'h' },
+ { "mmap", no_argument, NULL, 'm' },
+ { "read", no_argument, NULL, 'r' },
+ { "userp", no_argument, NULL, 'u' },
+ { "output", no_argument, NULL, 'o' },
+ { "format", no_argument, NULL, 'f' },
+ { "count", required_argument, NULL, 'c' },
+ { 0, 0, 0, 0 }
+ };
+
+ int main(int argc, char **argv)
+ {
+ dev_name = "/dev/video0";
+
+ for (;;) {
+ int idx;
+ int c;
+
+ c = getopt_long(argc, argv,
+ short_options, long_options, &idx);
+
+ if (-1 == c)
+ break;
+
+ switch (c) {
+ case 0: /* getopt_long() flag */
+ break;
+
+ case 'd':
+ dev_name = optarg;
+ break;
+
+ case 'h':
+ usage(stdout, argc, argv);
+ exit(EXIT_SUCCESS);
+
+ case 'm':
+ io = IO_METHOD_MMAP;
+ break;
+
+ case 'r':
+ io = IO_METHOD_READ;
+ break;
+
+ case 'u':
+ io = IO_METHOD_USERPTR;
+ break;
+
+ case 'o':
+ out_buf++;
+ break;
+
+ case 'f':
+ force_format++;
+ break;
+
+ case 'c':
+ errno = 0;
+ frame_count = strtol(optarg, NULL, 0);
+ if (errno)
+ errno_exit(optarg);
+ break;
+
+ default:
+ usage(stderr, argc, argv);
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ open_device();
+ init_device();
+ start_capturing();
+ mainloop();
+ stop_capturing();
+ uninit_device();
+ close_device();
+ fprintf(stderr, "\\n");
+ return 0;
+ }
diff --git a/Documentation/media/uapi/v4l/colorspaces.rst b/Documentation/media/uapi/v4l/colorspaces.rst
new file mode 100644
index 000000000000..322eb94c1d44
--- /dev/null
+++ b/Documentation/media/uapi/v4l/colorspaces.rst
@@ -0,0 +1,163 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _colorspaces:
+
+***********
+Colorspaces
+***********
+
+'Color' is a very complex concept and depends on physics, chemistry and
+biology. Just because you have three numbers that describe the 'red',
+'green' and 'blue' components of the color of a pixel does not mean that
+you can accurately display that color. A colorspace defines what it
+actually *means* to have an RGB value of e.g. (255, 0, 0). That is,
+which color should be reproduced on the screen in a perfectly calibrated
+environment.
+
+In order to do that we first need to have a good definition of color,
+i.e. some way to uniquely and unambiguously define a color so that
+someone else can reproduce it. Human color vision is trichromatic since
+the human eye has color receptors that are sensitive to three different
+wavelengths of light. Hence the need to use three numbers to describe
+color. Be glad you are not a mantis shrimp as those are sensitive to 12
+different wavelengths, so instead of RGB we would be using the
+ABCDEFGHIJKL colorspace...
+
+Color exists only in the eye and brain and is the result of how strongly
+color receptors are stimulated. This is based on the Spectral Power
+Distribution (SPD) which is a graph showing the intensity (radiant
+power) of the light at wavelengths covering the visible spectrum as it
+enters the eye. The science of colorimetry is about the relationship
+between the SPD and color as perceived by the human brain.
+
+Since the human eye has only three color receptors it is perfectly
+possible that different SPDs will result in the same stimulation of
+those receptors and are perceived as the same color, even though the SPD
+of the light is different.
+
+In the 1920s experiments were devised to determine the relationship
+between SPDs and the perceived color and that resulted in the CIE 1931
+standard that defines spectral weighting functions that model the
+perception of color. Specifically that standard defines functions that
+can take an SPD and calculate the stimulus for each color receptor.
+After some further mathematical transforms these stimuli are known as
+the *CIE XYZ tristimulus* values and these X, Y and Z values describe a
+color as perceived by a human unambiguously. These X, Y and Z values are
+all in the range [0…1].
+
+The Y value in the CIE XYZ colorspace corresponds to luminance. Often
+the CIE XYZ colorspace is transformed to the normalized CIE xyY
+colorspace:
+
+x = X / (X + Y + Z)
+
+y = Y / (X + Y + Z)
+
+The x and y values are the chromaticity coordinates and can be used to
+define a color without the luminance component Y. It is very confusing
+to have such similar names for these colorspaces. Just be aware that if
+colors are specified with lower case 'x' and 'y', then the CIE xyY
+colorspace is used. Upper case 'X' and 'Y' refer to the CIE XYZ
+colorspace. Also, y has nothing to do with luminance. Together x and y
+specify a color, and Y the luminance. That is really all you need to
+remember from a practical point of view. At the end of this section you
+will find reading resources that go into much more detail if you are
+interested.
+
+A monitor or TV will reproduce colors by emitting light at three
+different wavelengths, the combination of which will stimulate the color
+receptors in the eye and thus cause the perception of color.
+Historically these wavelengths were defined by the red, green and blue
+phosphors used in the displays. These *color primaries* are part of what
+defines a colorspace.
+
+Different display devices will have different primaries and some
+primaries are more suitable for some display technologies than others.
+This has resulted in a variety of colorspaces that are used for
+different display technologies or uses. To define a colorspace you need
+to define the three color primaries (these are typically defined as x, y
+chromaticity coordinates from the CIE xyY colorspace) but also the white
+reference: that is the color obtained when all three primaries are at
+maximum power. This determines the relative power or energy of the
+primaries. This is usually chosen to be close to daylight which has been
+defined as the CIE D65 Illuminant.
+
+To recapitulate: the CIE XYZ colorspace uniquely identifies colors.
+Other colorspaces are defined by three chromaticity coordinates defined
+in the CIE xyY colorspace. Based on those a 3x3 matrix can be
+constructed that transforms CIE XYZ colors to colors in the new
+colorspace.
+
+Both the CIE XYZ and the RGB colorspace that are derived from the
+specific chromaticity primaries are linear colorspaces. But neither the
+eye, nor display technology is linear. Doubling the values of all
+components in the linear colorspace will not be perceived as twice the
+intensity of the color. So each colorspace also defines a transfer
+function that takes a linear color component value and transforms it to
+the non-linear component value, which is a closer match to the
+non-linear performance of both the eye and displays. Linear component
+values are denoted RGB, non-linear are denoted as R'G'B'. In general
+colors used in graphics are all R'G'B', except in openGL which uses
+linear RGB. Special care should be taken when dealing with openGL to
+provide linear RGB colors or to use the built-in openGL support to apply
+the inverse transfer function.
+
+The final piece that defines a colorspace is a function that transforms
+non-linear R'G'B' to non-linear Y'CbCr. This function is determined by
+the so-called luma coefficients. There may be multiple possible Y'CbCr
+encodings allowed for the same colorspace. Many encodings of color
+prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the
+human eye is more sensitive to differences in luminance than in color
+this encoding allows one to reduce the amount of color information
+compared to the luma data. Note that the luma (Y') is unrelated to the Y
+in the CIE XYZ colorspace. Also note that Y'CbCr is often called YCbCr
+or YUV even though these are strictly speaking wrong.
+
+Sometimes people confuse Y'CbCr as being a colorspace. This is not
+correct, it is just an encoding of an R'G'B' color into luma and chroma
+values. The underlying colorspace that is associated with the R'G'B'
+color is also associated with the Y'CbCr color.
+
+The final step is how the RGB, R'G'B' or Y'CbCr values are quantized.
+The CIE XYZ colorspace where X, Y and Z are in the range [0…1] describes
+all colors that humans can perceive, but the transform to another
+colorspace will produce colors that are outside the [0…1] range. Once
+clamped to the [0…1] range those colors can no longer be reproduced in
+that colorspace. This clamping is what reduces the extent or gamut of
+the colorspace. How the range of [0…1] is translated to integer values
+in the range of [0…255] (or higher, depending on the color depth) is
+called the quantization. This is *not* part of the colorspace
+definition. In practice RGB or R'G'B' values are full range, i.e. they
+use the full [0…255] range. Y'CbCr values on the other hand are limited
+range with Y' using [16…235] and Cb and Cr using [16…240].
+
+Unfortunately, in some cases limited range RGB is also used where the
+components use the range [16…235]. And full range Y'CbCr also exists
+using the [0…255] range.
+
+In order to correctly interpret a color you need to know the
+quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr
+encoding and the colorspace. From that information you can calculate the
+corresponding CIE XYZ color and map that again to whatever colorspace
+your display device uses.
+
+The colorspace definition itself consists of the three chromaticity
+primaries, the white reference chromaticity, a transfer function and the
+luma coefficients needed to transform R'G'B' to Y'CbCr. While some
+colorspace standards correctly define all four, quite often the
+colorspace standard only defines some, and you have to rely on other
+standards for the missing pieces. The fact that colorspaces are often a
+mix of different standards also led to very confusing naming conventions
+where the name of a standard was used to name a colorspace when in fact
+that standard was part of various other colorspaces as well.
+
+If you want to read more about colors and colorspaces, then the
+following resources are useful: :ref:`poynton` is a good practical
+book for video engineers, :ref:`colimg` has a much broader scope and
+describes many more aspects of color (physics, chemistry, biology,
+etc.). The
+`http://www.brucelindbloom.com <http://www.brucelindbloom.com>`__
+website is an excellent resource, especially with respect to the
+mathematics behind colorspace conversions. The wikipedia
+`CIE 1931 colorspace <http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space>`__
+article is also very useful.
diff --git a/Documentation/media/uapi/v4l/common-defs.rst b/Documentation/media/uapi/v4l/common-defs.rst
new file mode 100644
index 000000000000..39058216b630
--- /dev/null
+++ b/Documentation/media/uapi/v4l/common-defs.rst
@@ -0,0 +1,13 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _common-defs:
+
+******************************************************
+Common definitions for V4L2 and V4L2 subdev interfaces
+******************************************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ selections-common
diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst
new file mode 100644
index 000000000000..13f2ed3fc5a6
--- /dev/null
+++ b/Documentation/media/uapi/v4l/common.rst
@@ -0,0 +1,46 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _common:
+
+###################
+Common API Elements
+###################
+Programming a V4L2 device consists of these steps:
+
+- Opening the device
+
+- Changing device properties, selecting a video and audio input, video
+ standard, picture brightness a. o.
+
+- Negotiating a data format
+
+- Negotiating an input/output method
+
+- The actual input/output loop
+
+- Closing the device
+
+In practice most steps are optional and can be executed out of order. It
+depends on the V4L2 device type, you can read about the details in
+:ref:`devices`. In this chapter we will discuss the basic concepts
+applicable to all devices.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ open
+ querycap
+ app-pri
+ video
+ audio
+ tuner
+ standard
+ dv-timings
+ control
+ extended-controls
+ format
+ planar-apis
+ crop
+ selection-api
+ streaming-par
diff --git a/Documentation/media/uapi/v4l/compat.rst b/Documentation/media/uapi/v4l/compat.rst
new file mode 100644
index 000000000000..8b5e1cebd8f4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/compat.rst
@@ -0,0 +1,18 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _compat:
+
+*******
+Changes
+*******
+
+The following chapters document the evolution of the V4L2 API, errata or
+extensions. They are also intended to help application and driver
+writers to port or update their code.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ diff-v4l
+ hist-v4l2
diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst
new file mode 100644
index 000000000000..6cf218ab36fb
--- /dev/null
+++ b/Documentation/media/uapi/v4l/control.rst
@@ -0,0 +1,533 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _control:
+
+*************
+User Controls
+*************
+
+Devices typically have a number of user-settable controls such as
+brightness, saturation and so on, which would be presented to the user
+on a graphical user interface. But, different devices will have
+different controls available, and furthermore, the range of possible
+values, and the default value will vary from device to device. The
+control ioctls provide the information and a mechanism to create a nice
+user interface for these controls that will work correctly with any
+device.
+
+All controls are accessed using an ID value. V4L2 defines several IDs
+for specific purposes. Drivers can also implement their own custom
+controls using ``V4L2_CID_PRIVATE_BASE`` [1]_ and higher values. The
+pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in
+:ref:`control-id`. The ID is used when querying the attributes of a
+control, and when getting or setting the current value.
+
+Generally applications should present controls to the user without
+assumptions about their purpose. Each control comes with a name string
+the user is supposed to understand. When the purpose is non-intuitive
+the driver writer should provide a user manual, a user interface plug-in
+or a driver specific panel application. Predefined IDs were introduced
+to change a few controls programmatically, for example to mute a device
+during a channel switch.
+
+Drivers may enumerate different controls after switching the current
+video input or output, tuner or modulator, or audio input or output.
+Different in the sense of other bounds, another default and current
+value, step size or other menu items. A control with a certain *custom*
+ID can also change name and type.
+
+If a control is not applicable to the current configuration of the
+device (for example, it doesn't apply to the current video input)
+drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag.
+
+Control values are stored globally, they do not change when switching
+except to stay within the reported bounds. They also do not change e. g.
+when the device is opened or closed, when the tuner radio frequency is
+changed or generally never without application request.
+
+V4L2 specifies an event mechanism to notify applications when controls
+change value (see
+:ref:`VIDIOC_SUBSCRIBE_EVENT`, event
+``V4L2_EVENT_CTRL``), panel applications might want to make use of that
+in order to always reflect the correct control value.
+
+All controls use machine endianness.
+
+
+.. _control-id:
+
+Control IDs
+===========
+
+``V4L2_CID_BASE``
+ First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``.
+
+``V4L2_CID_USER_BASE``
+ Synonym of ``V4L2_CID_BASE``.
+
+``V4L2_CID_BRIGHTNESS`` ``(integer)``
+ Picture brightness, or more precisely, the black level.
+
+``V4L2_CID_CONTRAST`` ``(integer)``
+ Picture contrast or luma gain.
+
+``V4L2_CID_SATURATION`` ``(integer)``
+ Picture color saturation or chroma gain.
+
+``V4L2_CID_HUE`` ``(integer)``
+ Hue or color balance.
+
+``V4L2_CID_AUDIO_VOLUME`` ``(integer)``
+ Overall audio volume. Note some drivers also provide an OSS or ALSA
+ mixer interface.
+
+``V4L2_CID_AUDIO_BALANCE`` ``(integer)``
+ Audio stereo balance. Minimum corresponds to all the way left,
+ maximum to right.
+
+``V4L2_CID_AUDIO_BASS`` ``(integer)``
+ Audio bass adjustment.
+
+``V4L2_CID_AUDIO_TREBLE`` ``(integer)``
+ Audio treble adjustment.
+
+``V4L2_CID_AUDIO_MUTE`` ``(boolean)``
+ Mute audio, i. e. set the volume to zero, however without affecting
+ ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute
+ at load time to avoid excessive noise. Actually the entire device
+ should be reset to a low power consumption state.
+
+``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)``
+ Loudness mode (bass boost).
+
+``V4L2_CID_BLACK_LEVEL`` ``(integer)``
+ Another name for brightness (not a synonym of
+ ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not
+ be used in new drivers and applications.
+
+``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)``
+ Automatic white balance (cameras).
+
+``V4L2_CID_DO_WHITE_BALANCE`` ``(button)``
+ This is an action control. When set (the value is ignored), the
+ device will do a white balance and then hold the current setting.
+ Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``,
+ which, when activated, keeps adjusting the white balance.
+
+``V4L2_CID_RED_BALANCE`` ``(integer)``
+ Red chroma balance.
+
+``V4L2_CID_BLUE_BALANCE`` ``(integer)``
+ Blue chroma balance.
+
+``V4L2_CID_GAMMA`` ``(integer)``
+ Gamma adjust.
+
+``V4L2_CID_WHITENESS`` ``(integer)``
+ Whiteness for grey-scale devices. This is a synonym for
+ ``V4L2_CID_GAMMA``. This control is deprecated and should not be
+ used in new drivers and applications.
+
+``V4L2_CID_EXPOSURE`` ``(integer)``
+ Exposure (cameras). [Unit?]
+
+``V4L2_CID_AUTOGAIN`` ``(boolean)``
+ Automatic gain/exposure control.
+
+``V4L2_CID_GAIN`` ``(integer)``
+ Gain control.
+
+``V4L2_CID_HFLIP`` ``(boolean)``
+ Mirror the picture horizontally.
+
+``V4L2_CID_VFLIP`` ``(boolean)``
+ Mirror the picture vertically.
+
+.. _v4l2-power-line-frequency:
+
+``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)``
+ Enables a power line frequency filter to avoid flicker. Possible
+ values for ``enum v4l2_power_line_frequency`` are:
+ ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0),
+ ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1),
+ ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and
+ ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3).
+
+``V4L2_CID_HUE_AUTO`` ``(boolean)``
+ Enables automatic hue control by the device. The effect of setting
+ ``V4L2_CID_HUE`` while automatic hue control is enabled is
+ undefined, drivers should ignore such request.
+
+``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)``
+ This control specifies the white balance settings as a color
+ temperature in Kelvin. A driver should have a minimum of 2800
+ (incandescent) to 6500 (daylight). For more information about color
+ temperature see
+ `Wikipedia <http://en.wikipedia.org/wiki/Color_temperature>`__.
+
+``V4L2_CID_SHARPNESS`` ``(integer)``
+ Adjusts the sharpness filters in a camera. The minimum value
+ disables the filters, higher values give a sharper picture.
+
+``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)``
+ Adjusts the backlight compensation in a camera. The minimum value
+ disables backlight compensation.
+
+``V4L2_CID_CHROMA_AGC`` ``(boolean)``
+ Chroma automatic gain control.
+
+``V4L2_CID_CHROMA_GAIN`` ``(integer)``
+ Adjusts the Chroma gain control (for use when chroma AGC is
+ disabled).
+
+``V4L2_CID_COLOR_KILLER`` ``(boolean)``
+ Enable the color killer (i. e. force a black & white image in case
+ of a weak video signal).
+
+.. _v4l2-colorfx:
+
+``V4L2_CID_COLORFX`` ``(enum)``
+ Selects a color effect. The following values are defined:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_COLORFX_NONE``
+
+ - Color effect is disabled.
+
+ - .. row 2
+
+ - ``V4L2_COLORFX_ANTIQUE``
+
+ - An aging (old photo) effect.
+
+ - .. row 3
+
+ - ``V4L2_COLORFX_ART_FREEZE``
+
+ - Frost color effect.
+
+ - .. row 4
+
+ - ``V4L2_COLORFX_AQUA``
+
+ - Water color, cool tone.
+
+ - .. row 5
+
+ - ``V4L2_COLORFX_BW``
+
+ - Black and white.
+
+ - .. row 6
+
+ - ``V4L2_COLORFX_EMBOSS``
+
+ - Emboss, the highlights and shadows replace light/dark boundaries
+ and low contrast areas are set to a gray background.
+
+ - .. row 7
+
+ - ``V4L2_COLORFX_GRASS_GREEN``
+
+ - Grass green.
+
+ - .. row 8
+
+ - ``V4L2_COLORFX_NEGATIVE``
+
+ - Negative.
+
+ - .. row 9
+
+ - ``V4L2_COLORFX_SEPIA``
+
+ - Sepia tone.
+
+ - .. row 10
+
+ - ``V4L2_COLORFX_SKETCH``
+
+ - Sketch.
+
+ - .. row 11
+
+ - ``V4L2_COLORFX_SKIN_WHITEN``
+
+ - Skin whiten.
+
+ - .. row 12
+
+ - ``V4L2_COLORFX_SKY_BLUE``
+
+ - Sky blue.
+
+ - .. row 13
+
+ - ``V4L2_COLORFX_SOLARIZATION``
+
+ - Solarization, the image is partially reversed in tone, only color
+ values above or below a certain threshold are inverted.
+
+ - .. row 14
+
+ - ``V4L2_COLORFX_SILHOUETTE``
+
+ - Silhouette (outline).
+
+ - .. row 15
+
+ - ``V4L2_COLORFX_VIVID``
+
+ - Vivid colors.
+
+ - .. row 16
+
+ - ``V4L2_COLORFX_SET_CBCR``
+
+ - The Cb and Cr chroma components are replaced by fixed coefficients
+ determined by ``V4L2_CID_COLORFX_CBCR`` control.
+
+
+
+``V4L2_CID_COLORFX_CBCR`` ``(integer)``
+ Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR``
+ color effect. Bits [7:0] of the supplied 32 bit value are
+ interpreted as Cr component, bits [15:8] as Cb component and bits
+ [31:16] must be zero.
+
+``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)``
+ Enable Automatic Brightness.
+
+``V4L2_CID_ROTATE`` ``(integer)``
+ Rotates the image by specified angle. Common angles are 90, 270 and
+ 180. Rotating the image to 90 and 270 will reverse the height and
+ width of the display window. It is necessary to set the new height
+ and width of the picture using the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl according to the
+ rotation angle selected.
+
+``V4L2_CID_BG_COLOR`` ``(integer)``
+ Sets the background color on the current output device. Background
+ color needs to be specified in the RGB24 format. The supplied 32 bit
+ value is interpreted as bits 0-7 Red color information, bits 8-15
+ Green color information, bits 16-23 Blue color information and bits
+ 24-31 must be zero.
+
+``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)``
+ Switch on or off the illuminator 1 or 2 of the device (usually a
+ microscope).
+
+``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of CAPTURE buffers to pass to
+ REQBUFS. The value is the minimum number of CAPTURE buffers that is
+ necessary for hardware to work.
+
+``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)``
+ This is a read-only control that can be read by the application and
+ used as a hint to determine the number of OUTPUT buffers to pass to
+ REQBUFS. The value is the minimum number of OUTPUT buffers that is
+ necessary for hardware to work.
+
+.. _v4l2-alpha-component:
+
+``V4L2_CID_ALPHA_COMPONENT`` ``(integer)``
+ Sets the alpha color component. When a capture device (or capture
+ queue of a mem-to-mem device) produces a frame format that includes
+ an alpha component (e.g.
+ :ref:`packed RGB image formats <rgb-formats>`) and the alpha value
+ is not defined by the device or the mem-to-mem input data this
+ control lets you select the alpha component value of all pixels.
+ When an output device (or output queue of a mem-to-mem device)
+ consumes a frame format that doesn't include an alpha component and
+ the device supports alpha channel processing this control lets you
+ set the alpha component value of all pixels for further processing
+ in the device.
+
+``V4L2_CID_LASTP1``
+ End of the predefined control IDs (currently
+ ``V4L2_CID_ALPHA_COMPONENT`` + 1).
+
+``V4L2_CID_PRIVATE_BASE``
+ ID of the first custom (driver specific) control. Applications
+ depending on particular custom controls should check the driver name
+ and version, see :ref:`querycap`.
+
+Applications can enumerate the available controls with the
+:ref:`VIDIOC_QUERYCTRL` and
+:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls, get and set a
+control value with the :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls. Drivers must implement
+``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the
+device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or
+more menu type controls.
+
+
+.. _enum_all_controls:
+
+.. code-block:: c
+ :caption: Example 1.8. Enumerating all user controls
+
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_querymenu querymenu;
+
+ static void enumerate_menu(void)
+ {
+ printf(" Menu items:\\n");
+
+ memset(&querymenu, 0, sizeof(querymenu));
+ querymenu.id = queryctrl.id;
+
+ for (querymenu.index = queryctrl.minimum;
+ querymenu.index <= queryctrl.maximum;
+ querymenu.index++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) {
+ printf(" %s\\n", querymenu.name);
+ }
+ }
+ }
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ for (queryctrl.id = V4L2_CID_BASE;
+ queryctrl.id < V4L2_CID_LASTP1;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+ } else {
+ if (errno == EINVAL)
+ continue;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
+ queryctrl.id++) {
+ if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+ } else {
+ if (errno == EINVAL)
+ break;
+
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.9. Enumerating all user controls (alternative)
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+
+ queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER)
+ break;
+ if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)
+ continue;
+
+ printf("Control %s\\n", queryctrl.name);
+
+ if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
+ enumerate_menu();
+
+ queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.10. Changing controls
+
+ struct v4l2_queryctrl queryctrl;
+ struct v4l2_control control;
+
+ memset(&queryctrl, 0, sizeof(queryctrl));
+ queryctrl.id = V4L2_CID_BRIGHTNESS;
+
+ if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) {
+ if (errno != EINVAL) {
+ perror("VIDIOC_QUERYCTRL");
+ exit(EXIT_FAILURE);
+ } else {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ }
+ } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) {
+ printf("V4L2_CID_BRIGHTNESS is not supportedn");
+ } else {
+ memset(&control, 0, sizeof (control));
+ control.id = V4L2_CID_BRIGHTNESS;
+ control.value = queryctrl.default_value;
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ memset(&control, 0, sizeof(control));
+ control.id = V4L2_CID_CONTRAST;
+
+ if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) {
+ control.value += 1;
+
+ /* The driver may clamp the value or return ERANGE, ignored here */
+
+ if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)
+ && errno != ERANGE) {
+ perror("VIDIOC_S_CTRL");
+ exit(EXIT_FAILURE);
+ }
+ /* Ignore if V4L2_CID_CONTRAST is unsupported */
+ } else if (errno != EINVAL) {
+ perror("VIDIOC_G_CTRL");
+ exit(EXIT_FAILURE);
+ }
+
+ control.id = V4L2_CID_AUDIO_MUTE;
+ control.value = 1; /* silence */
+
+ /* Errors ignored */
+ ioctl(fd, VIDIOC_S_CTRL, &control);
+
+.. [1]
+ The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different
+ drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different
+ controls. This makes it hard to programatically set such controls
+ since the meaning of the control with that ID is driver dependent. In
+ order to resolve this drivers use unique IDs and the
+ ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the
+ kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to
+ the real IDs.
+
+ Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs
+ instead of using :ref:`VIDIOC_QUERYCTRL` with
+ the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so
+ support for ``V4L2_CID_PRIVATE_BASE`` is still around.
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
new file mode 100644
index 000000000000..ed43b36c51d8
--- /dev/null
+++ b/Documentation/media/uapi/v4l/crop.rst
@@ -0,0 +1,294 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _crop:
+
+*************************************
+Image Cropping, Insertion and Scaling
+*************************************
+
+Some video capture devices can sample a subsection of the picture and
+shrink or enlarge it to an image of arbitrary size. We call these
+abilities cropping and scaling. Some video output devices can scale an
+image up or down and insert it at an arbitrary scan line and horizontal
+offset into a video signal.
+
+Applications can use the following API to select an area in the video
+signal, query the default area and the hardware limits.
+
+**NOTE**: Despite their name, the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>`,
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP
+<VIDIOC_G_CROP>` ioctls apply to input as well as output devices.
+
+Scaling requires a source and a target. On a video capture or overlay
+device the source is the video signal, and the cropping ioctls determine
+the area actually sampled. The target are images read by the application
+or overlaid onto the graphics screen. Their size (and position for an
+overlay) is negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls.
+
+On a video output device the source are the images passed in by the
+application, and their size is again negotiated with the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctls, or may be encoded in a compressed video stream. The target is
+the video signal, and the cropping ioctls determine the area where the
+images are inserted.
+
+Source and target rectangles are defined even if the device does not
+support scaling or the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctls. Their size (and position
+where applicable) will be fixed in this case.
+
+**NOTE:** All capture and output devices must support the
+:ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl such that applications can
+determine if scaling takes place.
+
+
+Cropping Structures
+===================
+
+
+.. _crop-scale:
+
+.. figure:: crop_files/crop.*
+ :alt: crop.pdf / crop.gif
+ :align: center
+
+ Image Cropping, Insertion and Scaling
+
+ The cropping, insertion and scaling process
+
+
+
+For capture devices the coordinates of the top left corner, width and
+height of the area which can be sampled is given by the ``bounds``
+substructure of the struct :ref:`v4l2_cropcap <v4l2-cropcap>` returned
+by the :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` ioctl. To support a wide
+range of hardware this specification does not define an origin or units.
+However by convention drivers should horizontally count unscaled samples
+relative to 0H (the leading edge of the horizontal sync pulse, see
+:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field
+(see ITU R-525 line numbering for :ref:`525 lines <vbi-525>` and for
+:ref:`625 lines <vbi-625>`), multiplied by two if the driver
+can capture both fields.
+
+The top left corner, width and height of the source rectangle, that is
+the area actually sampled, is given by struct
+:ref:`v4l2_crop <v4l2-crop>` using the same coordinate system as
+struct :ref:`v4l2_cropcap <v4l2-cropcap>`. Applications can use the
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>`
+ioctls to get and set this rectangle. It must lie completely within the
+capture boundaries and the driver may further adjust the requested size
+and/or position according to hardware limitations.
+
+Each capture device has a default source rectangle, given by the
+``defrect`` substructure of struct
+:ref:`v4l2_cropcap <v4l2-cropcap>`. The center of this rectangle
+shall align with the center of the active picture area of the video
+signal, and cover what the driver writer considers the complete picture.
+Drivers shall reset the source rectangle to the default when the driver
+is first loaded, but not later.
+
+For output devices these structures and ioctls are used accordingly,
+defining the *target* rectangle where the images will be inserted into
+the video signal.
+
+
+Scaling Adjustments
+===================
+
+Video hardware can have various cropping, insertion and scaling
+limitations. It may only scale up or down, support only discrete scaling
+factors, or have different scaling abilities in horizontal and vertical
+direction. Also it may not support scaling at all. At the same time the
+struct :ref:`v4l2_crop <v4l2-crop>` rectangle may have to be aligned,
+and both the source and target rectangles may have arbitrary upper and
+lower size limits. In particular the maximum ``width`` and ``height`` in
+struct :ref:`v4l2_crop <v4l2-crop>` may be smaller than the struct
+:ref:`v4l2_cropcap <v4l2-cropcap>`. ``bounds`` area. Therefore, as
+usual, drivers are expected to adjust the requested parameters and
+return the actual values selected.
+
+Applications can change the source or the target rectangle first, as
+they may prefer a particular image size or a certain area in the video
+signal. If the driver has to adjust both to satisfy hardware
+limitations, the last requested rectangle shall take priority, and the
+driver should preferably adjust the opposite one. The
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl however shall not change
+the driver state and therefore only adjust the requested rectangle.
+
+Suppose scaling on a video capture device is restricted to a factor 1:1
+or 2:1 in either direction and the target image size must be a multiple
+of 16 × 16 pixels. The source cropping rectangle is set to defaults,
+which are also the upper limit in this example, of 640 × 400 pixels at
+offset 0, 0. An application requests an image size of 300 × 225 pixels,
+assuming video will be scaled down from the "full picture" accordingly.
+The driver sets the image size to the closest possible values 304 × 224,
+then chooses the cropping rectangle closest to the requested size, that
+is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is
+still valid, thus unmodified. Given the default cropping rectangle
+reported by :ref:`VIDIOC_CROPCAP <VIDIOC_CROPCAP>` the application can
+easily propose another offset to center the cropping rectangle.
+
+Now the application may insist on covering an area using a picture
+aspect ratio closer to the original request, so it asks for a cropping
+rectangle of 608 × 456 pixels. The present scaling factors limit
+cropping to 640 × 384, so the driver returns the cropping size 608 × 384
+and adjusts the image size to closest possible 304 × 192.
+
+
+Examples
+========
+
+Source and target rectangles shall remain unchanged across closing and
+reopening a device, such that piping data into or out of a device will
+work without special preparations. More advanced applications should
+ensure the parameters are suitable before starting I/O.
+
+**NOTE:** on the next two examples, a video capture device is assumed;
+change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device.
+
+.. code-block:: c
+ :caption: Example 1.11. Resetting the cropping parameters
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ crop.c = cropcap.defrect;
+
+ /* Ignore if cropping is not supported (EINVAL). */
+
+ if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+.. code-block:: c
+ :caption: Example 1.12. Simple downscaling
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_format format;
+
+ reset_cropping_parameters ();
+
+ /* Scale down to 1/4 size of full picture. */
+
+ memset (&format, 0, sizeof (format)); /* defaults */
+
+ format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ format.fmt.pix.width = cropcap.defrect.width >> 1;
+ format.fmt.pix.height = cropcap.defrect.height >> 1;
+ format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
+
+ if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) {
+ perror ("VIDIOC_S_FORMAT");
+ exit (EXIT_FAILURE);
+ }
+
+ /* We could check the actual image size now, the actual scaling factor
+ or if the driver can scale at all. */
+
+**NOTE:** This example assumes an output device.
+
+.. code-block:: c
+ :caption: Example 1.13. Selecting an output area
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+
+ crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
+ crop.c = cropcap.defrect;
+
+ /* Scale the width and height to 50 % of their original size
+ and center the output. */
+
+ crop.c.width /= 2;
+ crop.c.height /= 2;
+ crop.c.left += crop.c.width / 2;
+ crop.c.top += crop.c.height / 2;
+
+ /* Ignore if cropping is not supported (EINVAL). */
+
+ if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop)
+ && errno != EINVAL) {
+ perror ("VIDIOC_S_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+**NOTE:** This example assumes a video capture device.
+
+.. code-block:: c
+ :caption: Example 1.14. Current scaling factor and pixel aspect
+
+ struct v4l2_cropcap cropcap;
+ struct v4l2_crop crop;
+ struct v4l2_format format;
+ double hscale, vscale;
+ double aspect;
+ int dwidth, dheight;
+
+ memset (&cropcap, 0, sizeof (cropcap));
+ cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) {
+ perror ("VIDIOC_CROPCAP");
+ exit (EXIT_FAILURE);
+ }
+
+ memset (&crop, 0, sizeof (crop));
+ crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) {
+ if (errno != EINVAL) {
+ perror ("VIDIOC_G_CROP");
+ exit (EXIT_FAILURE);
+ }
+
+ /* Cropping not supported. */
+ crop.c = cropcap.defrect;
+ }
+
+ memset (&format, 0, sizeof (format));
+ format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) {
+ perror ("VIDIOC_G_FMT");
+ exit (EXIT_FAILURE);
+ }
+
+ /* The scaling applied by the driver. */
+
+ hscale = format.fmt.pix.width / (double) crop.c.width;
+ vscale = format.fmt.pix.height / (double) crop.c.height;
+
+ aspect = cropcap.pixelaspect.numerator /
+ (double) cropcap.pixelaspect.denominator;
+ aspect = aspect * hscale / vscale;
+
+ /* Devices following ITU-R BT.601 do not capture
+ square pixels. For playback on a computer monitor
+ we should scale the images to this size. */
+
+ dwidth = format.fmt.pix.width / aspect;
+ dheight = format.fmt.pix.height;
diff --git a/Documentation/media/uapi/v4l/crop_files/crop.gif b/Documentation/media/uapi/v4l/crop_files/crop.gif
new file mode 100644
index 000000000000..3b9e7d836d4b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/crop_files/crop.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/crop_files/crop.pdf b/Documentation/media/uapi/v4l/crop_files/crop.pdf
new file mode 100644
index 000000000000..c9fb81cd32f3
--- /dev/null
+++ b/Documentation/media/uapi/v4l/crop_files/crop.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst
new file mode 100644
index 000000000000..82f183870aae
--- /dev/null
+++ b/Documentation/media/uapi/v4l/depth-formats.rst
@@ -0,0 +1,15 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _depth-formats:
+
+*************
+Depth Formats
+*************
+
+Depth data provides distance to points, mapped onto the image plane
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-z16
diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst
new file mode 100644
index 000000000000..16030a8354fd
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-capture.rst
@@ -0,0 +1,102 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _capture:
+
+***********************
+Video Capture Interface
+***********************
+
+Video capture devices sample an analog video signal and store the
+digitized images in memory. Today nearly all devices can capture at full
+25 or 30 frames/second. With this interface applications can control the
+capture process and move images from the driver into user space.
+
+Conventionally V4L2 video capture devices are accessed through character
+device special files named ``/dev/video`` and ``/dev/video0`` to
+``/dev/video63`` with major number 81 and minor numbers 0 to 63.
+``/dev/video`` is typically a symbolic link to the preferred video
+device. Note the same device files are used for video output devices.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video capture interface set the
+``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in
+the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
+functions they may also support the :ref:`video overlay <overlay>`
+(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture <raw-vbi>`
+(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or
+streaming I/O methods must be supported. Tuners and audio inputs are
+optional.
+
+
+Supplemental Functions
+======================
+
+Video capture devices shall support :ref:`audio input <audio>`,
+:ref:`tuner`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video input <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video capture devices.
+
+
+Image Format Negotiation
+========================
+
+The result of a capture operation is determined by cropping and image
+format parameters. The former select an area of the video picture to
+capture, the latter how images are stored in memory, i. e. in RGB or YUV
+format, the number of bits per pixel or width and height. Together they
+also define how images are scaled in the process.
+
+As usual these parameters are *not* reset at :ref:`open() <func-open>`
+time to permit Unix tool chains, programming a device and then reading
+from it as if it was a plain file. Well written V4L2 applications ensure
+they really get what they want, including cropping and scaling.
+
+Cropping initialization at minimum requires to reset the parameters to
+defaults. An example is given in :ref:`crop`.
+
+To query the current image format applications set the ``type`` field of
+a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and call the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
+structure. Drivers fill the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member of the ``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl with a pointer to this structure. Drivers may adjust the
+parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+does.
+
+Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
+can be used to learn about hardware limitations without disabling I/O or
+possibly time consuming hardware preparations.
+
+The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
+discussed in :ref:`pixfmt`. See also the specification of the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
+details. Video capture devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
+requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
+
+
+Reading Images
+==============
+
+A video capture device may support the ::ref:`read() function <func-read>`
+and/or streaming (:ref:`memory mapping <func-mmap>` or
+:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
diff --git a/Documentation/media/uapi/v4l/dev-codec.rst b/Documentation/media/uapi/v4l/dev-codec.rst
new file mode 100644
index 000000000000..7fd28d085c2c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-codec.rst
@@ -0,0 +1,32 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _codec:
+
+***************
+Codec Interface
+***************
+
+A V4L2 codec can compress, decompress, transform, or otherwise convert
+video data from one format into another format, in memory. Typically
+such devices are memory-to-memory devices (i.e. devices with the
+``V4L2_CAP_VIDEO_M2M`` or ``V4L2_CAP_VIDEO_M2M_MPLANE`` capability set).
+
+A memory-to-memory video node acts just like a normal video node, but it
+supports both output (sending frames from memory to the codec hardware)
+and capture (receiving the processed frames from the codec hardware into
+memory) stream I/O. An application will have to setup the stream I/O for
+both sides and finally call :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+for both capture and output to start the codec.
+
+Video compression codecs use the MPEG controls to setup their codec
+parameters (note that the MPEG controls actually support many more
+codecs than just MPEG). See :ref:`mpeg-controls`.
+
+Memory-to-memory devices can often be used as a shared resource: you can
+open the video node multiple times, each application setting up their
+own codec properties that are local to the file handle, and each can use
+it independently from the others. The driver will arbitrate access to
+the codec and reprogram it whenever another file handler gets access.
+This is different from the usual video node behavior where the video
+properties are global to the device (i.e. changing something through one
+file handle is visible through another file handle).
diff --git a/Documentation/media/uapi/v4l/dev-effect.rst b/Documentation/media/uapi/v4l/dev-effect.rst
new file mode 100644
index 000000000000..be4de3b0a025
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-effect.rst
@@ -0,0 +1,22 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _effect:
+
+************************
+Effect Devices Interface
+************************
+
+ **Note**
+
+ This interface has been be suspended from the V4L2 API implemented
+ in Linux 2.6 until we have more experience with effect device
+ interfaces.
+
+A V4L2 video effect device can do image effects, filtering, or combine
+two or more images or image streams. For example video transitions or
+wipes. Applications send data to be processed and receive the result
+data either with :ref:`read() <func-read>` and
+:ref:`write() <func-write>` functions, or through the streaming I/O
+mechanism.
+
+[to do]
diff --git a/Documentation/media/uapi/v4l/dev-event.rst b/Documentation/media/uapi/v4l/dev-event.rst
new file mode 100644
index 000000000000..a06ec4d65359
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-event.rst
@@ -0,0 +1,47 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _event:
+
+***************
+Event Interface
+***************
+
+The V4L2 event interface provides a means for a user to get immediately
+notified on certain conditions taking place on a device. This might
+include start of frame or loss of signal events, for example. Changes in
+the value or state of a V4L2 control can also be reported through
+events.
+
+To receive events, the events the user is interested in first must be
+subscribed using the
+:ref:`VIDIOC_SUBSCRIBE_EVENT` ioctl. Once
+an event is subscribed, the events of subscribed types are dequeueable
+using the :ref:`VIDIOC_DQEVENT` ioctl. Events may be
+unsubscribed using VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event
+type V4L2_EVENT_ALL may be used to unsubscribe all the events the
+driver supports.
+
+The event subscriptions and event queues are specific to file handles.
+Subscribing an event on one file handle does not affect other file
+handles.
+
+The information on dequeueable events is obtained by using select or
+poll system calls on video devices. The V4L2 events use POLLPRI events
+on poll system call and exceptions on select system call.
+
+Starting with kernel 3.1 certain guarantees can be given with regards to
+events:
+
+1. Each subscribed event has its own internal dedicated event queue.
+ This means that flooding of one event type will not interfere with
+ other event types.
+
+2. If the internal event queue for a particular subscribed event becomes
+ full, then the oldest event in that queue will be dropped.
+
+3. Where applicable, certain event types can ensure that the payload of
+ the oldest event that is about to be dropped will be merged with the
+ payload of the next oldest event. Thus ensuring that no information
+ is lost, but only an intermediate step leading up to that
+ information. See the documentation for the event you want to
+ subscribe to whether this is applicable for that event or not.
diff --git a/Documentation/media/uapi/v4l/dev-osd.rst b/Documentation/media/uapi/v4l/dev-osd.rst
new file mode 100644
index 000000000000..b9b53fd7eb5d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-osd.rst
@@ -0,0 +1,146 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _osd:
+
+******************************
+Video Output Overlay Interface
+******************************
+
+**Also known as On-Screen Display (OSD)**
+
+Some video output devices can overlay a framebuffer image onto the
+outgoing video signal. Applications can set up such an overlay using
+this interface, which borrows structures and ioctls of the
+:ref:`Video Overlay <overlay>` interface.
+
+The OSD function is accessible through the same character special file
+as the :ref:`Video Output <capture>` function. Note the default
+function of such a ``/dev/video`` device is video capturing or output.
+The OSD function is only available after calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the *Video Output Overlay* interface set the
+``V4L2_CAP_VIDEO_OUTPUT_OVERLAY`` flag in the ``capabilities`` field of
+struct :ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl.
+
+
+Framebuffer
+===========
+
+Contrary to the *Video Overlay* interface the framebuffer is normally
+implemented on the TV card and not the graphics card. On Linux it is
+accessible as a framebuffer device (``/dev/fbN``). Given a V4L2 device,
+applications can find the corresponding framebuffer device by calling
+the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` ioctl. It returns, amongst
+other information, the physical address of the framebuffer in the
+``base`` field of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`.
+The framebuffer device ioctl ``FBIOGET_FSCREENINFO`` returns the same
+address in the ``smem_start`` field of struct
+:c:type:`struct fb_fix_screeninfo`. The ``FBIOGET_FSCREENINFO``
+ioctl and struct :c:type:`struct fb_fix_screeninfo` are defined in
+the ``linux/fb.h`` header file.
+
+The width and height of the framebuffer depends on the current video
+standard. A V4L2 driver may reject attempts to change the video standard
+(or any other ioctl which would imply a framebuffer size change) with an
+``EBUSY`` error code until all applications closed the framebuffer device.
+
+
+.. code-block:: c
+ :caption: Example 4.1. Finding a framebuffer device for OSD
+
+ #include <linux/fb.h>
+
+ struct v4l2_framebuffer fbuf;
+ unsigned int i;
+ int fb_fd;
+
+ if (-1 == ioctl(fd, VIDIOC_G_FBUF, &fbuf)) {
+ perror("VIDIOC_G_FBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ for (i = 0; i < 30; i++) {
+ char dev_name[16];
+ struct fb_fix_screeninfo si;
+
+ snprintf(dev_name, sizeof(dev_name), "/dev/fb%u", i);
+
+ fb_fd = open(dev_name, O_RDWR);
+ if (-1 == fb_fd) {
+ switch (errno) {
+ case ENOENT: /* no such file */
+ case ENXIO: /* no driver */
+ continue;
+
+ default:
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ if (0 == ioctl(fb_fd, FBIOGET_FSCREENINFO, &si)) {
+ if (si.smem_start == (unsigned long)fbuf.base)
+ break;
+ } else {
+ /* Apparently not a framebuffer device. */
+ }
+
+ close(fb_fd);
+ fb_fd = -1;
+ }
+
+ /* fb_fd is the file descriptor of the framebuffer device
+ for the video output overlay, or -1 if no device was found. */
+
+
+Overlay Window and Scaling
+==========================
+
+The overlay is controlled by source and target rectangles. The source
+rectangle selects a subsection of the framebuffer image to be overlaid,
+the target rectangle an area in the outgoing video signal where the
+image will appear. Drivers may or may not support scaling, and arbitrary
+sizes and positions of these rectangles. Further drivers may support any
+(or none) of the clipping/blending methods defined for the
+:ref:`Video Overlay <overlay>` interface.
+
+A struct :ref:`v4l2_window <v4l2-window>` defines the size of the
+source rectangle, its position in the framebuffer and the
+clipping/blending method to be used for the overlay. To get the current
+parameters applications set the ``type`` field of a struct
+:ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` and call the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
+:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not
+possible to retrieve a previously programmed clipping list or bitmap.
+
+To program the source rectangle applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY``, initialize the ``win``
+substructure and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+The driver adjusts the parameters against hardware limits and returns
+the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
+the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
+about driver capabilities without actually changing driver state. Unlike
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
+
+A struct :ref:`v4l2_crop <v4l2-crop>` defines the size and position
+of the target rectangle. The scaling factor of the overlay is implied by
+the width and height given in struct :ref:`v4l2_window <v4l2-window>`
+and struct :ref:`v4l2_crop <v4l2-crop>`. The cropping API applies to
+*Video Output* and *Video Output Overlay* devices in the same way as to
+*Video Capture* and *Video Overlay* devices, merely reversing the
+direction of the data flow. For more information see :ref:`crop`.
+
+
+Enabling Overlay
+================
+
+There is no V4L2 ioctl to enable or disable the overlay, however the
+framebuffer interface of the driver may support the ``FBIOBLANK`` ioctl.
diff --git a/Documentation/media/uapi/v4l/dev-output.rst b/Documentation/media/uapi/v4l/dev-output.rst
new file mode 100644
index 000000000000..5063be7d4938
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-output.rst
@@ -0,0 +1,99 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _output:
+
+**********************
+Video Output Interface
+**********************
+
+Video output devices encode stills or image sequences as analog video
+signal. With this interface applications can control the encoding
+process and move images from user space to the driver.
+
+Conventionally V4L2 video output devices are accessed through character
+device special files named ``/dev/video`` and ``/dev/video0`` to
+``/dev/video63`` with major number 81 and minor numbers 0 to 63.
+``/dev/video`` is typically a symbolic link to the preferred video
+device. Note the same device files are used for video capture devices.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video output interface set the
+``V4L2_CAP_VIDEO_OUTPUT`` or ``V4L2_CAP_VIDEO_OUTPUT_MPLANE`` flag in
+the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device
+functions they may also support the :ref:`raw VBI output <raw-vbi>`
+(``V4L2_CAP_VBI_OUTPUT``) interface. At least one of the read/write or
+streaming I/O methods must be supported. Modulators and audio outputs
+are optional.
+
+
+Supplemental Functions
+======================
+
+Video output devices shall support :ref:`audio output <audio>`,
+:ref:`modulator <tuner>`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video output <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video output devices.
+
+
+Image Format Negotiation
+========================
+
+The output is determined by cropping and image format parameters. The
+former select an area of the video picture where the image will appear,
+the latter how images are stored in memory, i. e. in RGB or YUV format,
+the number of bits per pixel or width and height. Together they also
+define how images are scaled in the process.
+
+As usual these parameters are *not* reset at :ref:`open() <func-open>`
+time to permit Unix tool chains, programming a device and then writing
+to it as if it was a plain file. Well written V4L2 applications ensure
+they really get what they want, including cropping and scaling.
+
+Cropping initialization at minimum requires to reset the parameters to
+defaults. An example is given in :ref:`crop`.
+
+To query the current image format applications set the ``type`` field of
+a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``
+and call the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer
+to this structure. Drivers fill the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member of the ``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl with a pointer to this structure. Drivers may adjust the
+parameters and finally return the actual parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+does.
+
+Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` the :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl
+can be used to learn about hardware limitations without disabling I/O or
+possibly time consuming hardware preparations.
+
+The contents of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` are
+discussed in :ref:`pixfmt`. See also the specification of the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctls for
+details. Video output devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`
+and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all
+requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
+
+
+Writing Images
+==============
+
+A video output device may support the :ref:`write() function <rw>`
+and/or streaming (:ref:`memory mapping <mmap>` or
+:ref:`user pointer <userp>`) I/O. See :ref:`io` for details.
diff --git a/Documentation/media/uapi/v4l/dev-overlay.rst b/Documentation/media/uapi/v4l/dev-overlay.rst
new file mode 100644
index 000000000000..bed00bf34982
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-overlay.rst
@@ -0,0 +1,316 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _overlay:
+
+***********************
+Video Overlay Interface
+***********************
+
+**Also known as Framebuffer Overlay or Previewing.**
+
+Video overlay devices have the ability to genlock (TV-)video into the
+(VGA-)video signal of a graphics card, or to store captured images
+directly in video memory of a graphics card, typically with clipping.
+This can be considerable more efficient than capturing images and
+displaying them by other means. In the old days when only nuclear power
+plants needed cooling towers this used to be the only way to put live
+video into a window.
+
+Video overlay devices are accessed through the same character special
+files as :ref:`video capture <capture>` devices. Note the default
+function of a ``/dev/video`` device is video capturing. The overlay
+function is only available after calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+The driver may support simultaneous overlay and capturing using the
+read/write and streaming I/O methods. If so, operation at the nominal
+frame rate of the video standard is not guaranteed. Frames may be
+directed away from overlay to capture, or one field may be used for
+overlay and the other for capture if the capture parameters permit this.
+
+Applications should use different file descriptors for capturing and
+overlay. This must be supported by all drivers capable of simultaneous
+capturing and overlay. Optionally these drivers may also permit
+capturing and overlay with a single file descriptor for compatibility
+with V4L and earlier versions of V4L2. [1]_
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the video overlay interface set the
+``V4L2_CAP_VIDEO_OVERLAY`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. The overlay I/O
+method specified below must be supported. Tuners and audio inputs are
+optional.
+
+
+Supplemental Functions
+======================
+
+Video overlay devices shall support :ref:`audio input <audio>`,
+:ref:`tuner`, :ref:`controls <control>`,
+:ref:`cropping and scaling <crop>` and
+:ref:`streaming parameter <streaming-par>` ioctls as needed. The
+:ref:`video input <video>` and :ref:`video standard <standard>`
+ioctls must be supported by all video overlay devices.
+
+
+Setup
+=====
+
+Before overlay can commence applications must program the driver with
+frame buffer parameters, namely the address and size of the frame buffer
+and the image format, for example RGB 5:6:5. The
+:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
+:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls are available to get and
+set these parameters, respectively. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is
+privileged because it allows to set up DMA into physical memory,
+bypassing the memory protection mechanisms of the kernel. Only the
+superuser can change the frame buffer address and size. Users are not
+supposed to run TV applications as root or with SUID bit set. A small
+helper application with suitable privileges should query the graphics
+system and program the V4L2 driver at the appropriate time.
+
+Some devices add the video overlay to the output signal of the graphics
+card. In this case the frame buffer is not modified by the video device,
+and the frame buffer address and pixel format are not needed by the
+driver. The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl is not privileged. An application
+can check for this type of device by calling the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+ioctl.
+
+A driver may support any (or none) of five clipping/blending methods:
+
+1. Chroma-keying displays the overlaid image only where pixels in the
+ primary graphics surface assume a certain color.
+
+2. A bitmap can be specified where each bit corresponds to a pixel in
+ the overlaid image. When the bit is set, the corresponding video
+ pixel is displayed, otherwise a pixel of the graphics surface.
+
+3. A list of clipping rectangles can be specified. In these regions *no*
+ video is displayed, so the graphics surface can be seen here.
+
+4. The framebuffer has an alpha channel that can be used to clip or
+ blend the framebuffer with the video.
+
+5. A global alpha value can be specified to blend the framebuffer
+ contents with video images.
+
+When simultaneous capturing and overlay is supported and the hardware
+prohibits different image and frame buffer formats, the format requested
+first takes precedence. The attempt to capture
+(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) or overlay
+(:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`) may fail with an ``EBUSY`` error
+code or return accordingly modified parameters..
+
+
+Overlay Window
+==============
+
+The overlaid image is determined by cropping and overlay window
+parameters. The former select an area of the video picture to capture,
+the latter how images are overlaid and clipped. Cropping initialization
+at minimum requires to reset the parameters to defaults. An example is
+given in :ref:`crop`.
+
+The overlay window is described by a struct
+:ref:`v4l2_window <v4l2-window>`. It defines the size of the image,
+its position over the graphics surface and the clipping to be applied.
+To get the current parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OVERLAY`` and call the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl. The driver fills the
+:ref:`struct v4l2_window <v4l2-window>` substructure named ``win``. It is not
+possible to retrieve a previously programmed clipping list or bitmap.
+
+To program the overlay window applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VIDEO_OVERLAY``, initialize the ``win`` substructure and
+call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. The driver
+adjusts the parameters against hardware limits and returns the actual
+parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Like :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to learn
+about driver capabilities without actually changing driver state. Unlike
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` this also works after the overlay has been enabled.
+
+The scaling factor of the overlaid image is implied by the width and
+height given in struct :ref:`v4l2_window <v4l2-window>` and the size
+of the cropping rectangle. For more information see :ref:`crop`.
+
+When simultaneous capturing and overlay is supported and the hardware
+prohibits different image and window sizes, the size requested first
+takes precedence. The attempt to capture or overlay as well
+(:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) may fail with an ``EBUSY`` error
+code or return accordingly modified parameters.
+
+
+.. _v4l2-window:
+
+struct v4l2_window
+------------------
+
+``struct v4l2_rect w``
+ Size and position of the window relative to the top, left corner of
+ the frame buffer defined with
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The window can extend the
+ frame buffer width and height, the ``x`` and ``y`` coordinates can
+ be negative, and it can lie completely outside the frame buffer. The
+ driver clips the window accordingly, or if that is not possible,
+ modifies its size and/or position.
+
+``enum v4l2_field field``
+ Applications set this field to determine which video field shall be
+ overlaid, typically one of ``V4L2_FIELD_ANY`` (0),
+ ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM`` or
+ ``V4L2_FIELD_INTERLACED``. Drivers may have to choose a different
+ field order and return the actual setting here.
+
+``__u32 chromakey``
+ When chroma-keying has been negotiated with
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` applications set this field
+ to the desired pixel value for the chroma key. The format is the
+ same as the pixel format of the framebuffer (struct
+ :ref:`v4l2_framebuffer <v4l2-framebuffer>` ``fmt.pixelformat``
+ field), with bytes in host order. E. g. for
+ :ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR32>` the value should
+ be 0xRRGGBB on a little endian, 0xBBGGRR on a big endian host.
+
+``struct v4l2_clip * clips``
+ When chroma-keying has *not* been negotiated and
+ :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
+ applications can set this field to point to an array of clipping
+ rectangles.
+
+ Like the window coordinates w, clipping rectangles are defined
+ relative to the top, left corner of the frame buffer. However
+ clipping rectangles must not extend the frame buffer width and
+ height, and they must not overlap. If possible applications
+ should merge adjacent rectangles. Whether this must create
+ x-y or y-x bands, or the order of rectangles, is not defined. When
+ clip lists are not supported the driver ignores this field. Its
+ contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ are undefined.
+
+``__u32 clipcount``
+ When the application set the ``clips`` field, this field must
+ contain the number of clipping rectangles in the list. When clip
+ lists are not supported the driver ignores this field, its contents
+ after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are undefined. When clip lists are
+ supported but no clipping is desired this field must be set to zero.
+
+``void * bitmap``
+ When chroma-keying has *not* been negotiated and
+ :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` indicated this capability,
+ applications can set this field to point to a clipping bit mask.
+
+It must be of the same size as the window, ``w.width`` and ``w.height``.
+Each bit corresponds to a pixel in the overlaid image, which is
+displayed only when the bit is *set*. Pixel coordinates translate to
+bits like:
+
+
+.. code-block:: c
+
+ ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))
+
+where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [2]_
+
+When a clipping bit mask is not supported the driver ignores this field,
+its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are
+undefined. When a bit mask is supported but no clipping is desired this
+field must be set to ``NULL``.
+
+Applications need not create a clip list or bit mask. When they pass
+both, or despite negotiating chroma-keying, the results are undefined.
+Regardless of the chosen method, the clipping abilities of the hardware
+may be limited in quantity or quality. The results when these limits are
+exceeded are undefined. [3]_
+
+``__u8 global_alpha``
+ The global alpha value used to blend the framebuffer with video
+ images, if global alpha blending has been negotiated
+ (``V4L2_FBUF_FLAG_GLOBAL_ALPHA``, see
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`,
+ :ref:`framebuffer-flags`).
+
+ **Note**: this field was added in Linux 2.6.23, extending the structure.
+ However the :ref:`VIDIOC_[G|S|TRY]_FMT <VIDIOC_G_FMT>`
+ ioctls, which take a pointer to a :ref:`v4l2_format <v4l2-format>`
+ parent structure with padding bytes at the end, are not affected.
+
+
+.. _v4l2-clip:
+
+struct v4l2_clip [4]_
+---------------------
+
+``struct v4l2_rect c``
+ Coordinates of the clipping rectangle, relative to the top, left
+ corner of the frame buffer. Only window pixels *outside* all
+ clipping rectangles are displayed.
+
+``struct v4l2_clip * next``
+ Pointer to the next clipping rectangle, ``NULL`` when this is the last
+ rectangle. Drivers ignore this field, it cannot be used to pass a
+ linked list of clipping rectangles.
+
+
+.. _v4l2-rect:
+
+struct v4l2_rect
+----------------
+
+``__s32 left``
+ Horizontal offset of the top, left corner of the rectangle, in
+ pixels.
+
+``__s32 top``
+ Vertical offset of the top, left corner of the rectangle, in pixels.
+ Offsets increase to the right and down.
+
+``__u32 width``
+ Width of the rectangle, in pixels.
+
+``__u32 height``
+ Height of the rectangle, in pixels.
+
+
+Enabling Overlay
+================
+
+To start or stop the frame buffer overlay applications call the
+:ref:`VIDIOC_OVERLAY` ioctl.
+
+.. [1]
+ A common application of two file descriptors is the XFree86
+ :ref:`Xv/V4L <xvideo>` interface driver and a V4L2 application.
+ While the X server controls video overlay, the application can take
+ advantage of memory mapping and DMA.
+
+ In the opinion of the designers of this API, no driver writer taking
+ the efforts to support simultaneous capturing and overlay will
+ restrict this ability by requiring a single file descriptor, as in
+ V4L and earlier versions of V4L2. Making this optional means
+ applications depending on two file descriptors need backup routines
+ to be compatible with all drivers, which is considerable more work
+ than using two fds in applications which do not. Also two fd's fit
+ the general concept of one file descriptor for each logical stream.
+ Hence as a complexity trade-off drivers *must* support two file
+ descriptors and *may* support single fd operation.
+
+.. [2]
+ Should we require ``w.width`` to be a multiple of eight?
+
+.. [3]
+ When the image is written into frame buffer memory it will be
+ undesirable if the driver clips out less pixels than expected,
+ because the application and graphics system are not aware these
+ regions need to be refreshed. The driver should clip out more pixels
+ or not write the image at all.
+
+.. [4]
+ The X Window system defines "regions" which are vectors of ``struct
+ BoxRec { short x1, y1, x2, y2; }`` with ``width = x2 - x1`` and
+ ``height = y2 - y1``, so one cannot pass X11 clip lists directly.
diff --git a/Documentation/media/uapi/v4l/dev-radio.rst b/Documentation/media/uapi/v4l/dev-radio.rst
new file mode 100644
index 000000000000..5ff7cded2591
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-radio.rst
@@ -0,0 +1,52 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _radio:
+
+***************
+Radio Interface
+***************
+
+This interface is intended for AM and FM (analog) radio receivers and
+transmitters.
+
+Conventionally V4L2 radio devices are accessed through character device
+special files named ``/dev/radio`` and ``/dev/radio0`` to
+``/dev/radio63`` with major number 81 and minor numbers 64 to 127.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the radio interface set the ``V4L2_CAP_RADIO`` and
+``V4L2_CAP_TUNER`` or ``V4L2_CAP_MODULATOR`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. Other combinations of
+capability flags are reserved for future extensions.
+
+
+Supplemental Functions
+======================
+
+Radio devices can support :ref:`controls <control>`, and must support
+the :ref:`tuner or modulator <tuner>` ioctls.
+
+They do not support the video input or output, audio input or output,
+video standard, cropping and scaling, compression and streaming
+parameter, or overlay ioctls. All other ioctls and I/O methods are
+reserved for future extensions.
+
+
+Programming
+===========
+
+Radio devices may have a couple audio controls (as discussed in
+:ref:`control`) such as a volume control, possibly custom controls.
+Further all radio devices have one tuner or modulator (these are
+discussed in :ref:`tuner`) with index number zero to select the radio
+frequency and to determine if a monaural or FM stereo program is
+received/emitted. Drivers switch automatically between AM and FM
+depending on the selected frequency. The
+:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` or
+:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl reports the
+supported frequency range.
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
new file mode 100644
index 000000000000..da85be88d57e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
@@ -0,0 +1,350 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _raw-vbi:
+
+**********************
+Raw VBI Data Interface
+**********************
+
+VBI is an abbreviation of Vertical Blanking Interval, a gap in the
+sequence of lines of an analog video signal. During VBI no picture
+information is transmitted, allowing some time while the electron beam
+of a cathode ray tube TV returns to the top of the screen. Using an
+oscilloscope you will find here the vertical synchronization pulses and
+short data packages ASK modulated [1]_ onto the video signal. These are
+transmissions of services such as Teletext or Closed Caption.
+
+Subject of this interface type is raw VBI data, as sampled off a video
+signal, or to be added to a signal for output. The data format is
+similar to uncompressed video images, a number of lines times a number
+of samples per line, we call this a VBI image.
+
+Conventionally V4L2 VBI devices are accessed through character device
+special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31``
+with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is
+typically a symbolic link to the preferred VBI device. This convention
+applies to both input and output devices.
+
+To address the problems of finding related video and VBI devices VBI
+capturing and output is also available as device function under
+``/dev/video``. To capture or output raw VBI data with these devices
+applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+Accessed as ``/dev/vbi``, raw VBI capturing or output is the default
+device function.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the raw VBI capturing or output API set the
+``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively,
+in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
+read/write, streaming or asynchronous I/O methods must be supported. VBI
+devices may or may not have a tuner or modulator.
+
+
+Supplemental Functions
+======================
+
+VBI devices shall support :ref:`video input or output <video>`,
+:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>`
+ioctls as needed. The :ref:`video standard <standard>` ioctls provide
+information vital to program a VBI device, therefore must be supported.
+
+
+Raw VBI Format Negotiation
+==========================
+
+Raw VBI sampling abilities can vary, in particular the sampling
+frequency. To properly interpret the data V4L2 specifies an ioctl to
+query the sampling parameters. Moreover, to allow for some flexibility
+applications can also suggest different parameters.
+
+As usual these parameters are *not* reset at :ref:`open() <func-open>`
+time to permit Unix tool chains, programming a device and then reading
+from it as if it was a plain file. Well written V4L2 applications should
+always ensure they really get what they want, requesting reasonable
+parameters and then checking if the actual parameters are suitable.
+
+To query the current raw VBI capture parameters applications set the
+``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call
+the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
+structure. Drivers fill the struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the
+``fmt`` union.
+
+To request different parameters applications set the ``type`` field of a
+struct :ref:`v4l2_format <v4l2-format>` as above and initialize all
+fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+``vbi`` member of the ``fmt`` union, or better just modify the results
+of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error
+code only when the given parameters are ambiguous, otherwise they modify
+the parameters according to the hardware capabilities and return the
+actual parameters. When the driver allocates resources at this point, it
+may return an ``EBUSY`` error code to indicate the returned parameters are
+valid but the required resources are currently not available. That may
+happen for instance when the video and VBI areas to capture would
+overlap, or when the driver supports multiple opens and another process
+already requested VBI capturing or output. Anyway, applications must
+expect other resource allocation points which may return ``EBUSY``, at the
+:ref:`VIDIOC_STREAMON` ioctl and the first :ref:`read() <func-read>`
+, :ref:`write() <func-write>` and :ref:`select() <func-select>` calls.
+
+VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests
+and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.
+
+
+.. _v4l2-vbi-format:
+
+.. flat-table:: struct v4l2_vbi_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``sampling_rate``
+
+ - Samples per second, i. e. unit 1 Hz.
+
+ - .. row 2
+
+ - __u32
+
+ - ``offset``
+
+ - Horizontal offset of the VBI image, relative to the leading edge
+ of the line synchronization pulse and counted in samples: The
+ first sample in the VBI image will be located ``offset`` /
+ ``sampling_rate`` seconds following the leading edge. See also
+ :ref:`vbi-hsync`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``samples_per_line``
+
+ -
+
+ - .. row 4
+
+ - __u32
+
+ - ``sample_format``
+
+ - Defines the sample format as in :ref:`pixfmt`, a
+ four-character-code. [2]_ Usually this is ``V4L2_PIX_FMT_GREY``,
+ i. e. each sample consists of 8 bits with lower values oriented
+ towards the black level. Do not assume any other correlation of
+ values with the signal level. For example, the MSB does not
+ necessarily indicate if the signal is 'high' or 'low' because 128
+ may not be the mean value of the signal. Drivers shall not convert
+ the sample format by software.
+
+ - .. row 5
+
+ - __u32
+
+ - ``start``\ [2]_
+
+ - This is the scanning system line number associated with the first
+ line of the VBI image, of the first and the second field
+ respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid
+ values. The ``V4L2_VBI_ITU_525_F1_START``,
+ ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and
+ ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers
+ for each field for each 525 or 625 line format as a convenience.
+ Don't forget that ITU line numbering starts at 1, not 0. VBI input
+ drivers can return start values 0 if the hardware cannot reliable
+ identify scanning lines, VBI acquisition may not require this
+ information.
+
+ - .. row 6
+
+ - __u32
+
+ - ``count``\ [2]_
+
+ - The number of lines in the first and second field image,
+ respectively.
+
+ - .. row 7
+
+ - :cspan:`2`
+
+ Drivers should be as flexibility as possible. For example, it may
+ be possible to extend or move the VBI capture window down to the
+ picture area, implementing a 'full field mode' to capture data
+ service transmissions embedded in the picture.
+
+ An application can set the first or second ``count`` value to zero
+ if no data is required from the respective field; ``count``\ [1]
+ if the scanning system is progressive, i. e. not interlaced. The
+ corresponding start value shall be ignored by the application and
+ driver. Anyway, drivers may not support single field capturing and
+ return both count values non-zero.
+
+ Both ``count`` values set to zero, or line numbers outside the
+ bounds depicted in :ref:`vbi-525` and :ref:`vbi-625`, or a
+ field image covering lines of two fields, are invalid and shall
+ not be returned by the driver.
+
+ To initialize the ``start`` and ``count`` fields, applications
+ must first determine the current video standard selection. The
+ :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field
+ of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated
+ for this purpose.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - See :ref:`vbifmt-flags` below. Currently only drivers set flags,
+ applications must set this field to zero.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [2]_
+
+ - This array is reserved for future extensions. Drivers and
+ applications must set it to zero.
+
+
+
+.. _vbifmt-flags:
+
+.. flat-table:: Raw VBI Format Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_VBI_UNSYNC``
+
+ - 0x0001
+
+ - This flag indicates hardware which does not properly distinguish
+ between fields. Normally the VBI image stores the first field
+ (lower scanning line numbers) first in memory. This may be a top
+ or bottom field depending on the video standard. When this flag is
+ set the first or second field may be stored first, however the
+ fields are still in correct temporal order with the older field
+ first in memory. [3]_
+
+ - .. row 2
+
+ - ``V4L2_VBI_INTERLACED``
+
+ - 0x0002
+
+ - By default the two field images will be passed sequentially; all
+ lines of the first field followed by all lines of the second field
+ (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and
+ ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in
+ memory depends on the video standard). When this flag is set, the
+ two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The
+ first line of the first field followed by the first line of the
+ second field, then the two second lines, and so on. Such a layout
+ may be necessary when the hardware has been programmed to capture
+ or output interlaced video images and is unable to separate the
+ fields for VBI capturing at the same time. For simplicity setting
+ this flag implies that both ``count`` values are equal and
+ non-zero.
+
+
+
+.. _vbi-hsync:
+
+.. figure:: dev-raw-vbi_files/vbi_hsync.*
+ :alt: vbi_hsync.pdf / vbi_hsync.gif
+ :align: center
+
+ **Figure 4.1. Line synchronization**
+
+
+.. _vbi-525:
+
+.. figure:: dev-raw-vbi_files/vbi_525.*
+ :alt: vbi_525.pdf / vbi_525.gif
+ :align: center
+
+ **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
+
+
+
+.. _vbi-625:
+
+.. figure:: dev-raw-vbi_files/vbi_625.*
+ :alt: vbi_625.pdf / vbi_625.gif
+ :align: center
+
+ **Figure 4.3. ITU-R 625 line numbering**
+
+
+
+Remember the VBI image format depends on the selected video standard,
+therefore the application must choose a new standard or query the
+current standard first. Attempts to read or write data ahead of format
+negotiation, or after switching the video standard which may invalidate
+the negotiated VBI parameters, should be refused by the driver. A format
+change during active I/O is not permitted.
+
+
+Reading and writing VBI images
+==============================
+
+To assure synchronization with the field number and easier
+implementation, the smallest unit of data passed at a time is one frame,
+consisting of two fields of VBI images immediately following in memory.
+
+The total size of a frame computes as follows:
+
+
+.. code-block:: c
+
+ (count[0] + count[1]) * samples_per_line * sample size in bytes
+
+The sample size is most likely always one byte, applications must check
+the ``sample_format`` field though, to function properly with other
+drivers.
+
+A VBI device may support :ref:`read/write <rw>` and/or streaming
+(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
+The latter bears the possibility of synchronizing video and VBI data by
+using buffer timestamps.
+
+Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the
+first :ref:`read() <func-read>`, :ref:`write() <func-write>` and
+:ref:`select() <func-select>` call can be resource allocation
+points returning an ``EBUSY`` error code if the required hardware resources
+are temporarily unavailable, for example the device is already in use by
+another process.
+
+.. [1]
+ ASK: Amplitude-Shift Keying. A high signal level represents a '1'
+ bit, a low level a '0' bit.
+
+.. [2]
+ A few devices may be unable to sample VBI data at all but can extend
+ the video capture window to the VBI region.
+
+.. [3]
+ Most VBI services transmit on both fields, but some have different
+ semantics depending on the field number. These cannot be reliable
+ decoded or encoded when ``V4L2_VBI_UNSYNC`` is set.
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif
new file mode 100644
index 000000000000..5580b690d504
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf
new file mode 100644
index 000000000000..9e72c25b208d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif
new file mode 100644
index 000000000000..34e3251983c4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf
new file mode 100644
index 000000000000..765235e33a4d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif
new file mode 100644
index 000000000000..b02434d3b356
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf
new file mode 100644
index 000000000000..200b668189bf
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-rds.rst b/Documentation/media/uapi/v4l/dev-rds.rst
new file mode 100644
index 000000000000..6a0b1a874668
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-rds.rst
@@ -0,0 +1,255 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _rds:
+
+*************
+RDS Interface
+*************
+
+The Radio Data System transmits supplementary information in binary
+format, for example the station name or travel information, on an
+inaudible audio subcarrier of a radio program. This interface is aimed
+at devices capable of receiving and/or transmitting RDS information.
+
+For more information see the core RDS standard :ref:`iec62106` and the
+RBDS standard :ref:`nrsc4`.
+
+Note that the RBDS standard as is used in the USA is almost identical to
+the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only
+some of the fields have slightly different meanings. See the RBDS
+standard for more information.
+
+The RBDS standard also specifies support for MMBS (Modified Mobile
+Search). This is a proprietary format which seems to be discontinued.
+The RDS interface does not support this format. Should support for MMBS
+(or the so-called 'E blocks' in general) be needed, then please contact
+the linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the RDS capturing API set the
+``V4L2_CAP_RDS_CAPTURE`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. Any tuner that
+supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
+``capability`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`. If the
+driver only passes RDS blocks without interpreting the data the
+``V4L2_TUNER_CAP_RDS_BLOCK_IO`` flag has to be set, see
+:ref:`Reading RDS data <reading-rds-data>`. For future use the flag
+``V4L2_TUNER_CAP_RDS_CONTROLS`` has also been defined. However, a driver
+for a radio tuner with this capability does not yet exist, so if you are
+planning to write such a driver you should discuss this on the
+linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+Whether an RDS signal is present can be detected by looking at the
+``rxsubchans`` field of struct :ref:`v4l2_tuner <v4l2-tuner>`: the
+``V4L2_TUNER_SUB_RDS`` will be set if RDS data was detected.
+
+Devices supporting the RDS output API set the ``V4L2_CAP_RDS_OUTPUT``
+flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. Any modulator that
+supports RDS will set the ``V4L2_TUNER_CAP_RDS`` flag in the
+``capability`` field of struct
+:ref:`v4l2_modulator <v4l2-modulator>`. In order to enable the RDS
+transmission one must set the ``V4L2_TUNER_SUB_RDS`` bit in the
+``txsubchans`` field of struct
+:ref:`v4l2_modulator <v4l2-modulator>`. If the driver only passes RDS
+blocks without interpreting the data the ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
+flag has to be set. If the tuner is capable of handling RDS entities
+like program identification codes and radio text, the flag
+``V4L2_TUNER_CAP_RDS_CONTROLS`` should be set, see
+:ref:`Writing RDS data <writing-rds-data>` and
+:ref:`FM Transmitter Control Reference <fm-tx-controls>`.
+
+
+.. _reading-rds-data:
+
+Reading RDS data
+================
+
+RDS data can be read from the radio device with the
+:ref:`read() <func-read>` function. The data is packed in groups of
+three bytes.
+
+
+.. _writing-rds-data:
+
+Writing RDS data
+================
+
+RDS data can be written to the radio device with the
+:ref:`write() <func-write>` function. The data is packed in groups of
+three bytes, as follows:
+
+
+RDS datastructures
+==================
+
+
+.. _v4l2-rds-data:
+
+.. flat-table:: struct v4l2_rds_data
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 5
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``lsb``
+
+ - Least Significant Byte of RDS Block
+
+ - .. row 2
+
+ - __u8
+
+ - ``msb``
+
+ - Most Significant Byte of RDS Block
+
+ - .. row 3
+
+ - __u8
+
+ - ``block``
+
+ - Block description
+
+
+
+.. _v4l2-rds-block:
+
+.. flat-table:: Block description
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 5
+
+
+ - .. row 1
+
+ - Bits 0-2
+
+ - Block (aka offset) of the received data.
+
+ - .. row 2
+
+ - Bits 3-5
+
+ - Deprecated. Currently identical to bits 0-2. Do not use these
+ bits.
+
+ - .. row 3
+
+ - Bit 6
+
+ - Corrected bit. Indicates that an error was corrected for this data
+ block.
+
+ - .. row 4
+
+ - Bit 7
+
+ - Error bit. Indicates that an uncorrectable error occurred during
+ reception of this block.
+
+
+
+.. _v4l2-rds-block-codes:
+
+.. flat-table:: Block defines
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 5
+
+
+ - .. row 1
+
+ - V4L2_RDS_BLOCK_MSK
+
+ -
+ - 7
+
+ - Mask for bits 0-2 to get the block ID.
+
+ - .. row 2
+
+ - V4L2_RDS_BLOCK_A
+
+ -
+ - 0
+
+ - Block A.
+
+ - .. row 3
+
+ - V4L2_RDS_BLOCK_B
+
+ -
+ - 1
+
+ - Block B.
+
+ - .. row 4
+
+ - V4L2_RDS_BLOCK_C
+
+ -
+ - 2
+
+ - Block C.
+
+ - .. row 5
+
+ - V4L2_RDS_BLOCK_D
+
+ -
+ - 3
+
+ - Block D.
+
+ - .. row 6
+
+ - V4L2_RDS_BLOCK_C_ALT
+
+ -
+ - 4
+
+ - Block C'.
+
+ - .. row 7
+
+ - V4L2_RDS_BLOCK_INVALID
+
+ - read-only
+
+ - 7
+
+ - An invalid block.
+
+ - .. row 8
+
+ - V4L2_RDS_BLOCK_CORRECTED
+
+ - read-only
+
+ - 0x40
+
+ - A bit error was detected but corrected.
+
+ - .. row 9
+
+ - V4L2_RDS_BLOCK_ERROR
+
+ - read-only
+
+ - 0x80
+
+ - An uncorrectable error occurred.
diff --git a/Documentation/media/uapi/v4l/dev-sdr.rst b/Documentation/media/uapi/v4l/dev-sdr.rst
new file mode 100644
index 000000000000..fc4053f957fb
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-sdr.rst
@@ -0,0 +1,120 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sdr:
+
+**************************************
+Software Defined Radio Interface (SDR)
+**************************************
+
+SDR is an abbreviation of Software Defined Radio, the radio device which
+uses application software for modulation or demodulation. This interface
+is intended for controlling and data streaming of such devices.
+
+SDR devices are accessed through character device special files named
+``/dev/swradio0`` to ``/dev/swradio255`` with major number 81 and
+dynamically allocated minor numbers 0 to 255.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the SDR receiver interface set the
+``V4L2_CAP_SDR_CAPTURE`` and ``V4L2_CAP_TUNER`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
+device has an Analog to Digital Converter (ADC), which is a mandatory
+element for the SDR receiver.
+
+Devices supporting the SDR transmitter interface set the
+``V4L2_CAP_SDR_OUTPUT`` and ``V4L2_CAP_MODULATOR`` flag in the
+``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. That flag means the
+device has an Digital to Analog Converter (DAC), which is a mandatory
+element for the SDR transmitter.
+
+At least one of the read/write, streaming or asynchronous I/O methods
+must be supported.
+
+
+Supplemental Functions
+======================
+
+SDR devices can support :ref:`controls <control>`, and must support
+the :ref:`tuner` ioctls. Tuner ioctls are used for setting the
+ADC/DAC sampling rate (sampling frequency) and the possible radio
+frequency (RF).
+
+The ``V4L2_TUNER_SDR`` tuner type is used for setting SDR device ADC/DAC
+frequency, and the ``V4L2_TUNER_RF`` tuner type is used for setting
+radio frequency. The tuner index of the RF tuner (if any) must always
+follow the SDR tuner index. Normally the SDR tuner is #0 and the RF
+tuner is #1.
+
+The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl is
+not supported.
+
+
+Data Format Negotiation
+=======================
+
+The SDR device uses the :ref:`format` ioctls to select the
+capture and output format. Both the sampling resolution and the data
+streaming format are bound to that selectable format. In addition to the
+basic :ref:`format` ioctls, the
+:ref:`VIDIOC_ENUM_FMT` ioctl must be supported as
+well.
+
+To use the :ref:`format` ioctls applications set the ``type``
+field of a struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_SDR_CAPTURE`` or ``V4L2_BUF_TYPE_SDR_OUTPUT`` and use
+the struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` ``sdr`` member
+of the ``fmt`` union as needed per the desired operation. Currently
+there is two fields, ``pixelformat`` and ``buffersize``, of struct
+struct :ref:`v4l2_sdr_format <v4l2-sdr-format>` which are used.
+Content of the ``pixelformat`` is V4L2 FourCC code of the data format.
+The ``buffersize`` field is maximum buffer size in bytes required for
+data transfer, set by the driver in order to inform application.
+
+
+.. _v4l2-sdr-format:
+
+.. flat-table:: struct v4l2_sdr_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The data format or type of compression, set by the application.
+ This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines SDR
+ formats in :ref:`sdr-formats`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``buffersize``
+
+ - Maximum size in bytes required for data. Value is set by the
+ driver.
+
+ - .. row 3
+
+ - __u8
+
+ - ``reserved[24]``
+
+ - This array is reserved for future extensions. Drivers and
+ applications must set it to zero.
+
+
+An SDR device may support :ref:`read/write <rw>` and/or streaming
+(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O.
diff --git a/Documentation/media/uapi/v4l/dev-sliced-vbi.rst b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst
new file mode 100644
index 000000000000..fbd04fee0484
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-sliced-vbi.rst
@@ -0,0 +1,822 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sliced:
+
+*************************
+Sliced VBI Data Interface
+*************************
+
+VBI stands for Vertical Blanking Interval, a gap in the sequence of
+lines of an analog video signal. During VBI no picture information is
+transmitted, allowing some time while the electron beam of a cathode ray
+tube TV returns to the top of the screen.
+
+Sliced VBI devices use hardware to demodulate data transmitted in the
+VBI. V4L2 drivers shall *not* do this by software, see also the
+:ref:`raw VBI interface <raw-vbi>`. The data is passed as short
+packets of fixed size, covering one scan line each. The number of
+packets per video frame is variable.
+
+Sliced VBI capture and output devices are accessed through the same
+character special files as raw VBI devices. When a driver supports both
+interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI
+capturing or output, and the sliced VBI function is only available after
+calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined
+below. Likewise a ``/dev/video`` device may support the sliced VBI API,
+however the default function here is video capturing or output.
+Different file descriptors must be used to pass raw and sliced VBI data
+simultaneously, if this is supported by the driver.
+
+
+Querying Capabilities
+=====================
+
+Devices supporting the sliced VBI capturing or output API set the
+``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag
+respectively, in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
+read/write, streaming or asynchronous :ref:`I/O methods <io>` must be
+supported. Sliced VBI devices may have a tuner or modulator.
+
+
+Supplemental Functions
+======================
+
+Sliced VBI devices shall support :ref:`video input or output <video>`
+and :ref:`tuner or modulator <tuner>` ioctls if they have these
+capabilities, and they may support :ref:`control` ioctls.
+The :ref:`video standard <standard>` ioctls provide information vital
+to program a sliced VBI device, therefore must be supported.
+
+
+.. _sliced-vbi-format-negotitation:
+
+Sliced VBI Format Negotiation
+=============================
+
+To find out which data services are supported by the hardware
+applications can call the
+:ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl.
+All drivers implementing the sliced VBI interface must support this
+ioctl. The results may differ from those of the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI
+lines the hardware can capture or output per frame, or the number of
+services it can identify on a given line are limited. For example on PAL
+line 16 the hardware may be able to look for a VPS or Teletext signal,
+but not both at the same time.
+
+To determine the currently selected services applications set the
+``type`` field of struct :ref:`v4l2_format <v4l2-format>` to
+``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
+``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced``
+member, a struct
+:ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`.
+
+Applications can request different parameters by initializing or
+modifying the ``fmt.sliced`` member and calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the
+:ref:`struct v4l2_format <v4l2-format>` structure.
+
+The sliced VBI API is more complicated than the raw VBI API because the
+hardware must be told which VBI service to expect on each scan line. Not
+all services may be supported by the hardware on all lines (this is
+especially true for VBI output where Teletext is often unsupported and
+other services can only be inserted in one specific line). In many
+cases, however, it is sufficient to just set the ``service_set`` field
+to the required services and let the driver fill the ``service_lines``
+array according to hardware capabilities. Only if more precise control
+is needed should the programmer set the ``service_lines`` array
+explicitly.
+
+The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters
+according to hardware capabilities. When the driver allocates resources
+at this point, it may return an ``EBUSY`` error code if the required
+resources are temporarily unavailable. Other resource allocation points
+which may return ``EBUSY`` can be the
+:ref:`VIDIOC_STREAMON` ioctl and the first
+:ref:`read() <func-read>`, :ref:`write() <func-write>` and
+:ref:`select() <func-select>` call.
+
+
+.. _v4l2-sliced-vbi-format:
+
+struct v4l2_sliced_vbi_format
+-----------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 3 2 2 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``service_set``
+
+ - :cspan:`2`
+
+ If ``service_set`` is non-zero when passed with
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
+ :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines``
+ array will be filled by the driver according to the services
+ specified in this field. For example, if ``service_set`` is
+ initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
+ a driver for the cx25840 video decoder sets lines 7-22 of both
+ fields [1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
+ field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
+ zero, then the values of ``service_lines`` will be used instead.
+
+ On return the driver sets this field to the union of all elements
+ of the returned ``service_lines`` array. It may contain less
+ services than requested, perhaps just one, if the hardware cannot
+ handle more services simultaneously. It may be empty (zero) if
+ none of the requested services are supported by the hardware.
+
+ - .. row 2
+
+ - __u16
+
+ - ``service_lines``\ [2][24]
+
+ - :cspan:`2`
+
+ Applications initialize this array with sets of data services the
+ driver shall look for or insert on the respective scan line.
+ Subject to hardware capabilities drivers return the requested set,
+ a subset, which may be just a single service, or an empty set.
+ When the hardware cannot handle multiple services on the same line
+ the driver shall choose one. No assumptions can be made on which
+ service the driver chooses.
+
+ Data services are defined in :ref:`vbi-services2`. Array indices
+ map to ITU-R line numbers (see also :ref:`vbi-525` and
+ :ref:`vbi-625`) as follows:
+
+ - .. row 3
+
+ -
+ -
+ - Element
+
+ - 525 line systems
+
+ - 625 line systems
+
+ - .. row 4
+
+ -
+ -
+ - ``service_lines``\ [0][1]
+
+ - 1
+
+ - 1
+
+ - .. row 5
+
+ -
+ -
+ - ``service_lines``\ [0][23]
+
+ - 23
+
+ - 23
+
+ - .. row 6
+
+ -
+ -
+ - ``service_lines``\ [1][1]
+
+ - 264
+
+ - 314
+
+ - .. row 7
+
+ -
+ -
+ - ``service_lines``\ [1][23]
+
+ - 286
+
+ - 336
+
+ - .. row 8
+
+ -
+ -
+ - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
+ ``service_lines``\ [1][0] to zero. The
+ ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
+ ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
+ defines give the start line numbers for each field for each 525 or
+ 625 line format as a convenience. Don't forget that ITU line
+ numbering starts at 1, not 0.
+
+ - .. row 9
+
+ - __u32
+
+ - ``io_size``
+
+ - :cspan:`2` Maximum number of bytes passed by one
+ :ref:`read() <func-read>` or :ref:`write() <func-write>` call,
+ and the buffer size in bytes for the
+ :ref:`VIDIOC_QBUF` and
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
+ to the size of struct
+ :ref:`v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` times the
+ number of non-zero elements in the returned ``service_lines``
+ array (that is the number of lines potentially carrying data).
+
+ - .. row 10
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - :cspan:`2` This array is reserved for future extensions.
+ Applications and drivers must set it to zero.
+
+
+
+.. _vbi-services2:
+
+Sliced VBI services
+-------------------
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 2 1 1 2 2
+
+
+ - .. row 1
+
+ - Symbol
+
+ - Value
+
+ - Reference
+
+ - Lines, usually
+
+ - Payload
+
+ - .. row 2
+
+ - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
+
+ - 0x0001
+
+ - :ref:`ets300706`, :ref:`itu653`
+
+ - PAL/SECAM line 7-22, 320-335 (second field 7-22)
+
+ - Last 42 of the 45 byte Teletext packet, that is without clock
+ run-in and framing code, lsb first transmitted.
+
+ - .. row 3
+
+ - ``V4L2_SLICED_VPS``
+
+ - 0x0400
+
+ - :ref:`ets300231`
+
+ - PAL line 16
+
+ - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
+ first transmitted.
+
+ - .. row 4
+
+ - ``V4L2_SLICED_CAPTION_525``
+
+ - 0x1000
+
+ - :ref:`cea608`
+
+ - NTSC line 21, 284 (second field 21)
+
+ - Two bytes in transmission order, including parity bit, lsb first
+ transmitted.
+
+ - .. row 5
+
+ - ``V4L2_SLICED_WSS_625``
+
+ - 0x4000
+
+ - :ref:`itu1119`, :ref:`en300294`
+
+ - PAL/SECAM line 23
+
+ -
+
+ ::
+
+ Byte 0 1
+ msb lsb msb lsb
+ Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
+
+ - .. row 6
+
+ - ``V4L2_SLICED_VBI_525``
+
+ - 0x1000
+
+ - :cspan:`2` Set of services applicable to 525 line systems.
+
+ - .. row 7
+
+ - ``V4L2_SLICED_VBI_625``
+
+ - 0x4401
+
+ - :cspan:`2` Set of services applicable to 625 line systems.
+
+
+Drivers may return an ``EINVAL`` error code when applications attempt to
+read or write data without prior format negotiation, after switching the
+video standard (which may invalidate the negotiated VBI parameters) and
+after switching the video input (which may change the video standard as
+a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may
+return an ``EBUSY`` error code when applications attempt to change the
+format while i/o is in progress (between a
+:ref:`VIDIOC_STREAMON` and
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
+:ref:`read() <func-read>` or :ref:`write() <func-write>` call).
+
+
+Reading and writing sliced VBI data
+===================================
+
+A single :ref:`read() <func-read>` or :ref:`write() <func-write>`
+call must pass all data belonging to one video frame. That is an array
+of :ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` structures with one or
+more elements and a total size not exceeding ``io_size`` bytes. Likewise
+in streaming I/O mode one buffer of ``io_size`` bytes must contain data
+of one video frame. The ``id`` of unused
+:ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` elements must be zero.
+
+
+.. _v4l2-sliced-vbi-data:
+
+struct v4l2_sliced_vbi_data
+---------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - A flag from :ref:`vbi-services` identifying the type of data in
+ this packet. Only a single bit must be set. When the ``id`` of a
+ captured packet is zero, the packet is empty and the contents of
+ other fields are undefined. Applications shall ignore empty
+ packets. When the ``id`` of a packet for output is zero the
+ contents of the ``data`` field are undefined and the driver must
+ no longer insert data on the requested ``field`` and ``line``.
+
+ - .. row 2
+
+ - __u32
+
+ - ``field``
+
+ - The video field number this data has been captured from, or shall
+ be inserted at. ``0`` for the first field, ``1`` for the second
+ field.
+
+ - .. row 3
+
+ - __u32
+
+ - ``line``
+
+ - The field (as opposed to frame) line number this data has been
+ captured from, or shall be inserted at. See :ref:`vbi-525` and
+ :ref:`vbi-625` for valid values. Sliced VBI capture devices can
+ set the line number of all packets to ``0`` if the hardware cannot
+ reliably identify scan lines. The field number must always be
+ valid.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``
+
+ - This field is reserved for future extensions. Applications and
+ drivers must set it to zero.
+
+ - .. row 5
+
+ - __u8
+
+ - ``data``\ [48]
+
+ - The packet payload. See :ref:`vbi-services` for the contents and
+ number of bytes passed for each data type. The contents of padding
+ bytes at the end of this array are undefined, drivers and
+ applications shall ignore them.
+
+
+Packets are always passed in ascending line number order, without
+duplicate line numbers. The :ref:`write() <func-write>` function and
+the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
+error code when applications violate this rule. They must also return an
+EINVAL error code when applications pass an incorrect field or line
+number, or a combination of ``field``, ``line`` and ``id`` which has not
+been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are
+unknown the driver must pass the packets in transmitted order. The
+driver can insert empty packets with ``id`` set to zero anywhere in the
+packet array.
+
+To assure synchronization and to distinguish from frame dropping, when a
+captured frame does not carry any of the requested data services drivers
+must pass one or more empty packets. When an application fails to pass
+VBI data in time for output, the driver must output the last VPS and WSS
+packet again, and disable the output of Closed Caption and Teletext
+data, or output data which is ignored by Closed Caption and Teletext
+decoders.
+
+A sliced VBI device may support :ref:`read/write <rw>` and/or
+streaming (:ref:`memory mapping <mmap>` and/or
+:ref:`user pointer <userp>`) I/O. The latter bears the possibility of
+synchronizing video and VBI data by using buffer timestamps.
+
+
+Sliced VBI Data in MPEG Streams
+===============================
+
+If a device can produce an MPEG output stream, it may be capable of
+providing
+:ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
+as data embedded in the MPEG stream. Users or applications control this
+sliced VBI data insertion with the
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control.
+
+If the driver does not provide the
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control, or only allows that control to be set to
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
+then the device cannot embed sliced VBI data in the MPEG stream.
+
+The
+:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
+control does not implicitly set the device driver to capture nor cease
+capturing sliced VBI data. The control only indicates to embed sliced
+VBI data in the MPEG stream, if an application has negotiated sliced VBI
+service be captured.
+
+It may also be the case that a device can embed sliced VBI data in only
+certain types of MPEG streams: for example in an MPEG-2 PS but not an
+MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
+the sliced VBI data will be embedded in MPEG stream types when
+supported, and silently omitted from MPEG stream types where sliced VBI
+data insertion is not supported by the device.
+
+The following subsections specify the format of the embedded sliced VBI
+data.
+
+
+MPEG Stream Embedded, Sliced VBI Data Format: NONE
+--------------------------------------------------
+
+The
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
+embedded sliced VBI format shall be interpreted by drivers as a control
+to cease embedding sliced VBI data in MPEG streams. Neither the device
+nor driver shall insert "empty" embedded sliced VBI data packets in the
+MPEG stream when this format is set. No MPEG stream data structures are
+specified for this format.
+
+
+MPEG Stream Embedded, Sliced VBI Data Format: IVTV
+--------------------------------------------------
+
+The
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
+embedded sliced VBI format, when supported, indicates to the driver to
+embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
+Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
+MPEG stream.
+
+*Historical context*: This format specification originates from a
+custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
+This format has already been informally specified in the kernel sources
+in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The
+maximum size of the payload and other aspects of this format are driven
+by the CX23415 MPEG decoder's capabilities and limitations with respect
+to extracting, decoding, and displaying sliced VBI data embedded within
+an MPEG stream.
+
+This format's use is *not* exclusive to the ``ivtv`` driver *nor*
+exclusive to CX2341x devices, as the sliced VBI data packet insertion
+into the MPEG stream is implemented in driver software. At least the
+``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
+this format as well.
+
+The following definitions specify the payload of the MPEG-2 *Private
+Stream 1 PES* packets that contain sliced VBI data when
+:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
+is set. (The MPEG-2 *Private Stream 1 PES* packet header and
+encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
+refer to the MPEG-2 specifications for details on those packet headers.)
+
+The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
+sliced VBI data is specified by struct
+:ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>`. The
+payload is variable length, depending on the actual number of lines of
+sliced VBI data present in a video frame. The payload may be padded at
+the end with unspecified fill bytes to align the end of the payload to a
+4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
+with 18 lines/field with 43 bytes of data/line and a 4 byte magic
+number).
+
+
+.. _v4l2-mpeg-vbi-fmt-ivtv:
+
+struct v4l2_mpeg_vbi_fmt_ivtv
+-----------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``magic``\ [4]
+
+ -
+ - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
+ indicates this is a valid sliced VBI data payload and also
+ indicates which member of the anonymous union, ``itv0`` or
+ ``ITV0``, to use for the payload data.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_mpeg_vbi_itv0 <v4l2-mpeg-vbi-itv0>`
+
+ - ``itv0``
+
+ - The primary form of the sliced VBI data payload that contains
+ anywhere from 1 to 35 lines of sliced VBI data. Line masks are
+ provided in this form of the payload indicating which VBI lines
+ are provided.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
+
+ - ``ITV0``
+
+ - An alternate form of the sliced VBI data payload used when 36
+ lines of sliced VBI data are present. No line masks are provided
+ in this form of the payload; all valid line mask bits are
+ implcitly set.
+
+
+
+.. _v4l2-mpeg-vbi-fmt-ivtv-magic:
+
+Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
+-------------------------------------------------------------
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Defined Symbol
+
+ - Value
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
+
+ - "itv0"
+
+ - Indicates the ``itv0`` member of the union in struct
+ :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
+ valid.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
+
+ - "ITV0"
+
+ - Indicates the ``ITV0`` member of the union in struct
+ :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
+ valid and that 36 lines of sliced VBI data are present.
+
+
+
+.. _v4l2-mpeg-vbi-itv0:
+
+struct v4l2_mpeg_vbi_itv0
+-------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __le32
+
+ - ``linemask``\ [2]
+
+ - Bitmasks indicating the VBI service lines present. These
+ ``linemask`` values are stored in little endian byte order in the
+ MPEG stream. Some reference ``linemask`` bit positions with their
+ corresponding VBI line number and video field are given below.
+ b\ :sub:`0` indicates the least significant bit of a ``linemask``
+ value:
+
+
+
+ ::
+
+ linemask[0] b0: line 6 first field
+ linemask[0] b17: line 23 first field
+ linemask[0] b18: line 6 second field
+ linemask[0] b31: line 19 second field
+ linemask[1] b0: line 20 second field
+ linemask[1] b3: line 23 second field
+ linemask[1] b4-b31: unused and set to 0
+
+ - .. row 2
+
+ - struct
+ :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
+
+ - ``line``\ [35]
+
+ - This is a variable length array that holds from 1 to 35 lines of
+ sliced VBI data. The sliced VBI data lines present correspond to
+ the bits set in the ``linemask`` array, starting from b\ :sub:`0`
+ of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
+ and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of
+ ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
+ found set in the ``linemask`` array, ``line``\ [1] corresponds to
+ the second bit found set in the ``linemask`` array, etc. If no
+ ``linemask`` array bits are set, then ``line``\ [0] may contain
+ one line of unspecified data that should be ignored by
+ applications.
+
+
+
+.. _v4l2-mpeg-vbi-itv0-1:
+
+struct v4l2_mpeg_vbi_ITV0
+-------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct
+ :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
+
+ - ``line``\ [36]
+
+ - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
+ through ``line``\ [17] correspond to lines 6 through 23 of the
+ first field. ``line``\ [18] through ``line``\ [35] corresponds to
+ lines 6 through 23 of the second field.
+
+
+
+.. _v4l2-mpeg-vbi-itv0-line:
+
+struct v4l2_mpeg_vbi_itv0_line
+------------------------------
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``id``
+
+ - A line identifier value from
+ :ref:`ITV0-Line-Identifier-Constants` that indicates the type of
+ sliced VBI data stored on this line.
+
+ - .. row 2
+
+ - __u8
+
+ - ``data``\ [42]
+
+ - The sliced VBI data for the line.
+
+
+
+.. _ITV0-Line-Identifier-Constants:
+
+Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
+------------------------------------------------------------
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Defined Symbol
+
+ - Value
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
+
+ - 1
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
+
+ - 4
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VBI_IVTV_WSS_625``
+
+ - 5
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VBI_IVTV_VPS``
+
+ - 7
+
+ - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
+ description of the line payload.
+
+
+
+.. [1]
+ According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
+ field and lines 5-22 of the second field may carry Teletext data.
diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
new file mode 100644
index 000000000000..39d3d860dda4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev.rst
@@ -0,0 +1,491 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _subdev:
+
+********************
+Sub-device Interface
+********************
+
+The complex nature of V4L2 devices, where hardware is often made of
+several integrated circuits that need to interact with each other in a
+controlled way, leads to complex V4L2 drivers. The drivers usually
+reflect the hardware model in software, and model the different hardware
+components as software blocks called sub-devices.
+
+V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
+implements the media device API, they will automatically inherit from
+media entities. Applications will be able to enumerate the sub-devices
+and discover the hardware topology using the media entities, pads and
+links enumeration API.
+
+In addition to make sub-devices discoverable, drivers can also choose to
+make them directly configurable by applications. When both the
+sub-device driver and the V4L2 device driver support this, sub-devices
+will feature a character device node on which ioctls can be called to
+
+- query, read and write sub-devices controls
+
+- subscribe and unsubscribe to events and retrieve them
+
+- negotiate image formats on individual pads
+
+Sub-device character device nodes, conventionally named
+``/dev/v4l-subdev*``, use major number 81.
+
+
+Controls
+========
+
+Most V4L2 controls are implemented by sub-device hardware. Drivers
+usually merge all controls and expose them through video device nodes.
+Applications can control all sub-devices through a single interface.
+
+Complex devices sometimes implement the same control in different pieces
+of hardware. This situation is common in embedded platforms, where both
+sensors and image processing hardware implement identical functions,
+such as contrast adjustment, white balance or faulty pixels correction.
+As the V4L2 controls API doesn't support several identical controls in a
+single device, all but one of the identical controls are hidden.
+
+Applications can access those hidden controls through the sub-device
+node with the V4L2 control API described in :ref:`control`. The ioctls
+behave identically as when issued on V4L2 device nodes, with the
+exception that they deal only with controls implemented in the
+sub-device.
+
+Depending on the driver, those controls might also be exposed through
+one (or several) V4L2 device nodes.
+
+
+Events
+======
+
+V4L2 sub-devices can notify applications of events as described in
+:ref:`event`. The API behaves identically as when used on V4L2 device
+nodes, with the exception that it only deals with events generated by
+the sub-device. Depending on the driver, those events might also be
+reported on one (or several) V4L2 device nodes.
+
+
+.. _pad-level-formats:
+
+Pad-level Formats
+=================
+
+ **Warning**
+
+ Pad-level formats are only applicable to very complex device that
+ need to expose low-level format configuration to user space. Generic
+ V4L2 applications do *not* need to use the API described in this
+ section.
+
+ **Note**
+
+ For the purpose of this section, the term *format* means the
+ combination of media bus data format, frame width and frame height.
+
+Image formats are typically negotiated on video capture and output
+devices using the format and
+:ref:`selection <VIDIOC_SUBDEV_G_SELECTION>` ioctls. The driver is
+responsible for configuring every block in the video pipeline according
+to the requested format at the pipeline input and/or output.
+
+For complex devices, such as often found in embedded systems, identical
+image sizes at the output of a pipeline can be achieved using different
+hardware configurations. One such example is shown on
+:ref:`pipeline-scaling`, where image scaling can be performed on both
+the video sensor and the host image processing hardware.
+
+
+.. _pipeline-scaling:
+
+.. figure:: dev-subdev_files/pipeline.*
+ :alt: pipeline.pdf / pipeline.png
+ :align: center
+
+ Image Format Negotiation on Pipelines
+
+ High quality and high speed pipeline configuration
+
+
+
+The sensor scaler is usually of less quality than the host scaler, but
+scaling on the sensor is required to achieve higher frame rates.
+Depending on the use case (quality vs. speed), the pipeline must be
+configured differently. Applications need to configure the formats at
+every point in the pipeline explicitly.
+
+Drivers that implement the :ref:`media API <media-controller-intro>`
+can expose pad-level image format configuration to applications. When
+they do, applications can use the
+:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls. to
+negotiate formats on a per-pad basis.
+
+Applications are responsible for configuring coherent parameters on the
+whole pipeline and making sure that connected pads have compatible
+formats. The pipeline is checked for formats mismatch at
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` time, and an ``EPIPE`` error
+code is then returned if the configuration is invalid.
+
+Pad-level image format configuration support can be tested by calling
+the :ref:`VIDIOC_SUBDEV_G_FMT` ioctl on pad
+0. If the driver returns an ``EINVAL`` error code pad-level format
+configuration is not supported by the sub-device.
+
+
+Format Negotiation
+------------------
+
+Acceptable formats on pads can (and usually do) depend on a number of
+external parameters, such as formats on other pads, active links, or
+even controls. Finding a combination of formats on all pads in a video
+pipeline, acceptable to both application and driver, can't rely on
+formats enumeration only. A format negotiation mechanism is required.
+
+Central to the format negotiation mechanism are the get/set format
+operations. When called with the ``which`` argument set to
+:ref:`V4L2_SUBDEV_FORMAT_TRY <VIDIOC_SUBDEV_G_FMT>`, the
+:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` and
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctls operate on
+a set of formats parameters that are not connected to the hardware
+configuration. Modifying those 'try' formats leaves the device state
+untouched (this applies to both the software state stored in the driver
+and the hardware state stored in the device itself).
+
+While not kept as part of the device state, try formats are stored in
+the sub-device file handles. A
+:ref:`VIDIOC_SUBDEV_G_FMT <VIDIOC_SUBDEV_G_FMT>` call will return
+the last try format set *on the same sub-device file handle*. Several
+applications querying the same sub-device at the same time will thus not
+interact with each other.
+
+To find out whether a particular format is supported by the device,
+applications use the
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl. Drivers
+verify and, if needed, change the requested ``format`` based on device
+requirements and return the possibly modified value. Applications can
+then choose to try a different format or accept the returned value and
+continue.
+
+Formats returned by the driver during a negotiation iteration are
+guaranteed to be supported by the device. In particular, drivers
+guarantee that a returned format will not be further changed if passed
+to an :ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` call as-is
+(as long as external parameters, such as formats on other pads or links'
+configuration are not changed).
+
+Drivers automatically propagate formats inside sub-devices. When a try
+or active format is set on a pad, corresponding formats on other pads of
+the same sub-device can be modified by the driver. Drivers are free to
+modify formats as required by the device. However, they should comply
+with the following rules when possible:
+
+- Formats should be propagated from sink pads to source pads. Modifying
+ a format on a source pad should not modify the format on any sink
+ pad.
+
+- Sub-devices that scale frames using variable scaling factors should
+ reset the scale factors to default values when sink pads formats are
+ modified. If the 1:1 scaling ratio is supported, this means that
+ source pads formats should be reset to the sink pads formats.
+
+Formats are not propagated across links, as that would involve
+propagating them from one sub-device file handle to another.
+Applications must then take care to configure both ends of every link
+explicitly with compatible formats. Identical formats on the two ends of
+a link are guaranteed to be compatible. Drivers are free to accept
+different formats matching device requirements as being compatible.
+
+:ref:`sample-pipeline-config` shows a sample configuration sequence
+for the pipeline described in :ref:`pipeline-scaling` (table columns
+list entity names and pad numbers).
+
+
+.. _sample-pipeline-config:
+
+.. flat-table:: Sample Pipeline Configuration
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - Sensor/0 format
+
+ - Frontend/0 format
+
+ - Frontend/1 format
+
+ - Scaler/0 format
+
+ - Scaler/0 compose selection rectangle
+
+ - Scaler/1 format
+
+ - .. row 2
+
+ - Initial state
+
+ - 2048x1536/SGRBG8_1X8
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - .. row 3
+
+ - Configure frontend sink format
+
+ - 2048x1536/SGRBG8_1X8
+
+ - *2048x1536/SGRBG8_1X8*
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - (default)
+
+ - (default)
+
+ - (default)
+
+ - .. row 4
+
+ - Configure scaler sink format
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - *0,0/2046x1534*
+
+ - *2046x1534/SGRBG8_1X8*
+
+ - .. row 5
+
+ - Configure scaler sink compose selection
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2048x1536/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - 2046x1534/SGRBG8_1X8
+
+ - *0,0/1280x960*
+
+ - *1280x960/SGRBG8_1X8*
+
+
+
+1. Initial state. The sensor source pad format is set to its native 3MP
+ size and V4L2_MBUS_FMT_SGRBG8_1X8 media bus code. Formats on the
+ host frontend and scaler sink and source pads have the default
+ values, as well as the compose rectangle on the scaler's sink pad.
+
+2. The application configures the frontend sink pad format's size to
+ 2048x1536 and its media bus code to V4L2_MBUS_FMT_SGRBG_1X8. The
+ driver propagates the format to the frontend source pad.
+
+3. The application configures the scaler sink pad format's size to
+ 2046x1534 and the media bus code to V4L2_MBUS_FMT_SGRBG_1X8 to
+ match the frontend source size and media bus code. The media bus code
+ on the sink pad is set to V4L2_MBUS_FMT_SGRBG_1X8. The driver
+ propagates the size to the compose selection rectangle on the
+ scaler's sink pad, and the format to the scaler source pad.
+
+4. The application configures the size of the compose selection
+ rectangle of the scaler's sink pad 1280x960. The driver propagates
+ the size to the scaler's source pad format.
+
+When satisfied with the try results, applications can set the active
+formats by setting the ``which`` argument to
+``V4L2_SUBDEV_FORMAT_ACTIVE``. Active formats are changed exactly as try
+formats by drivers. To avoid modifying the hardware state during format
+negotiation, applications should negotiate try formats first and then
+modify the active settings using the try formats returned during the
+last negotiation iteration. This guarantees that the active format will
+be applied as-is by the driver without being modified.
+
+
+.. _v4l2-subdev-selections:
+
+Selections: cropping, scaling and composition
+---------------------------------------------
+
+Many sub-devices support cropping frames on their input or output pads
+(or possible even on both). Cropping is used to select the area of
+interest in an image, typically on an image sensor or a video decoder.
+It can also be used as part of digital zoom implementations to select
+the area of the image that will be scaled up.
+
+Crop settings are defined by a crop rectangle and represented in a
+struct :ref:`v4l2_rect <v4l2-rect>` by the coordinates of the top
+left corner and the rectangle size. Both the coordinates and sizes are
+expressed in pixels.
+
+As for pad formats, drivers store try and active rectangles for the
+selection targets :ref:`v4l2-selections-common`.
+
+On sink pads, cropping is applied relative to the current pad format.
+The pad format represents the image size as received by the sub-device
+from the previous block in the pipeline, and the crop rectangle
+represents the sub-image that will be transmitted further inside the
+sub-device for processing.
+
+The scaling operation changes the size of the image by scaling it to new
+dimensions. The scaling ratio isn't specified explicitly, but is implied
+from the original and scaled image sizes. Both sizes are represented by
+struct :ref:`v4l2_rect <v4l2-rect>`.
+
+Scaling support is optional. When supported by a subdev, the crop
+rectangle on the subdev's sink pad is scaled to the size configured
+using the
+:ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>` IOCTL
+using ``V4L2_SEL_TGT_COMPOSE`` selection target on the same pad. If the
+subdev supports scaling but not composing, the top and left values are
+not used and must always be set to zero.
+
+On source pads, cropping is similar to sink pads, with the exception
+that the source size from which the cropping is performed, is the
+COMPOSE rectangle on the sink pad. In both sink and source pads, the
+crop rectangle must be entirely contained inside the source image size
+for the crop operation.
+
+The drivers should always use the closest possible rectangle the user
+requests on all selection targets, unless specifically told otherwise.
+``V4L2_SEL_FLAG_GE`` and ``V4L2_SEL_FLAG_LE`` flags may be used to round
+the image size either up or down. :ref:`v4l2-selection-flags`
+
+
+Types of selection targets
+--------------------------
+
+
+Actual targets
+^^^^^^^^^^^^^^
+
+Actual targets (without a postfix) reflect the actual hardware
+configuration at any point of time. There is a BOUNDS target
+corresponding to every actual target.
+
+
+BOUNDS targets
+^^^^^^^^^^^^^^
+
+BOUNDS targets is the smallest rectangle that contains all valid actual
+rectangles. It may not be possible to set the actual rectangle as large
+as the BOUNDS rectangle, however. This may be because e.g. a sensor's
+pixel array is not rectangular but cross-shaped or round. The maximum
+size may also be smaller than the BOUNDS rectangle.
+
+
+Order of configuration and format propagation
+---------------------------------------------
+
+Inside subdevs, the order of image processing steps will always be from
+the sink pad towards the source pad. This is also reflected in the order
+in which the configuration must be performed by the user: the changes
+made will be propagated to any subsequent stages. If this behaviour is
+not desired, the user must set ``V4L2_SEL_FLAG_KEEP_CONFIG`` flag. This
+flag causes no propagation of the changes are allowed in any
+circumstances. This may also cause the accessed rectangle to be adjusted
+by the driver, depending on the properties of the underlying hardware.
+
+The coordinates to a step always refer to the actual size of the
+previous step. The exception to this rule is the source compose
+rectangle, which refers to the sink compose bounds rectangle --- if it
+is supported by the hardware.
+
+1. Sink pad format. The user configures the sink pad format. This format
+ defines the parameters of the image the entity receives through the
+ pad for further processing.
+
+2. Sink pad actual crop selection. The sink pad crop defines the crop
+ performed to the sink pad format.
+
+3. Sink pad actual compose selection. The size of the sink pad compose
+ rectangle defines the scaling ratio compared to the size of the sink
+ pad crop rectangle. The location of the compose rectangle specifies
+ the location of the actual sink compose rectangle in the sink compose
+ bounds rectangle.
+
+4. Source pad actual crop selection. Crop on the source pad defines crop
+ performed to the image in the sink compose bounds rectangle.
+
+5. Source pad format. The source pad format defines the output pixel
+ format of the subdev, as well as the other parameters with the
+ exception of the image width and height. Width and height are defined
+ by the size of the source pad actual crop selection.
+
+Accessing any of the above rectangles not supported by the subdev will
+return ``EINVAL``. Any rectangle referring to a previous unsupported
+rectangle coordinates will instead refer to the previous supported
+rectangle. For example, if sink crop is not supported, the compose
+selection will refer to the sink pad format dimensions instead.
+
+
+.. _subdev-image-processing-crop:
+
+.. figure:: dev-subdev_files/subdev-image-processing-crop.*
+ :alt: subdev-image-processing-crop.svg
+ :align: center
+
+ **Figure 4.5. Image processing in subdevs: simple crop example**
+
+In the above example, the subdev supports cropping on its sink pad. To
+configure it, the user sets the media bus format on the subdev's sink
+pad. Now the actual crop rectangle can be set on the sink pad --- the
+location and size of this rectangle reflect the location and size of a
+rectangle to be cropped from the sink format. The size of the sink crop
+rectangle will also be the size of the format of the subdev's source
+pad.
+
+
+.. _subdev-image-processing-scaling-multi-source:
+
+.. figure:: dev-subdev_files/subdev-image-processing-scaling-multi-source.*
+ :alt: subdev-image-processing-scaling-multi-source.svg
+ :align: center
+
+ **Figure 4.6. Image processing in subdevs: scaling with multiple sources**
+
+In this example, the subdev is capable of first cropping, then scaling
+and finally cropping for two source pads individually from the resulting
+scaled image. The location of the scaled image in the cropped image is
+ignored in sink compose target. Both of the locations of the source crop
+rectangles refer to the sink scaling rectangle, independently cropping
+an area at location specified by the source crop rectangle from it.
+
+
+.. _subdev-image-processing-full:
+
+.. figure:: dev-subdev_files/subdev-image-processing-full.*
+ :alt: subdev-image-processing-full.svg
+ :align: center
+
+ **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources**
+
+The subdev driver supports two sink pads and two source pads. The images
+from both of the sink pads are individually cropped, then scaled and
+further composed on the composition bounds rectangle. From that, two
+independent streams are cropped and sent out of the subdev from the
+source pads.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ subdev-formats
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf
new file mode 100644
index 000000000000..ee3e37f04b6a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png
new file mode 100644
index 000000000000..f19b86c2c24d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf
new file mode 100644
index 000000000000..29a806f839b4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg
new file mode 100644
index 000000000000..18b0f5de9ed2
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="43cm" height="10cm" viewBox="-194 128 844 196" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="469.774" height="193"/>
+ <g>
+ <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="63.5" y="211" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="63.5" y="211" width="94" height="77"/>
+ </g>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="74.5" y="227.75">
+ <tspan x="74.5" y="227.75">sink</tspan>
+ <tspan x="74.5" y="243.75">crop</tspan>
+ <tspan x="74.5" y="259.75">selection</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
+ <tspan x="29.5" y="158"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
+ <tspan x="8.53836" y="157.914">sink media</tspan>
+ <tspan x="8.53836" y="173.914">bus format</tspan>
+ </text>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="349.774" y="155">
+ <tspan x="349.774" y="155">source media</tspan>
+ <tspan x="349.774" y="171">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="350.488" y="190.834" width="93.2863" height="75.166"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="350.488" y="190.834" width="93.2863" height="75.166"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="266" x2="63.5" y2="288"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="350.488" y1="190.834" x2="63.5" y2="211"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="266" x2="157.5" y2="288"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="443.774" y1="190.834" x2="157.5" y2="211"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="473.1" cy="219.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="481.6" y1="219.984" x2="637.934" y2="220.012"/>
+ <polygon style="fill: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="645.434,220.014 635.433,225.012 637.934,220.012 635.435,215.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="506.908" y="209.8">
+ <tspan x="506.908" y="209.8">pad 1 (source)</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
+ <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
+ <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
+ </text>
+</svg>
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf
new file mode 100644
index 000000000000..b78a8e8f6b35
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg
new file mode 100644
index 000000000000..3322cf4c0093
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="59cm" height="18cm" viewBox="-186 71 1178 346" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <g>
+ <rect style="fill: #ffffff" x="318.9" y="129" width="208.1" height="249"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ff765a" x="318.9" y="129" width="208.1" height="249"/>
+ </g>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-2" y="73" width="806" height="343"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.5" cy="166.712" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <ellipse style="fill: #ffffff" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.232" cy="205.184" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.5" y1="167" x2="-30.7361" y2="166.729"/>
+ <polygon style="fill: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-23.2361,166.716 -33.2272,171.734 -30.7361,166.729 -33.2449,161.734 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.732" y1="205.184" x2="980.066" y2="205.212"/>
+ <polygon style="fill: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.566,205.214 977.565,210.212 980.066,205.212 977.567,200.212 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139.96" y="155">
+ <tspan x="-139.96" y="155">pad 0 (sink)</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.04" y="195">
+ <tspan x="849.04" y="195">pad 2 (source)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="5.5" y="120" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="5.5" y="120" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="62.5" y="136" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="62.5" y="136" width="94" height="77"/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="30.5" y="89">
+ <tspan x="30.5" y="89"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="9.53836" y="88.9138">
+ <tspan x="9.53836" y="88.9138">sink media</tspan>
+ <tspan x="9.53836" y="104.914">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="62.5" y2="213"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="62.5" y2="136"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="156.5" y2="213"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="156.5" y2="136"/>
+ <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
+ <tspan x="334.704" y="149.442">sink compose</tspan>
+ <tspan x="334.704" y="165.442">selection (scaling)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="409.322" y="194.565" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="409.322" y="194.565" width="100.186" height="71.4523"/>
+ </g>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="689.5" y="105.128">
+ <tspan x="689.5" y="105.128">source media</tspan>
+ <tspan x="689.5" y="121.128">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="688.488" y="173.834" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="688.488" y="173.834" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="245.286" x2="409.322" y2="266.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="688.488" y1="173.834" x2="409.322" y2="194.565"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="245.286" x2="509.508" y2="266.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="788.674" y1="173.834" x2="509.508" y2="194.565"/>
+ <text style="fill: #ff765a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="325" y="103">
+ <tspan x="325" y="103">sink compose</tspan>
+ <tspan x="325" y="119">bounds selection</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-12.0982" cy="341.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-184.098" y1="341.8" x2="-30.3343" y2="341.529"/>
+ <polygon style="fill: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-22.8343,341.516 -32.8254,346.534 -30.3343,341.529 -32.8431,336.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-139" y="329">
+ <tspan x="-139" y="329">pad 1 (sink)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="7.80824" y="292.8" width="112.092" height="82.2"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="7.80824" y="292.8" width="112.092" height="82.2"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="52.9" y="314.8" width="58.1" height="50.2"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="52.9" y="314.8" width="58.1" height="50.2"/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="31.9" y="259.8">
+ <tspan x="31.9" y="259.8"></tspan>
+ </text>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="251.9" x2="52.9" y2="314.8"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="358.9" y1="316" x2="52.9" y2="365"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="316" x2="111" y2="365"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="434" y1="251.9" x2="111" y2="314.8"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="358.9" y="251.9" width="75.1" height="64.1"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="443.262" y="284.466" width="64.738" height="48.534"/>
+ <g>
+ <rect style="fill: #ffffff" x="693.428" y="324.734" width="63.572" height="49.266"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="693.428" y="324.734" width="63.572" height="49.266"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="374" x2="443.262" y2="333"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="693.428" y1="324.734" x2="443.262" y2="284.466"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="374" x2="508" y2="333"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="757" y1="324.734" x2="508" y2="284.466"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="815.44" cy="343.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="823.94" y1="343.984" x2="980.274" y2="344.012"/>
+ <polygon style="fill: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="987.774,344.014 977.773,349.012 980.274,344.012 977.775,339.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="849.248" y="333.8">
+ <tspan x="849.248" y="333.8">pad 3 (source)</tspan>
+ </text>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="197" y="91">
+ <tspan x="197" y="91">sink</tspan>
+ <tspan x="197" y="107">crop</tspan>
+ <tspan x="197" y="123">selection</tspan>
+ </text>
+ <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="553" y="95">
+ <tspan x="553" y="95">source</tspan>
+ <tspan x="553" y="111">crop</tspan>
+ <tspan x="553" y="127">selection</tspan>
+ </text>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="211" y1="132" x2="166.21" y2="135.287"/>
+ <polygon style="fill: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="158.73,135.836 168.337,130.118 166.21,135.287 169.069,140.091 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x1="209" y1="131" x2="115.581" y2="306.209"/>
+ <polygon style="fill: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" points="112.052,312.827 112.345,301.65 115.581,306.209 121.169,306.355 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.492" y1="133.214" x2="514.916" y2="186.469"/>
+ <polygon style="fill: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="510.75,192.706 512.147,181.613 514.916,186.469 520.463,187.168 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="550.072" y1="133.787" x2="510.618" y2="275.089"/>
+ <polygon style="fill: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="508.601,282.312 506.475,271.336 510.618,275.089 516.106,274.025 "/>
+ </g>
+</svg>
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf
new file mode 100644
index 000000000000..8f7a95b6eb4d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg
new file mode 100644
index 000000000000..2340c0f8bc92
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
+<svg width="59cm" height="17cm" viewBox="-194 128 1179 330" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="-8" y="130" width="806" height="327"/>
+ <g>
+ <rect style="fill: #ffffff" x="4.5" y="189" width="159" height="104"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a52a2a" x="4.5" y="189" width="159" height="104"/>
+ </g>
+ <g>
+ <rect style="fill: #ffffff" x="49.5" y="204" width="94" height="77"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #0000ff" x="49.5" y="204" width="94" height="77"/>
+ </g>
+ <text style="fill: #0000ff;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="60" y="224">
+ <tspan x="60" y="224">sink</tspan>
+ <tspan x="60" y="240">crop</tspan>
+ <tspan x="60" y="256">selection</tspan>
+ </text>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="29.5" y="158">
+ <tspan x="29.5" y="158"></tspan>
+ </text>
+ <text style="fill: #a52a2a;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="8.53836" y="157.914">
+ <tspan x="8.53836" y="157.914">sink media</tspan>
+ <tspan x="8.53836" y="173.914">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #00ff00" x="333.644" y="185.65" width="165.2" height="172.478"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="358.128" x2="49.5" y2="281"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="333.644" y1="185.65" x2="49.5" y2="204"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="358.128" x2="143.5" y2="281"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="498.844" y1="185.65" x2="143.5" y2="204"/>
+ <text style="fill: #00ff00;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="334.704" y="149.442">
+ <tspan x="334.704" y="149.442">sink compose</tspan>
+ <tspan x="334.704" y="165.442">selection (scaling)</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="382.322" y="199.565" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="382.322" y="199.565" width="100.186" height="71.4523"/>
+ </g>
+ <text style="fill: #a020f0;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="543.322" y="149.442">
+ <tspan x="543.322" y="149.442">source</tspan>
+ <tspan x="543.322" y="165.442">crop</tspan>
+ <tspan x="543.322" y="181.442">selection</tspan>
+ </text>
+ <text style="fill: #8b6914;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="691.5" y="157.128">
+ <tspan x="691.5" y="157.128">source media</tspan>
+ <tspan x="691.5" y="173.128">bus format</tspan>
+ </text>
+ <g>
+ <rect style="fill: #ffffff" x="690.488" y="225.834" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="690.488" y="225.834" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="297.286" x2="382.322" y2="271.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="690.488" y1="225.834" x2="382.322" y2="199.565"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="297.286" x2="482.508" y2="271.018"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.674" y1="225.834" x2="482.508" y2="199.565"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="808.1" cy="249.984" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="816.6" y1="249.984" x2="972.934" y2="250.012"/>
+ <polygon style="fill: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="980.434,250.014 970.433,255.012 972.934,250.012 970.435,245.012 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="841.908" y="239.8">
+ <tspan x="841.908" y="239.8">pad 1 (source)</tspan>
+ </text>
+ <g>
+ <ellipse style="fill: #ffffff" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-20.3982" cy="241.512" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-192.398" y1="241.8" x2="-38.6343" y2="241.529"/>
+ <polygon style="fill: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-31.1343,241.516 -41.1254,246.534 -38.6343,241.529 -41.1431,236.534 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-147.858" y="229.8">
+ <tspan x="-147.858" y="229.8">pad 0 (sink)</tspan>
+ </text>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x="389.822" y="276.666" width="100.186" height="71.4523"/>
+ <g>
+ <rect style="fill: #ffffff" x="689.988" y="345.934" width="100.186" height="71.4523"/>
+ <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #8b6914" x="689.988" y="345.934" width="100.186" height="71.4523"/>
+ </g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="417.386" x2="389.822" y2="348.118"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="689.988" y1="345.934" x2="389.822" y2="276.666"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="417.386" x2="490.008" y2="348.118"/>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 4; stroke: #e60505" x1="790.174" y1="345.934" x2="490.008" y2="276.666"/>
+ <g>
+ <ellipse style="fill: #ffffff" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="805.6" cy="384.084" rx="8.5" ry="8.5"/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="814.1" y1="384.084" x2="970.434" y2="384.112"/>
+ <polygon style="fill: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="977.934,384.114 967.933,389.112 970.434,384.112 967.935,379.112 "/>
+ </g>
+ <text style="fill: #000000;text-anchor:start;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="839.408" y="373.9">
+ <tspan x="839.408" y="373.9">pad 2 (source)</tspan>
+ </text>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546" y1="191" x2="492.157" y2="198.263"/>
+ <polygon style="fill: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="484.724,199.266 493.966,192.974 492.157,198.263 495.303,202.884 "/>
+ </g>
+ <g>
+ <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" x1="546.908" y1="190.725" x2="495.383" y2="268.548"/>
+ <polygon style="fill: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
+ <polygon style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #a020f0" points="491.242,274.802 492.594,263.703 495.383,268.548 500.932,269.224 "/>
+ </g>
+</svg>
diff --git a/Documentation/media/uapi/v4l/dev-teletext.rst b/Documentation/media/uapi/v4l/dev-teletext.rst
new file mode 100644
index 000000000000..2648f6b37ea3
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dev-teletext.rst
@@ -0,0 +1,34 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _ttx:
+
+******************
+Teletext Interface
+******************
+
+This interface was aimed at devices receiving and demodulating Teletext
+data [:ref:`ets300706`, :ref:`itu653`], evaluating the Teletext
+packages and storing formatted pages in cache memory. Such devices are
+usually implemented as microcontrollers with serial interface
+(I:sup:`2`\ C) and could be found on old TV cards, dedicated Teletext
+decoding cards and home-brew devices connected to the PC parallel port.
+
+The Teletext API was designed by Martin Buck. It was defined in the
+kernel header file ``linux/videotext.h``, the specification is available
+from
+`ftp://ftp.gwdg.de/pub/linux/misc/videotext/ <ftp://ftp.gwdg.de/pub/linux/misc/videotext/>`__.
+(Videotext is the name of the German public television Teletext
+service.)
+
+Eventually the Teletext API was integrated into the V4L API with
+character device file names ``/dev/vtx0`` to ``/dev/vtx31``, device
+major number 81, minor numbers 192 to 223.
+
+However, teletext decoders were quickly replaced by more generic VBI
+demodulators and those dedicated teletext decoders no longer exist. For
+many years the vtx devices were still around, even though nobody used
+them. So the decision was made to finally remove support for the
+Teletext API in kernel 2.6.37.
+
+Modern devices all use the :ref:`raw <raw-vbi>` or
+:ref:`sliced` VBI API.
diff --git a/Documentation/media/uapi/v4l/devices.rst b/Documentation/media/uapi/v4l/devices.rst
new file mode 100644
index 000000000000..aed0ce11d1f8
--- /dev/null
+++ b/Documentation/media/uapi/v4l/devices.rst
@@ -0,0 +1,26 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _devices:
+
+**********
+Interfaces
+**********
+
+
+.. toctree::
+ :maxdepth: 1
+
+ dev-capture
+ dev-overlay
+ dev-output
+ dev-osd
+ dev-codec
+ dev-effect
+ dev-raw-vbi
+ dev-sliced-vbi
+ dev-teletext
+ dev-radio
+ dev-rds
+ dev-sdr
+ dev-event
+ dev-subdev
diff --git a/Documentation/media/uapi/v4l/diff-v4l.rst b/Documentation/media/uapi/v4l/diff-v4l.rst
new file mode 100644
index 000000000000..5f45ec123162
--- /dev/null
+++ b/Documentation/media/uapi/v4l/diff-v4l.rst
@@ -0,0 +1,954 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _diff-v4l:
+
+********************************
+Differences between V4L and V4L2
+********************************
+
+The Video For Linux API was first introduced in Linux 2.1 to unify and
+replace various TV and radio device related interfaces, developed
+independently by driver writers in prior years. Starting with Linux 2.5
+the much improved V4L2 API replaces the V4L API. The support for the old
+V4L calls were removed from Kernel, but the library :ref:`libv4l`
+supports the conversion of a V4L API system call into a V4L2 one.
+
+
+Opening and Closing Devices
+===========================
+
+For compatibility reasons the character device file names recommended
+for V4L2 video capture, overlay, radio and raw vbi capture devices did
+not change from those used by V4L. They are listed in :ref:`devices`
+and below in :ref:`v4l-dev`.
+
+The teletext devices (minor range 192-223) have been removed in V4L2 and
+no longer exist. There is no hardware available anymore for handling
+pure teletext. Instead raw or sliced VBI is used.
+
+The V4L ``videodev`` module automatically assigns minor numbers to
+drivers in load order, depending on the registered device type. We
+recommend that V4L2 drivers by default register devices with the same
+numbers, but the system administrator can assign arbitrary minor numbers
+using driver module options. The major device number remains 81.
+
+
+.. _v4l-dev:
+
+.. flat-table:: V4L Device Types, Names and Numbers
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Device Type
+
+ - File Name
+
+ - Minor Numbers
+
+ - .. row 2
+
+ - Video capture and overlay
+
+ - ``/dev/video`` and ``/dev/bttv0``\ [1]_, ``/dev/video0`` to
+ ``/dev/video63``
+
+ - 0-63
+
+ - .. row 3
+
+ - Radio receiver
+
+ - ``/dev/radio``\ [2]_, ``/dev/radio0`` to ``/dev/radio63``
+
+ - 64-127
+
+ - .. row 4
+
+ - Raw VBI capture
+
+ - ``/dev/vbi``, ``/dev/vbi0`` to ``/dev/vbi31``
+
+ - 224-255
+
+
+V4L prohibits (or used to prohibit) multiple opens of a device file.
+V4L2 drivers *may* support multiple opens, see :ref:`open` for details
+and consequences.
+
+V4L drivers respond to V4L2 ioctls with an ``EINVAL`` error code.
+
+
+Querying Capabilities
+=====================
+
+The V4L ``VIDIOCGCAP`` ioctl is equivalent to V4L2's
+:ref:`VIDIOC_QUERYCAP`.
+
+The ``name`` field in struct :c:type:`struct video_capability` became
+``card`` in struct :ref:`v4l2_capability <v4l2-capability>`, ``type``
+was replaced by ``capabilities``. Note V4L2 does not distinguish between
+device types like this, better think of basic video input, video output
+and radio devices supporting a set of related functions like video
+capturing, video overlay and VBI capturing. See :ref:`open` for an
+introduction.
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_capability` ``type``
+
+ - struct :ref:`v4l2_capability <v4l2-capability>`
+ ``capabilities`` flags
+
+ - Purpose
+
+ - .. row 2
+
+ - ``VID_TYPE_CAPTURE``
+
+ - ``V4L2_CAP_VIDEO_CAPTURE``
+
+ - The :ref:`video capture <capture>` interface is supported.
+
+ - .. row 3
+
+ - ``VID_TYPE_TUNER``
+
+ - ``V4L2_CAP_TUNER``
+
+ - The device has a :ref:`tuner or modulator <tuner>`.
+
+ - .. row 4
+
+ - ``VID_TYPE_TELETEXT``
+
+ - ``V4L2_CAP_VBI_CAPTURE``
+
+ - The :ref:`raw VBI capture <raw-vbi>` interface is supported.
+
+ - .. row 5
+
+ - ``VID_TYPE_OVERLAY``
+
+ - ``V4L2_CAP_VIDEO_OVERLAY``
+
+ - The :ref:`video overlay <overlay>` interface is supported.
+
+ - .. row 6
+
+ - ``VID_TYPE_CHROMAKEY``
+
+ - ``V4L2_FBUF_CAP_CHROMAKEY`` in field ``capability`` of struct
+ :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether chromakey overlay is supported. For more information on
+ overlay see :ref:`overlay`.
+
+ - .. row 7
+
+ - ``VID_TYPE_CLIPPING``
+
+ - ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
+ ``V4L2_FBUF_CAP_BITMAP_CLIPPING`` in field ``capability`` of
+ struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether clipping the overlaid image is supported, see
+ :ref:`overlay`.
+
+ - .. row 8
+
+ - ``VID_TYPE_FRAMERAM``
+
+ - ``V4L2_FBUF_CAP_EXTERNOVERLAY`` *not set* in field ``capability``
+ of struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`
+
+ - Whether overlay overwrites frame buffer memory, see
+ :ref:`overlay`.
+
+ - .. row 9
+
+ - ``VID_TYPE_SCALES``
+
+ - ``-``
+
+ - This flag indicates if the hardware can scale images. The V4L2 API
+ implies the scale factor by setting the cropping dimensions and
+ image size with the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` and
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, respectively. The
+ driver returns the closest sizes possible. For more information on
+ cropping and scaling see :ref:`crop`.
+
+ - .. row 10
+
+ - ``VID_TYPE_MONOCHROME``
+
+ - ``-``
+
+ - Applications can enumerate the supported image formats with the
+ :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
+ the device supports grey scale capturing only. For more
+ information on image formats see :ref:`pixfmt`.
+
+ - .. row 11
+
+ - ``VID_TYPE_SUBCAPTURE``
+
+ - ``-``
+
+ - Applications can call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>`
+ ioctl to determine if the device supports capturing a subsection
+ of the full picture ("cropping" in V4L2). If not, the ioctl
+ returns the ``EINVAL`` error code. For more information on cropping
+ and scaling see :ref:`crop`.
+
+ - .. row 12
+
+ - ``VID_TYPE_MPEG_DECODER``
+
+ - ``-``
+
+ - Applications can enumerate the supported image formats with the
+ :ref:`VIDIOC_ENUM_FMT` ioctl to determine if
+ the device supports MPEG streams.
+
+ - .. row 13
+
+ - ``VID_TYPE_MPEG_ENCODER``
+
+ - ``-``
+
+ - See above.
+
+ - .. row 14
+
+ - ``VID_TYPE_MJPEG_DECODER``
+
+ - ``-``
+
+ - See above.
+
+ - .. row 15
+
+ - ``VID_TYPE_MJPEG_ENCODER``
+
+ - ``-``
+
+ - See above.
+
+
+The ``audios`` field was replaced by ``capabilities`` flag
+``V4L2_CAP_AUDIO``, indicating *if* the device has any audio inputs or
+outputs. To determine their number applications can enumerate audio
+inputs with the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl. The
+audio ioctls are described in :ref:`audio`.
+
+The ``maxwidth``, ``maxheight``, ``minwidth`` and ``minheight`` fields
+were removed. Calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl with the desired
+dimensions returns the closest size possible, taking into account the
+current video standard, cropping and scaling limitations.
+
+
+Video Sources
+=============
+
+V4L provides the ``VIDIOCGCHAN`` and ``VIDIOCSCHAN`` ioctl using struct
+:c:type:`struct video_channel` to enumerate the video inputs of a V4L
+device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_ENUMINPUT`,
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` using struct
+:ref:`v4l2_input <v4l2-input>` as discussed in :ref:`video`.
+
+The ``channel`` field counting inputs was renamed to ``index``, the
+video input types were renamed as follows:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_channel` ``type``
+
+ - struct :ref:`v4l2_input <v4l2-input>` ``type``
+
+ - .. row 2
+
+ - ``VIDEO_TYPE_TV``
+
+ - ``V4L2_INPUT_TYPE_TUNER``
+
+ - .. row 3
+
+ - ``VIDEO_TYPE_CAMERA``
+
+ - ``V4L2_INPUT_TYPE_CAMERA``
+
+
+Unlike the ``tuners`` field expressing the number of tuners of this
+input, V4L2 assumes each video input is connected to at most one tuner.
+However a tuner can have more than one input, i. e. RF connectors, and a
+device can have multiple tuners. The index number of the tuner
+associated with the input, if any, is stored in field ``tuner`` of
+struct :ref:`v4l2_input <v4l2-input>`. Enumeration of tuners is
+discussed in :ref:`tuner`.
+
+The redundant ``VIDEO_VC_TUNER`` flag was dropped. Video inputs
+associated with a tuner are of type ``V4L2_INPUT_TYPE_TUNER``. The
+``VIDEO_VC_AUDIO`` flag was replaced by the ``audioset`` field. V4L2
+considers devices with up to 32 audio inputs. Each set bit in the
+``audioset`` field represents one audio input this video input combines
+with. For information about audio inputs and how to switch between them
+see :ref:`audio`.
+
+The ``norm`` field describing the supported video standards was replaced
+by ``std``. The V4L specification mentions a flag ``VIDEO_VC_NORM``
+indicating whether the standard can be changed. This flag was a later
+addition together with the ``norm`` field and has been removed in the
+meantime. V4L2 has a similar, albeit more comprehensive approach to
+video standards, see :ref:`standard` for more information.
+
+
+Tuning
+======
+
+The V4L ``VIDIOCGTUNER`` and ``VIDIOCSTUNER`` ioctl and struct
+:c:type:`struct video_tuner` can be used to enumerate the tuners of a
+V4L TV or radio device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
+:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` using struct
+:ref:`v4l2_tuner <v4l2-tuner>`. Tuners are covered in :ref:`tuner`.
+
+The ``tuner`` field counting tuners was renamed to ``index``. The fields
+``name``, ``rangelow`` and ``rangehigh`` remained unchanged.
+
+The ``VIDEO_TUNER_PAL``, ``VIDEO_TUNER_NTSC`` and ``VIDEO_TUNER_SECAM``
+flags indicating the supported video standards were dropped. This
+information is now contained in the associated struct
+:ref:`v4l2_input <v4l2-input>`. No replacement exists for the
+``VIDEO_TUNER_NORM`` flag indicating whether the video standard can be
+switched. The ``mode`` field to select a different video standard was
+replaced by a whole new set of ioctls and structures described in
+:ref:`standard`. Due to its ubiquity it should be mentioned the BTTV
+driver supports several standards in addition to the regular
+``VIDEO_MODE_PAL`` (0), ``VIDEO_MODE_NTSC``, ``VIDEO_MODE_SECAM`` and
+``VIDEO_MODE_AUTO`` (3). Namely N/PAL Argentina, M/PAL, N/PAL, and NTSC
+Japan with numbers 3-6 (sic).
+
+The ``VIDEO_TUNER_STEREO_ON`` flag indicating stereo reception became
+``V4L2_TUNER_SUB_STEREO`` in field ``rxsubchans``. This field also
+permits the detection of monaural and bilingual audio, see the
+definition of struct :ref:`v4l2_tuner <v4l2-tuner>` for details.
+Presently no replacement exists for the ``VIDEO_TUNER_RDS_ON`` and
+``VIDEO_TUNER_MBS_ON`` flags.
+
+The ``VIDEO_TUNER_LOW`` flag was renamed to ``V4L2_TUNER_CAP_LOW`` in
+the struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field.
+
+The ``VIDIOCGFREQ`` and ``VIDIOCSFREQ`` ioctl to change the tuner
+frequency where renamed to
+:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`. They take a pointer
+to a struct :ref:`v4l2_frequency <v4l2-frequency>` instead of an
+unsigned long integer.
+
+
+.. _v4l-image-properties:
+
+Image Properties
+================
+
+V4L2 has no equivalent of the ``VIDIOCGPICT`` and ``VIDIOCSPICT`` ioctl
+and struct :c:type:`struct video_picture`. The following fields where
+replaced by V4L2 controls accessible with the
+:ref:`VIDIOC_QUERYCTRL`,
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_picture`
+
+ - V4L2 Control ID
+
+ - .. row 2
+
+ - ``brightness``
+
+ - ``V4L2_CID_BRIGHTNESS``
+
+ - .. row 3
+
+ - ``hue``
+
+ - ``V4L2_CID_HUE``
+
+ - .. row 4
+
+ - ``colour``
+
+ - ``V4L2_CID_SATURATION``
+
+ - .. row 5
+
+ - ``contrast``
+
+ - ``V4L2_CID_CONTRAST``
+
+ - .. row 6
+
+ - ``whiteness``
+
+ - ``V4L2_CID_WHITENESS``
+
+
+The V4L picture controls are assumed to range from 0 to 65535 with no
+particular reset value. The V4L2 API permits arbitrary limits and
+defaults which can be queried with the
+:ref:`VIDIOC_QUERYCTRL` ioctl. For general
+information about controls see :ref:`control`.
+
+The ``depth`` (average number of bits per pixel) of a video image is
+implied by the selected image format. V4L2 does not explicitly provide
+such information assuming applications recognizing the format are aware
+of the image depth and others need not know. The ``palette`` field moved
+into the struct :ref:`v4l2_pix_format <v4l2-pix-format>`:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_picture` ``palette``
+
+ - struct :ref:`v4l2_pix_format <v4l2-pix-format>` ``pixfmt``
+
+ - .. row 2
+
+ - ``VIDEO_PALETTE_GREY``
+
+ - :ref:`V4L2_PIX_FMT_GREY <V4L2-PIX-FMT-GREY>`
+
+ - .. row 3
+
+ - ``VIDEO_PALETTE_HI240``
+
+ - :ref:`V4L2_PIX_FMT_HI240 <pixfmt-reserved>` [3]_
+
+ - .. row 4
+
+ - ``VIDEO_PALETTE_RGB565``
+
+ - :ref:`V4L2_PIX_FMT_RGB565 <pixfmt-rgb>`
+
+ - .. row 5
+
+ - ``VIDEO_PALETTE_RGB555``
+
+ - :ref:`V4L2_PIX_FMT_RGB555 <pixfmt-rgb>`
+
+ - .. row 6
+
+ - ``VIDEO_PALETTE_RGB24``
+
+ - :ref:`V4L2_PIX_FMT_BGR24 <pixfmt-rgb>`
+
+ - .. row 7
+
+ - ``VIDEO_PALETTE_RGB32``
+
+ - :ref:`V4L2_PIX_FMT_BGR32 <pixfmt-rgb>` [4]_
+
+ - .. row 8
+
+ - ``VIDEO_PALETTE_YUV422``
+
+ - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
+
+ - .. row 9
+
+ - ``VIDEO_PALETTE_YUYV``\ [5]_
+
+ - :ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`
+
+ - .. row 10
+
+ - ``VIDEO_PALETTE_UYVY``
+
+ - :ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`
+
+ - .. row 11
+
+ - ``VIDEO_PALETTE_YUV420``
+
+ - None
+
+ - .. row 12
+
+ - ``VIDEO_PALETTE_YUV411``
+
+ - :ref:`V4L2_PIX_FMT_Y41P <V4L2-PIX-FMT-Y41P>` [6]_
+
+ - .. row 13
+
+ - ``VIDEO_PALETTE_RAW``
+
+ - None [7]_
+
+ - .. row 14
+
+ - ``VIDEO_PALETTE_YUV422P``
+
+ - :ref:`V4L2_PIX_FMT_YUV422P <V4L2-PIX-FMT-YUV422P>`
+
+ - .. row 15
+
+ - ``VIDEO_PALETTE_YUV411P``
+
+ - :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>` [8]_
+
+ - .. row 16
+
+ - ``VIDEO_PALETTE_YUV420P``
+
+ - :ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`
+
+ - .. row 17
+
+ - ``VIDEO_PALETTE_YUV410P``
+
+ - :ref:`V4L2_PIX_FMT_YVU410 <V4L2-PIX-FMT-YVU410>`
+
+
+V4L2 image formats are defined in :ref:`pixfmt`. The image format can
+be selected with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+
+Audio
+=====
+
+The ``VIDIOCGAUDIO`` and ``VIDIOCSAUDIO`` ioctl and struct
+:c:type:`struct video_audio` are used to enumerate the audio inputs
+of a V4L device. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` and
+:ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` using struct
+:ref:`v4l2_audio <v4l2-audio>` as discussed in :ref:`audio`.
+
+The ``audio`` "channel number" field counting audio inputs was renamed
+to ``index``.
+
+On ``VIDIOCSAUDIO`` the ``mode`` field selects *one* of the
+``VIDEO_SOUND_MONO``, ``VIDEO_SOUND_STEREO``, ``VIDEO_SOUND_LANG1`` or
+``VIDEO_SOUND_LANG2`` audio demodulation modes. When the current audio
+standard is BTSC ``VIDEO_SOUND_LANG2`` refers to SAP and
+``VIDEO_SOUND_LANG1`` is meaningless. Also undocumented in the V4L
+specification, there is no way to query the selected mode. On
+``VIDIOCGAUDIO`` the driver returns the *actually received* audio
+programmes in this field. In the V4L2 API this information is stored in
+the struct :ref:`v4l2_tuner <v4l2-tuner>` ``rxsubchans`` and
+``audmode`` fields, respectively. See :ref:`tuner` for more
+information on tuners. Related to audio modes struct
+:ref:`v4l2_audio <v4l2-audio>` also reports if this is a mono or
+stereo input, regardless if the source is a tuner.
+
+The following fields where replaced by V4L2 controls accessible with the
+:ref:`VIDIOC_QUERYCTRL`,
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :c:type:`struct video_audio`
+
+ - V4L2 Control ID
+
+ - .. row 2
+
+ - ``volume``
+
+ - ``V4L2_CID_AUDIO_VOLUME``
+
+ - .. row 3
+
+ - ``bass``
+
+ - ``V4L2_CID_AUDIO_BASS``
+
+ - .. row 4
+
+ - ``treble``
+
+ - ``V4L2_CID_AUDIO_TREBLE``
+
+ - .. row 5
+
+ - ``balance``
+
+ - ``V4L2_CID_AUDIO_BALANCE``
+
+
+To determine which of these controls are supported by a driver V4L
+provides the ``flags`` ``VIDEO_AUDIO_VOLUME``, ``VIDEO_AUDIO_BASS``,
+``VIDEO_AUDIO_TREBLE`` and ``VIDEO_AUDIO_BALANCE``. In the V4L2 API the
+:ref:`VIDIOC_QUERYCTRL` ioctl reports if the
+respective control is supported. Accordingly the ``VIDEO_AUDIO_MUTABLE``
+and ``VIDEO_AUDIO_MUTE`` flags where replaced by the boolean
+``V4L2_CID_AUDIO_MUTE`` control.
+
+All V4L2 controls have a ``step`` attribute replacing the struct
+:c:type:`struct video_audio` ``step`` field. The V4L audio controls
+are assumed to range from 0 to 65535 with no particular reset value. The
+V4L2 API permits arbitrary limits and defaults which can be queried with
+the :ref:`VIDIOC_QUERYCTRL` ioctl. For general
+information about controls see :ref:`control`.
+
+
+Frame Buffer Overlay
+====================
+
+The V4L2 ioctls equivalent to ``VIDIOCGFBUF`` and ``VIDIOCSFBUF`` are
+:ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and
+:ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. The ``base`` field of struct
+:c:type:`struct video_buffer` remained unchanged, except V4L2 defines
+a flag to indicate non-destructive overlays instead of a ``NULL``
+pointer. All other fields moved into the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``fmt`` substructure of
+struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`. The ``depth``
+field was replaced by ``pixelformat``. See :ref:`pixfmt-rgb` for a
+list of RGB formats and their respective color depths.
+
+Instead of the special ioctls ``VIDIOCGWIN`` and ``VIDIOCSWIN`` V4L2
+uses the general-purpose data format negotiation ioctls
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
+:ref:`v4l2_format <v4l2-format>` as argument. Here the ``win`` member
+of the ``fmt`` union is used, a struct
+:ref:`v4l2_window <v4l2-window>`.
+
+The ``x``, ``y``, ``width`` and ``height`` fields of struct
+:c:type:`struct video_window` moved into struct
+:ref:`v4l2_rect <v4l2-rect>` substructure ``w`` of struct
+:c:type:`struct v4l2_window`. The ``chromakey``, ``clips``, and
+``clipcount`` fields remained unchanged. Struct
+:c:type:`struct video_clip` was renamed to struct
+:ref:`v4l2_clip <v4l2-clip>`, also containing a struct
+:c:type:`struct v4l2_rect`, but the semantics are still the same.
+
+The ``VIDEO_WINDOW_INTERLACE`` flag was dropped. Instead applications
+must set the ``field`` field to ``V4L2_FIELD_ANY`` or
+``V4L2_FIELD_INTERLACED``. The ``VIDEO_WINDOW_CHROMAKEY`` flag moved
+into struct :ref:`v4l2_framebuffer <v4l2-framebuffer>`, under the new
+name ``V4L2_FBUF_FLAG_CHROMAKEY``.
+
+In V4L, storing a bitmap pointer in ``clips`` and setting ``clipcount``
+to ``VIDEO_CLIP_BITMAP`` (-1) requests bitmap clipping, using a fixed
+size bitmap of 1024 × 625 bits. Struct :c:type:`struct v4l2_window`
+has a separate ``bitmap`` pointer field for this purpose and the bitmap
+size is determined by ``w.width`` and ``w.height``.
+
+The ``VIDIOCCAPTURE`` ioctl to enable or disable overlay was renamed to
+:ref:`VIDIOC_OVERLAY`.
+
+
+Cropping
+========
+
+To capture only a subsection of the full picture V4L defines the
+``VIDIOCGCAPTURE`` and ``VIDIOCSCAPTURE`` ioctls using struct
+:c:type:`struct video_capture`. The equivalent V4L2 ioctls are
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` using struct
+:ref:`v4l2_crop <v4l2-crop>`, and the related
+:ref:`VIDIOC_CROPCAP` ioctl. This is a rather
+complex matter, see :ref:`crop` for details.
+
+The ``x``, ``y``, ``width`` and ``height`` fields moved into struct
+:ref:`v4l2_rect <v4l2-rect>` substructure ``c`` of struct
+:c:type:`struct v4l2_crop`. The ``decimation`` field was dropped. In
+the V4L2 API the scaling factor is implied by the size of the cropping
+rectangle and the size of the captured or overlaid image.
+
+The ``VIDEO_CAPTURE_ODD`` and ``VIDEO_CAPTURE_EVEN`` flags to capture
+only the odd or even field, respectively, were replaced by
+``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM`` in the field named
+``field`` of struct :ref:`v4l2_pix_format <v4l2-pix-format>` and
+struct :ref:`v4l2_window <v4l2-window>`. These structures are used to
+select a capture or overlay format with the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+
+Reading Images, Memory Mapping
+==============================
+
+
+Capturing using the read method
+-------------------------------
+
+There is no essential difference between reading images from a V4L or
+V4L2 device using the :ref:`read() <func-read>` function, however V4L2
+drivers are not required to support this I/O method. Applications can
+determine if the function is available with the
+:ref:`VIDIOC_QUERYCAP` ioctl. All V4L2 devices
+exchanging data with applications must support the
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions.
+
+To select an image format and size, V4L provides the ``VIDIOCSPICT`` and
+``VIDIOCSWIN`` ioctls. V4L2 uses the general-purpose data format
+negotiation ioctls :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. They take a pointer to a struct
+:ref:`v4l2_format <v4l2-format>` as argument, here the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` named ``pix`` of its
+``fmt`` union is used.
+
+For more information about the V4L2 read interface see :ref:`rw`.
+
+
+Capturing using memory mapping
+------------------------------
+
+Applications can read from V4L devices by mapping buffers in device
+memory, or more often just buffers allocated in DMA-able system memory,
+into their address space. This avoids the data copying overhead of the
+read method. V4L2 supports memory mapping as well, with a few
+differences.
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - V4L
+
+ - V4L2
+
+ - .. row 2
+
+ -
+ - The image format must be selected before buffers are allocated,
+ with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When no
+ format is selected the driver may use the last, possibly by
+ another application requested format.
+
+ - .. row 3
+
+ - Applications cannot change the number of buffers. The it is built
+ into the driver, unless it has a module option to change the
+ number when the driver module is loaded.
+
+ - The :ref:`VIDIOC_REQBUFS` ioctl allocates the
+ desired number of buffers, this is a required step in the
+ initialization sequence.
+
+ - .. row 4
+
+ - Drivers map all buffers as one contiguous range of memory. The
+ ``VIDIOCGMBUF`` ioctl is available to query the number of buffers,
+ the offset of each buffer from the start of the virtual file, and
+ the overall amount of memory used, which can be used as arguments
+ for the :ref:`mmap() <func-mmap>` function.
+
+ - Buffers are individually mapped. The offset and size of each
+ buffer can be determined with the
+ :ref:`VIDIOC_QUERYBUF` ioctl.
+
+ - .. row 5
+
+ - The ``VIDIOCMCAPTURE`` ioctl prepares a buffer for capturing. It
+ also determines the image format for this buffer. The ioctl
+ returns immediately, eventually with an ``EAGAIN`` error code if no
+ video signal had been detected. When the driver supports more than
+ one buffer applications can call the ioctl multiple times and thus
+ have multiple outstanding capture requests.
+
+ The ``VIDIOCSYNC`` ioctl suspends execution until a particular
+ buffer has been filled.
+
+ - Drivers maintain an incoming and outgoing queue.
+ :ref:`VIDIOC_QBUF` enqueues any empty buffer into
+ the incoming queue. Filled buffers are dequeued from the outgoing
+ queue with the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. To wait
+ until filled buffers become available this function,
+ :ref:`select() <func-select>` or :ref:`poll() <func-poll>` can
+ be used. The :ref:`VIDIOC_STREAMON` ioctl
+ must be called once after enqueuing one or more buffers to start
+ capturing. Its counterpart
+ :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` stops capturing and
+ dequeues all buffers from both queues. Applications can query the
+ signal status, if known, with the
+ :ref:`VIDIOC_ENUMINPUT` ioctl.
+
+
+For a more in-depth discussion of memory mapping and examples, see
+:ref:`mmap`.
+
+
+Reading Raw VBI Data
+====================
+
+Originally the V4L API did not specify a raw VBI capture interface, only
+the device file ``/dev/vbi`` was reserved for this purpose. The only
+driver supporting this interface was the BTTV driver, de-facto defining
+the V4L VBI interface. Reading from the device yields a raw VBI image
+with the following parameters:
+
+
+
+.. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+
+ - V4L, BTTV driver
+
+ - .. row 2
+
+ - sampling_rate
+
+ - 28636363 Hz NTSC (or any other 525-line standard); 35468950 Hz PAL
+ and SECAM (625-line standards)
+
+ - .. row 3
+
+ - offset
+
+ - ?
+
+ - .. row 4
+
+ - samples_per_line
+
+ - 2048
+
+ - .. row 5
+
+ - sample_format
+
+ - V4L2_PIX_FMT_GREY. The last four bytes (a machine endianness
+ integer) contain a frame counter.
+
+ - .. row 6
+
+ - start[]
+
+ - 10, 273 NTSC; 22, 335 PAL and SECAM
+
+ - .. row 7
+
+ - count[]
+
+ - 16, 16 [9]_
+
+ - .. row 8
+
+ - flags
+
+ - 0
+
+
+Undocumented in the V4L specification, in Linux 2.3 the
+``VIDIOCGVBIFMT`` and ``VIDIOCSVBIFMT`` ioctls using struct
+:c:type:`struct vbi_format` were added to determine the VBI image
+parameters. These ioctls are only partially compatible with the V4L2 VBI
+interface specified in :ref:`raw-vbi`.
+
+An ``offset`` field does not exist, ``sample_format`` is supposed to be
+``VIDEO_PALETTE_RAW``, equivalent to ``V4L2_PIX_FMT_GREY``. The
+remaining fields are probably equivalent to struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>`.
+
+Apparently only the Zoran (ZR 36120) driver implements these ioctls. The
+semantics differ from those specified for V4L2 in two ways. The
+parameters are reset on :ref:`open() <func-open>` and
+``VIDIOCSVBIFMT`` always returns an ``EINVAL`` error code if the parameters
+are invalid.
+
+
+Miscellaneous
+=============
+
+V4L2 has no equivalent of the ``VIDIOCGUNIT`` ioctl. Applications can
+find the VBI device associated with a video capture device (or vice
+versa) by reopening the device and requesting VBI data. For details see
+:ref:`open`.
+
+No replacement exists for ``VIDIOCKEY``, and the V4L functions for
+microcode programming. A new interface for MPEG compression and playback
+devices is documented in :ref:`extended-controls`.
+
+.. [1]
+ According to Documentation/devices.txt these should be symbolic links
+ to ``/dev/video0``. Note the original bttv interface is not
+ compatible with V4L or V4L2.
+
+.. [2]
+ According to ``Documentation/devices.txt`` a symbolic link to
+ ``/dev/radio0``.
+
+.. [3]
+ This is a custom format used by the BTTV driver, not one of the V4L2
+ standard formats.
+
+.. [4]
+ Presumably all V4L RGB formats are little-endian, although some
+ drivers might interpret them according to machine endianness. V4L2
+ defines little-endian, big-endian and red/blue swapped variants. For
+ details see :ref:`pixfmt-rgb`.
+
+.. [5]
+ ``VIDEO_PALETTE_YUV422`` and ``VIDEO_PALETTE_YUYV`` are the same
+ formats. Some V4L drivers respond to one, some to the other.
+
+.. [6]
+ Not to be confused with ``V4L2_PIX_FMT_YUV411P``, which is a planar
+ format.
+
+.. [7]
+ V4L explains this as: "RAW capture (BT848)"
+
+.. [8]
+ Not to be confused with ``V4L2_PIX_FMT_Y41P``, which is a packed
+ format.
+
+.. [9]
+ Old driver versions used different values, eventually the custom
+ ``BTTV_VBISIZE`` ioctl was added to query the correct values.
diff --git a/Documentation/media/uapi/v4l/dmabuf.rst b/Documentation/media/uapi/v4l/dmabuf.rst
new file mode 100644
index 000000000000..474d8c021507
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dmabuf.rst
@@ -0,0 +1,155 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dmabuf:
+
+************************************
+Streaming I/O (DMA buffer importing)
+************************************
+
+The DMABUF framework provides a generic method for sharing buffers
+between multiple devices. Device drivers that support DMABUF can export
+a DMA buffer to userspace as a file descriptor (known as the exporter
+role), import a DMA buffer from userspace using a file descriptor
+previously exported for a different or the same device (known as the
+importer role), or both. This section describes the DMABUF importer role
+API in V4L2.
+
+Refer to :ref:`DMABUF exporting <VIDIOC_EXPBUF>` for details about
+exporting V4L2 buffers as DMABUF file descriptors.
+
+Input and output devices support the streaming I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>` ioctl is set. Whether
+importing DMA buffers through DMABUF file descriptors is supported is
+determined by calling the :ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
+ioctl with the memory type set to ``V4L2_MEMORY_DMABUF``.
+
+This I/O method is dedicated to sharing DMA buffers between different
+devices, which may be V4L devices or other video-related devices (e.g.
+DRM). Buffers (planes) are allocated by a driver on behalf of an
+application. Next, these buffers are exported to the application as file
+descriptors using an API which is specific for an allocator driver. Only
+such file descriptor are exchanged. The descriptors and meta-information
+are passed in struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
+:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
+driver must be switched into DMABUF I/O mode by calling the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>` with the desired buffer type.
+
+
+.. code-block:: c
+ :caption: Example 3.4. Initiating streaming I/O with DMABUF file descriptors
+
+ struct v4l2_requestbuffers reqbuf;
+
+ memset(&reqbuf, 0, sizeof (reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_DMABUF;
+ reqbuf.count = 1;
+
+ if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf("Video capturing or DMABUF streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+The buffer (plane) file descriptor is passed on the fly with the
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. In case of multiplanar
+buffers, every plane can be associated with a different DMABUF
+descriptor. Although buffers are commonly cycled, applications can pass
+a different DMABUF descriptor at each :ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call.
+
+
+.. code-block:: c
+ :caption: Example 3.5. Queueing DMABUF using single plane API
+
+ int buffer_queue(int v4lfd, int index, int dmafd)
+ {
+ struct v4l2_buffer buf;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.fd = dmafd;
+
+ if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+ }
+
+
+.. code-block:: c
+ :caption: Example 3.6. Queueing DMABUF using multi plane API
+
+ int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes)
+ {
+ struct v4l2_buffer buf;
+ struct v4l2_plane planes[VIDEO_MAX_PLANES];
+ int i;
+
+ memset(&buf, 0, sizeof buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+ buf.memory = V4L2_MEMORY_DMABUF;
+ buf.index = index;
+ buf.m.planes = planes;
+ buf.length = n_planes;
+
+ memset(&planes, 0, sizeof planes);
+
+ for (i = 0; i < n_planes; ++i)
+ buf.m.planes[i].m.fd = dmafd[i];
+
+ if (ioctl(v4lfd, VIDIOC_QBUF, &buf) == -1) {
+ perror("VIDIOC_QBUF");
+ return -1;
+ }
+
+ return 0;
+ }
+
+Captured or displayed buffers are dequeued with the
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
+buffer at any time between the completion of the DMA and this ioctl. The
+memory is also unlocked when
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, or when the device is closed.
+
+For capturing applications it is customary to enqueue a number of empty
+buffers, to start capturing and enter the read loop. Here the
+application waits until a filled buffer can be dequeued, and re-enqueues
+the buffer when the data is no longer needed. Output applications fill
+and enqueue buffers, when enough buffers are stacked up output is
+started. In the write loop, when the application runs out of free
+buffers it must wait until an empty buffer can be dequeued and reused.
+Two methods exist to suspend execution of the application until one or
+more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
+<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
+``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
+error code when no buffer is available. The
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions are always available.
+
+To start and stop capturing or displaying applications call the
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls. Note that
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from
+both queues and unlocks all buffers as a side effect. Since there is no
+notion of doing anything "now" on a multitasking system, if an
+application needs to synchronize with another event it should examine
+the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+outputted buffers.
+
+Drivers implementing DMABUF importing I/O must support the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON
+<VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls,
+and the :ref:`select() <func-select>` and :ref:`poll() <func-poll>`
+functions.
diff --git a/Documentation/media/uapi/v4l/driver.rst b/Documentation/media/uapi/v4l/driver.rst
new file mode 100644
index 000000000000..2319b383f0a4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/driver.rst
@@ -0,0 +1,9 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _driver:
+
+***********************
+V4L2 Driver Programming
+***********************
+
+to do
diff --git a/Documentation/media/uapi/v4l/dv-timings.rst b/Documentation/media/uapi/v4l/dv-timings.rst
new file mode 100644
index 000000000000..415a0c4e2ccb
--- /dev/null
+++ b/Documentation/media/uapi/v4l/dv-timings.rst
@@ -0,0 +1,38 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _dv-timings:
+
+**************************
+Digital Video (DV) Timings
+**************************
+
+The video standards discussed so far have been dealing with Analog TV
+and the corresponding video timings. Today there are many more different
+hardware interfaces such as High Definition TV interfaces (HDMI), VGA,
+DVI connectors etc., that carry video signals and there is a need to
+extend the API to select the video timings for these interfaces. Since
+it is not possible to extend the :ref:`v4l2_std_id <v4l2-std-id>`
+due to the limited bits available, a new set of ioctls was added to
+set/get video timings at the input and output.
+
+These ioctls deal with the detailed digital video timings that define
+each video format. This includes parameters such as the active video
+width and height, signal polarities, frontporches, backporches, sync
+widths etc. The ``linux/v4l2-dv-timings.h`` header can be used to get
+the timings of the formats in the :ref:`cea861` and :ref:`vesadmt`
+standards.
+
+To enumerate and query the attributes of the DV timings supported by a
+device applications use the
+:ref:`VIDIOC_ENUM_DV_TIMINGS` and
+:ref:`VIDIOC_DV_TIMINGS_CAP` ioctls. To set
+DV timings for the device applications use the
+:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get
+current DV timings they use the
+:ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. To detect
+the DV timings as seen by the video receiver applications use the
+:ref:`VIDIOC_QUERY_DV_TIMINGS` ioctl.
+
+Applications can make use of the :ref:`input-capabilities` and
+:ref:`output-capabilities` flags to determine whether the digital
+video ioctls can be used with the given input or output.
diff --git a/Documentation/media/uapi/v4l/extended-controls.rst b/Documentation/media/uapi/v4l/extended-controls.rst
new file mode 100644
index 000000000000..26eb6ee851c3
--- /dev/null
+++ b/Documentation/media/uapi/v4l/extended-controls.rst
@@ -0,0 +1,4524 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _extended-controls:
+
+*****************
+Extended Controls
+*****************
+
+
+Introduction
+============
+
+The control mechanism as originally designed was meant to be used for
+user settings (brightness, saturation, etc). However, it turned out to
+be a very useful model for implementing more complicated driver APIs
+where each driver implements only a subset of a larger API.
+
+The MPEG encoding API was the driving force behind designing and
+implementing this extended control mechanism: the MPEG standard is quite
+large and the currently supported hardware MPEG encoders each only
+implement a subset of this standard. Further more, many parameters
+relating to how the video is encoded into an MPEG stream are specific to
+the MPEG encoding chip since the MPEG standard only defines the format
+of the resulting MPEG stream, not how the video is actually encoded into
+that format.
+
+Unfortunately, the original control API lacked some features needed for
+these new uses and so it was extended into the (not terribly originally
+named) extended control API.
+
+Even though the MPEG encoding API was the first effort to use the
+Extended Control API, nowadays there are also other classes of Extended
+Controls, such as Camera Controls and FM Transmitter Controls. The
+Extended Controls API as well as all Extended Controls classes are
+described in the following text.
+
+
+The Extended Control API
+========================
+
+Three new ioctls are available:
+:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
+:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
+:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`. These ioctls act
+on arrays of controls (as opposed to the
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls that act on a single
+control). This is needed since it is often required to atomically change
+several controls at once.
+
+Each of the new ioctls expects a pointer to a struct
+:ref:`v4l2_ext_controls <v4l2-ext-controls>`. This structure
+contains a pointer to the control array, a count of the number of
+controls in that array and a control class. Control classes are used to
+group similar controls into a single class. For example, control class
+``V4L2_CTRL_CLASS_USER`` contains all user controls (i. e. all controls
+that can also be set using the old :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
+ioctl). Control class ``V4L2_CTRL_CLASS_MPEG`` contains all controls
+relating to MPEG encoding, etc.
+
+All controls in the control array must belong to the specified control
+class. An error is returned if this is not the case.
+
+It is also possible to use an empty control array (``count`` == 0) to check
+whether the specified control class is supported.
+
+The control array is a struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` array. The
+:ref:`struct v4l2_ext_control <v4l2-ext-control>` structure is very similar to
+struct :ref:`v4l2_control <v4l2-control>`, except for the fact that
+it also allows for 64-bit values and pointers to be passed.
+
+Since the struct :ref:`v4l2_ext_control <v4l2-ext-control>` supports
+pointers it is now also possible to have controls with compound types
+such as N-dimensional arrays and/or structures. You need to specify the
+``V4L2_CTRL_FLAG_NEXT_COMPOUND`` when enumerating controls to actually
+be able to see such compound controls. In other words, these controls
+with compound types should only be used programmatically.
+
+Since such compound controls need to expose more information about
+themselves than is possible with
+:ref:`VIDIOC_QUERYCTRL` the
+:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>` ioctl was added. In
+particular, this ioctl gives the dimensions of the N-dimensional array
+if this control consists of more than one element.
+
+It is important to realize that due to the flexibility of controls it is
+necessary to check whether the control you want to set actually is
+supported in the driver and what the valid range of values is. So use
+the :ref:`VIDIOC_QUERYCTRL` (or
+:ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`) and
+:ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>` ioctls to check this. Also
+note that it is possible that some of the menu indices in a control of
+type ``V4L2_CTRL_TYPE_MENU`` may not be supported (``VIDIOC_QUERYMENU``
+will return an error). A good example is the list of supported MPEG
+audio bitrates. Some drivers only support one or two bitrates, others
+support a wider range.
+
+All controls use machine endianness.
+
+
+Enumerating Extended Controls
+=============================
+
+The recommended way to enumerate over the extended controls is by using
+:ref:`VIDIOC_QUERYCTRL` in combination with the
+``V4L2_CTRL_FLAG_NEXT_CTRL`` flag:
+
+
+.. code-block:: c
+
+ struct v4l2_queryctrl qctrl;
+
+ qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl (fd, VIDIOC_QUERYCTRL, &qctrl)) {
+ /* ... */
+ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+
+The initial control ID is set to 0 ORed with the
+``V4L2_CTRL_FLAG_NEXT_CTRL`` flag. The ``VIDIOC_QUERYCTRL`` ioctl will
+return the first control with a higher ID than the specified one. When
+no such controls are found an error is returned.
+
+If you want to get all controls within a specific control class, then
+you can set the initial ``qctrl.id`` value to the control class and add
+an extra check to break out of the loop when a control of another
+control class is found:
+
+
+.. code-block:: c
+
+ qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
+ while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &qctrl)) {
+ if (V4L2_CTRL_ID2CLASS(qctrl.id) != V4L2_CTRL_CLASS_MPEG)
+ break;
+ /* ... */
+ qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
+ }
+
+The 32-bit ``qctrl.id`` value is subdivided into three bit ranges: the
+top 4 bits are reserved for flags (e. g. ``V4L2_CTRL_FLAG_NEXT_CTRL``)
+and are not actually part of the ID. The remaining 28 bits form the
+control ID, of which the most significant 12 bits define the control
+class and the least significant 16 bits identify the control within the
+control class. It is guaranteed that these last 16 bits are always
+non-zero for controls. The range of 0x1000 and up are reserved for
+driver-specific controls. The macro ``V4L2_CTRL_ID2CLASS(id)`` returns
+the control class ID based on a control ID.
+
+If the driver does not support extended controls, then
+``VIDIOC_QUERYCTRL`` will fail when used in combination with
+``V4L2_CTRL_FLAG_NEXT_CTRL``. In that case the old method of enumerating
+control should be used (see :ref:`enum_all_controls`). But if it is
+supported, then it is guaranteed to enumerate over all controls,
+including driver-private controls.
+
+
+Creating Control Panels
+=======================
+
+It is possible to create control panels for a graphical user interface
+where the user can select the various controls. Basically you will have
+to iterate over all controls using the method described above. Each
+control class starts with a control of type
+``V4L2_CTRL_TYPE_CTRL_CLASS``. ``VIDIOC_QUERYCTRL`` will return the name
+of this control class which can be used as the title of a tab page
+within a control panel.
+
+The flags field of struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` also
+contains hints on the behavior of the control. See the
+:ref:`VIDIOC_QUERYCTRL` documentation for more
+details.
+
+
+.. _mpeg-controls:
+
+Codec Control Reference
+=======================
+
+Below all controls within the Codec control class are described. First
+the generic controls, then controls specific for certain hardware.
+
+Note: These controls are applicable to all codecs and not just MPEG. The
+defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG as the controls
+were originally made for MPEG codecs and later extended to cover all
+encoding formats.
+
+
+Generic Codec Controls
+----------------------
+
+
+.. _mpeg-control-id:
+
+Codec Control IDs
+^^^^^^^^^^^^^^^^^
+
+``V4L2_CID_MPEG_CLASS (class)``
+ The Codec class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class. This description can be
+ used as the caption of a Tab page in a GUI, for example.
+
+.. _v4l2-mpeg-stream-type:
+
+``V4L2_CID_MPEG_STREAM_TYPE (enum v4l2_mpeg_stream_type)``
+ The MPEG-1, -2 or -4 output stream type. One cannot assume anything
+ here. Each hardware MPEG encoder tends to support different subsets
+ of the available MPEG stream types. This control is specific to
+ multiplexed MPEG streams. The currently defined stream types are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_PS``
+
+ - MPEG-2 program stream
+
+ - .. row 2
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_TS``
+
+ - MPEG-2 transport stream
+
+ - .. row 3
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG1_SS``
+
+ - MPEG-1 system stream
+
+ - .. row 4
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_DVD``
+
+ - MPEG-2 DVD-compatible stream
+
+ - .. row 5
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG1_VCD``
+
+ - MPEG-1 VCD-compatible stream
+
+ - .. row 6
+
+ - ``V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD``
+
+ - MPEG-2 SVCD-compatible stream
+
+
+
+``V4L2_CID_MPEG_STREAM_PID_PMT (integer)``
+ Program Map Table Packet ID for the MPEG transport stream (default
+ 16)
+
+``V4L2_CID_MPEG_STREAM_PID_AUDIO (integer)``
+ Audio Packet ID for the MPEG transport stream (default 256)
+
+``V4L2_CID_MPEG_STREAM_PID_VIDEO (integer)``
+ Video Packet ID for the MPEG transport stream (default 260)
+
+``V4L2_CID_MPEG_STREAM_PID_PCR (integer)``
+ Packet ID for the MPEG transport stream carrying PCR fields (default
+ 259)
+
+``V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (integer)``
+ Audio ID for MPEG PES
+
+``V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (integer)``
+ Video ID for MPEG PES
+
+.. _v4l2-mpeg-stream-vbi-fmt:
+
+``V4L2_CID_MPEG_STREAM_VBI_FMT (enum v4l2_mpeg_stream_vbi_fmt)``
+ Some cards can embed VBI data (e. g. Closed Caption, Teletext) into
+ the MPEG stream. This control selects whether VBI data should be
+ embedded, and if so, what embedding method should be used. The list
+ of possible VBI formats depends on the driver. The currently defined
+ VBI format types are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_STREAM_VBI_FMT_NONE``
+
+ - No VBI in the MPEG stream
+
+ - .. row 2
+
+ - ``V4L2_MPEG_STREAM_VBI_FMT_IVTV``
+
+ - VBI in private packets, IVTV format (documented in the kernel
+ sources in the file
+ ``Documentation/video4linux/cx2341x/README.vbi``)
+
+
+
+.. _v4l2-mpeg-audio-sampling-freq:
+
+``V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (enum v4l2_mpeg_audio_sampling_freq)``
+ MPEG Audio sampling frequency. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100``
+
+ - 44.1 kHz
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000``
+
+ - 48 kHz
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000``
+
+ - 32 kHz
+
+
+
+.. _v4l2-mpeg-audio-encoding:
+
+``V4L2_CID_MPEG_AUDIO_ENCODING (enum v4l2_mpeg_audio_encoding)``
+ MPEG Audio encoding. This control is specific to multiplexed MPEG
+ streams. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_1``
+
+ - MPEG-1/2 Layer I encoding
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_2``
+
+ - MPEG-1/2 Layer II encoding
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_LAYER_3``
+
+ - MPEG-1/2 Layer III encoding
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_AAC``
+
+ - MPEG-2/4 AAC (Advanced Audio Coding)
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_ENCODING_AC3``
+
+ - AC-3 aka ATSC A/52 encoding
+
+
+
+.. _v4l2-mpeg-audio-l1-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_L1_BITRATE (enum v4l2_mpeg_audio_l1_bitrate)``
+ MPEG-1/2 Layer I bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_288K``
+
+ - 288 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_352K``
+
+ - 352 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_384K``
+
+ - 384 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_416K``
+
+ - 416 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L1_BITRATE_448K``
+
+ - 448 kbit/s
+
+
+
+.. _v4l2-mpeg-audio-l2-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_L2_BITRATE (enum v4l2_mpeg_audio_l2_bitrate)``
+ MPEG-1/2 Layer II bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L2_BITRATE_384K``
+
+ - 384 kbit/s
+
+
+
+.. _v4l2-mpeg-audio-l3-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_L3_BITRATE (enum v4l2_mpeg_audio_l3_bitrate)``
+ MPEG-1/2 Layer III bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_40K``
+
+ - 40 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_L3_BITRATE_320K``
+
+ - 320 kbit/s
+
+
+
+``V4L2_CID_MPEG_AUDIO_AAC_BITRATE (integer)``
+ AAC bitrate in bits per second.
+
+.. _v4l2-mpeg-audio-ac3-bitrate:
+
+``V4L2_CID_MPEG_AUDIO_AC3_BITRATE (enum v4l2_mpeg_audio_ac3_bitrate)``
+ AC-3 bitrate. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_32K``
+
+ - 32 kbit/s
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_40K``
+
+ - 40 kbit/s
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_48K``
+
+ - 48 kbit/s
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_56K``
+
+ - 56 kbit/s
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_64K``
+
+ - 64 kbit/s
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_80K``
+
+ - 80 kbit/s
+
+ - .. row 7
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_96K``
+
+ - 96 kbit/s
+
+ - .. row 8
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_112K``
+
+ - 112 kbit/s
+
+ - .. row 9
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_128K``
+
+ - 128 kbit/s
+
+ - .. row 10
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_160K``
+
+ - 160 kbit/s
+
+ - .. row 11
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_192K``
+
+ - 192 kbit/s
+
+ - .. row 12
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_224K``
+
+ - 224 kbit/s
+
+ - .. row 13
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_256K``
+
+ - 256 kbit/s
+
+ - .. row 14
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_320K``
+
+ - 320 kbit/s
+
+ - .. row 15
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_384K``
+
+ - 384 kbit/s
+
+ - .. row 16
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_448K``
+
+ - 448 kbit/s
+
+ - .. row 17
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_512K``
+
+ - 512 kbit/s
+
+ - .. row 18
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_576K``
+
+ - 576 kbit/s
+
+ - .. row 19
+
+ - ``V4L2_MPEG_AUDIO_AC3_BITRATE_640K``
+
+ - 640 kbit/s
+
+
+
+.. _v4l2-mpeg-audio-mode:
+
+``V4L2_CID_MPEG_AUDIO_MODE (enum v4l2_mpeg_audio_mode)``
+ MPEG Audio mode. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_MODE_STEREO``
+
+ - Stereo
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_MODE_JOINT_STEREO``
+
+ - Joint Stereo
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_MODE_DUAL``
+
+ - Bilingual
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_MODE_MONO``
+
+ - Mono
+
+
+
+.. _v4l2-mpeg-audio-mode-extension:
+
+``V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (enum v4l2_mpeg_audio_mode_extension)``
+ Joint Stereo audio mode extension. In Layer I and II they indicate
+ which subbands are in intensity stereo. All other subbands are coded
+ in stereo. Layer III is not (yet) supported. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4``
+
+ - Subbands 4-31 in intensity stereo
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8``
+
+ - Subbands 8-31 in intensity stereo
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12``
+
+ - Subbands 12-31 in intensity stereo
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16``
+
+ - Subbands 16-31 in intensity stereo
+
+
+
+.. _v4l2-mpeg-audio-emphasis:
+
+``V4L2_CID_MPEG_AUDIO_EMPHASIS (enum v4l2_mpeg_audio_emphasis)``
+ Audio Emphasis. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_NONE``
+
+ - None
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS``
+
+ - 50/15 microsecond emphasis
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17``
+
+ - CCITT J.17
+
+
+
+.. _v4l2-mpeg-audio-crc:
+
+``V4L2_CID_MPEG_AUDIO_CRC (enum v4l2_mpeg_audio_crc)``
+ CRC method. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_CRC_NONE``
+
+ - None
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_CRC_CRC16``
+
+ - 16 bit parity check
+
+
+
+``V4L2_CID_MPEG_AUDIO_MUTE (boolean)``
+ Mutes the audio when capturing. This is not done by muting audio
+ hardware, which can still produce a slight hiss, but in the encoder
+ itself, guaranteeing a fixed and reproducible audio bitstream. 0 =
+ unmuted, 1 = muted.
+
+.. _v4l2-mpeg-audio-dec-playback:
+
+``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
+ Determines how monolingual audio should be played back. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO``
+
+ - Automatically determines the best playback mode.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO``
+
+ - Stereo playback.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT``
+
+ - Left channel playback.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT``
+
+ - Right channel playback.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO``
+
+ - Mono playback.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO``
+
+ - Stereo playback with swapped left and right channels.
+
+
+
+.. _v4l2-mpeg-audio-dec-multilingual-playback:
+
+``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK (enum v4l2_mpeg_audio_dec_playback)``
+ Determines how multilingual audio should be played back.
+
+.. _v4l2-mpeg-video-encoding:
+
+``V4L2_CID_MPEG_VIDEO_ENCODING (enum v4l2_mpeg_video_encoding)``
+ MPEG Video encoding method. This control is specific to multiplexed
+ MPEG streams. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_1``
+
+ - MPEG-1 Video encoding
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_2``
+
+ - MPEG-2 Video encoding
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC``
+
+ - MPEG-4 AVC (H.264) Video encoding
+
+
+
+.. _v4l2-mpeg-video-aspect:
+
+``V4L2_CID_MPEG_VIDEO_ASPECT (enum v4l2_mpeg_video_aspect)``
+ Video aspect. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_1x1``
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_4x3``
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_16x9``
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_ASPECT_221x100``
+
+
+
+``V4L2_CID_MPEG_VIDEO_B_FRAMES (integer)``
+ Number of B-Frames (default 2)
+
+``V4L2_CID_MPEG_VIDEO_GOP_SIZE (integer)``
+ GOP size (default 12)
+
+``V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (boolean)``
+ GOP closure (default 1)
+
+``V4L2_CID_MPEG_VIDEO_PULLDOWN (boolean)``
+ Enable 3:2 pulldown (default 0)
+
+.. _v4l2-mpeg-video-bitrate-mode:
+
+``V4L2_CID_MPEG_VIDEO_BITRATE_MODE (enum v4l2_mpeg_video_bitrate_mode)``
+ Video bitrate mode. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_BITRATE_MODE_VBR``
+
+ - Variable bitrate
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_BITRATE_MODE_CBR``
+
+ - Constant bitrate
+
+
+
+``V4L2_CID_MPEG_VIDEO_BITRATE (integer)``
+ Video bitrate in bits per second.
+
+``V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)``
+ Peak video bitrate in bits per second. Must be larger or equal to
+ the average video bitrate. It is ignored if the video bitrate mode
+ is set to constant bitrate.
+
+``V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (integer)``
+ For every captured frame, skip this many subsequent frames (default
+ 0).
+
+``V4L2_CID_MPEG_VIDEO_MUTE (boolean)``
+ "Mutes" the video to a fixed color when capturing. This is useful
+ for testing, to produce a fixed video bitstream. 0 = unmuted, 1 =
+ muted.
+
+``V4L2_CID_MPEG_VIDEO_MUTE_YUV (integer)``
+ Sets the "mute" color of the video. The supplied 32-bit integer is
+ interpreted as follows (bit 0 = least significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:7
+
+ - V chrominance information
+
+ - .. row 2
+
+ - Bit 8:15
+
+ - U chrominance information
+
+ - .. row 3
+
+ - Bit 16:23
+
+ - Y luminance information
+
+ - .. row 4
+
+ - Bit 24:31
+
+ - Must be zero.
+
+
+
+.. _v4l2-mpeg-video-dec-pts:
+
+``V4L2_CID_MPEG_VIDEO_DEC_PTS (integer64)``
+ This read-only control returns the 33-bit video Presentation Time
+ Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of the
+ currently displayed frame. This is the same PTS as is used in
+ :ref:`VIDIOC_DECODER_CMD`.
+
+.. _v4l2-mpeg-video-dec-frame:
+
+``V4L2_CID_MPEG_VIDEO_DEC_FRAME (integer64)``
+ This read-only control returns the frame counter of the frame that
+ is currently displayed (decoded). This value is reset to 0 whenever
+ the decoder is started.
+
+``V4L2_CID_MPEG_VIDEO_DECODER_SLICE_INTERFACE (boolean)``
+ If enabled the decoder expects to receive a single slice per buffer,
+ otherwise the decoder expects a single frame in per buffer.
+ Applicable to the decoder, all codecs.
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_ENABLE (boolean)``
+ Enable writing sample aspect ratio in the Video Usability
+ Information. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-vui-sar-idc:
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_SAR_IDC (enum v4l2_mpeg_video_h264_vui_sar_idc)``
+ VUI sample aspect ratio indicator for H.264 encoding. The value is
+ defined in the table E-1 in the standard. Applicable to the H264
+ encoder.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_UNSPECIFIED``
+
+ - Unspecified
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_1x1``
+
+ - 1x1
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_12x11``
+
+ - 12x11
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_10x11``
+
+ - 10x11
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_16x11``
+
+ - 16x11
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_40x33``
+
+ - 40x33
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_24x11``
+
+ - 24x11
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_20x11``
+
+ - 20x11
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_32x11``
+
+ - 32x11
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_80x33``
+
+ - 80x33
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_18x11``
+
+ - 18x11
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_15x11``
+
+ - 15x11
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_64x33``
+
+ - 64x33
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_160x99``
+
+ - 160x99
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_4x3``
+
+ - 4x3
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_3x2``
+
+ - 3x2
+
+ - .. row 17
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_2x1``
+
+ - 2x1
+
+ - .. row 18
+
+ - ``V4L2_MPEG_VIDEO_H264_VUI_SAR_IDC_EXTENDED``
+
+ - Extended SAR
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_WIDTH (integer)``
+ Extended sample aspect ratio width for H.264 VUI encoding.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_VUI_EXT_SAR_HEIGHT (integer)``
+ Extended sample aspect ratio height for H.264 VUI encoding.
+ Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-level:
+
+``V4L2_CID_MPEG_VIDEO_H264_LEVEL (enum v4l2_mpeg_video_h264_level)``
+ The level information for the H264 video elementary stream.
+ Applicable to the H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_0``
+
+ - Level 1.0
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1B``
+
+ - Level 1B
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_1``
+
+ - Level 1.1
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_2``
+
+ - Level 1.2
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_1_3``
+
+ - Level 1.3
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_0``
+
+ - Level 2.0
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_1``
+
+ - Level 2.1
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_2_2``
+
+ - Level 2.2
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_0``
+
+ - Level 3.0
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_1``
+
+ - Level 3.1
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_3_2``
+
+ - Level 3.2
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_0``
+
+ - Level 4.0
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_1``
+
+ - Level 4.1
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_4_2``
+
+ - Level 4.2
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_0``
+
+ - Level 5.0
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_LEVEL_5_1``
+
+ - Level 5.1
+
+
+
+.. _v4l2-mpeg-video-mpeg4-level:
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_LEVEL (enum v4l2_mpeg_video_mpeg4_level)``
+ The level information for the MPEG4 elementary stream. Applicable to
+ the MPEG4 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_0``
+
+ - Level 0
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_0B``
+
+ - Level 0b
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_1``
+
+ - Level 1
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_2``
+
+ - Level 2
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_3``
+
+ - Level 3
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_3B``
+
+ - Level 3b
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_4``
+
+ - Level 4
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_LEVEL_5``
+
+ - Level 5
+
+
+
+.. _v4l2-mpeg-video-h264-profile:
+
+``V4L2_CID_MPEG_VIDEO_H264_PROFILE (enum v4l2_mpeg_video_h264_profile)``
+ The profile information for H264. Applicable to the H264 encoder.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_BASELINE``
+
+ - Baseline profile
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_CONSTRAINED_BASELINE``
+
+ - Constrained Baseline profile
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_MAIN``
+
+ - Main profile
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_EXTENDED``
+
+ - Extended profile
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH``
+
+ - High profile
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10``
+
+ - High 10 profile
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422``
+
+ - High 422 profile
+
+ - .. row 8
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_PREDICTIVE``
+
+ - High 444 Predictive profile
+
+ - .. row 9
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_10_INTRA``
+
+ - High 10 Intra profile
+
+ - .. row 10
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_422_INTRA``
+
+ - High 422 Intra profile
+
+ - .. row 11
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_HIGH_444_INTRA``
+
+ - High 444 Intra profile
+
+ - .. row 12
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_CAVLC_444_INTRA``
+
+ - CAVLC 444 Intra profile
+
+ - .. row 13
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_BASELINE``
+
+ - Scalable Baseline profile
+
+ - .. row 14
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH``
+
+ - Scalable High profile
+
+ - .. row 15
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_SCALABLE_HIGH_INTRA``
+
+ - Scalable High Intra profile
+
+ - .. row 16
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_STEREO_HIGH``
+
+ - Stereo High profile
+
+ - .. row 17
+
+ - ``V4L2_MPEG_VIDEO_H264_PROFILE_MULTIVIEW_HIGH``
+
+ - Multiview High profile
+
+
+
+.. _v4l2-mpeg-video-mpeg4-profile:
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_PROFILE (enum v4l2_mpeg_video_mpeg4_profile)``
+ The profile information for MPEG4. Applicable to the MPEG4 encoder.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE``
+
+ - Simple profile
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_SIMPLE``
+
+ - Advanced Simple profile
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_CORE``
+
+ - Core profile
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_SIMPLE_SCALABLE``
+
+ - Simple Scalable profile
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_PROFILE_ADVANCED_CODING_EFFICIENCY``
+
+ -
+
+
+
+``V4L2_CID_MPEG_VIDEO_MAX_REF_PIC (integer)``
+ The maximum number of reference pictures used for encoding.
+ Applicable to the encoder.
+
+.. _v4l2-mpeg-video-multi-slice-mode:
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE (enum v4l2_mpeg_video_multi_slice_mode)``
+ Determines how the encoder should handle division of frame into
+ slices. Applicable to the encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_SINGLE``
+
+ - Single slice per frame.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``
+
+ - Multiple slices with set maximum number of macroblocks per slice.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``
+
+ - Multiple slice with set maximum size in bytes per slice.
+
+
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_MB (integer)``
+ The maximum number of macroblocks in a slice. Used when
+ ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
+ ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_MB``. Applicable to the
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MAX_BYTES (integer)``
+ The maximum size of a slice in bytes. Used when
+ ``V4L2_CID_MPEG_VIDEO_MULTI_SLICE_MODE`` is set to
+ ``V4L2_MPEG_VIDEO_MULTI_SLICE_MODE_MAX_BYTES``. Applicable to the
+ encoder.
+
+.. _v4l2-mpeg-video-h264-loop-filter-mode:
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_MODE (enum v4l2_mpeg_video_h264_loop_filter_mode)``
+ Loop filter mode for H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_ENABLED``
+
+ - Loop filter is enabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED``
+
+ - Loop filter is disabled.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_LOOP_FILTER_MODE_DISABLED_AT_SLICE_BOUNDARY``
+
+ - Loop filter is disabled at the slice boundary.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_ALPHA (integer)``
+ Loop filter alpha coefficient, defined in the H264 standard.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_LOOP_FILTER_BETA (integer)``
+ Loop filter beta coefficient, defined in the H264 standard.
+ Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-entropy-mode:
+
+``V4L2_CID_MPEG_VIDEO_H264_ENTROPY_MODE (enum v4l2_mpeg_video_h264_entropy_mode)``
+ Entropy coding mode for H264 - CABAC/CAVALC. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CAVLC``
+
+ - Use CAVLC entropy coding.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_ENTROPY_MODE_CABAC``
+
+ - Use CABAC entropy coding.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_8X8_TRANSFORM (boolean)``
+ Enable 8X8 transform for H264. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_CYCLIC_INTRA_REFRESH_MB (integer)``
+ Cyclic intra macroblock refresh. This is the number of continuous
+ macroblocks refreshed every frame. Each frame a successive set of
+ macroblocks is refreshed until the cycle completes and starts from
+ the top of the frame. Applicable to H264, H263 and MPEG4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_FRAME_RC_ENABLE (boolean)``
+ Frame level rate control enable. If this control is disabled then
+ the quantization parameter for each frame type is constant and set
+ with appropriate controls (e.g.
+ ``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP``). If frame rate control is
+ enabled then quantization parameter is adjusted to meet the chosen
+ bitrate. Minimum and maximum value for the quantization parameter
+ can be set with appropriate controls (e.g.
+ ``V4L2_CID_MPEG_VIDEO_H263_MIN_QP``). Applicable to encoders.
+
+``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE (boolean)``
+ Macroblock level rate control enable. Applicable to the MPEG4 and
+ H264 encoders.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_QPEL (boolean)``
+ Quarter pixel motion estimation for MPEG4. Applicable to the MPEG4
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_H263_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_MIN_QP (integer)``
+ Minimum quantization parameter for H263. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_MAX_QP (integer)``
+ Maximum quantization parameter for H263. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H263_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for H263. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_H264_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_MIN_QP (integer)``
+ Minimum quantization parameter for H264. Valid range: from 0 to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_MAX_QP (integer)``
+ Maximum quantization parameter for H264. Valid range: from 0 to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_H264_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for H264. Valid range: from 0
+ to 51.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_MIN_QP (integer)``
+ Minimum quantization parameter for MPEG4. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_MAX_QP (integer)``
+ Maximum quantization parameter for MPEG4. Valid range: from 1 to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_P_FRAME_QP (integer)``
+ Quantization parameter for an P frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_B_FRAME_QP (integer)``
+ Quantization parameter for an B frame for MPEG4. Valid range: from 1
+ to 31.
+
+``V4L2_CID_MPEG_VIDEO_VBV_SIZE (integer)``
+ The Video Buffer Verifier size in kilobytes, it is used as a
+ limitation of frame skip. The VBV is defined in the standard as a
+ mean to verify that the produced stream will be successfully
+ decoded. The standard describes it as "Part of a hypothetical
+ decoder that is conceptually connected to the output of the encoder.
+ Its purpose is to provide a constraint on the variability of the
+ data rate that an encoder or editing process may produce.".
+ Applicable to the MPEG1, MPEG2, MPEG4 encoders.
+
+.. _v4l2-mpeg-video-vbv-delay:
+
+``V4L2_CID_MPEG_VIDEO_VBV_DELAY (integer)``
+ Sets the initial delay in milliseconds for VBV buffer control.
+
+.. _v4l2-mpeg-video-hor-search-range:
+
+``V4L2_CID_MPEG_VIDEO_MV_H_SEARCH_RANGE (integer)``
+ Horizontal search range defines maximum horizontal search area in
+ pixels to search and match for the present Macroblock (MB) in the
+ reference picture. This V4L2 control macro is used to set horizontal
+ search range for motion estimation module in video encoder.
+
+.. _v4l2-mpeg-video-vert-search-range:
+
+``V4L2_CID_MPEG_VIDEO_MV_V_SEARCH_RANGE (integer)``
+ Vertical search range defines maximum vertical search area in pixels
+ to search and match for the present Macroblock (MB) in the reference
+ picture. This V4L2 control macro is used to set vertical search
+ range for motion estimation module in video encoder.
+
+.. _v4l2-mpeg-video-force-key-frame:
+
+``V4L2_CID_MPEG_VIDEO_FORCE_KEY_FRAME (button)``
+ Force a key frame for the next queued buffer. Applicable to
+ encoders. This is a general, codec-agnostic keyframe control.
+
+``V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)``
+ The Coded Picture Buffer size in kilobytes, it is used as a
+ limitation of frame skip. The CPB is defined in the H264 standard as
+ a mean to verify that the produced stream will be successfully
+ decoded. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_I_PERIOD (integer)``
+ Period between I-frames in the open GOP for H264. In case of an open
+ GOP this is the period between two I-frames. The period between IDR
+ (Instantaneous Decoding Refresh) frames is taken from the GOP_SIZE
+ control. An IDR frame, which stands for Instantaneous Decoding
+ Refresh is an I-frame after which no prior frames are referenced.
+ This means that a stream can be restarted from an IDR frame without
+ the need to store or decode any previous frames. Applicable to the
+ H264 encoder.
+
+.. _v4l2-mpeg-video-header-mode:
+
+``V4L2_CID_MPEG_VIDEO_HEADER_MODE (enum v4l2_mpeg_video_header_mode)``
+ Determines whether the header is returned as the first buffer or is
+ it returned together with the first frame. Applicable to encoders.
+ Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_HEADER_MODE_SEPARATE``
+
+ - The stream header is returned separately in the first buffer.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_HEADER_MODE_JOINED_WITH_1ST_FRAME``
+
+ - The stream header is returned together with the first encoded
+ frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER (boolean)``
+ Repeat the video sequence headers. Repeating these headers makes
+ random access to the video stream easier. Applicable to the MPEG1, 2
+ and 4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER (boolean)``
+ Enabled the deblocking post processing filter for MPEG4 decoder.
+ Applicable to the MPEG4 decoder.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_RES (integer)``
+ vop_time_increment_resolution value for MPEG4. Applicable to the
+ MPEG4 encoder.
+
+``V4L2_CID_MPEG_VIDEO_MPEG4_VOP_TIME_INC (integer)``
+ vop_time_increment value for MPEG4. Applicable to the MPEG4
+ encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING (boolean)``
+ Enable generation of frame packing supplemental enhancement
+ information in the encoded bitstream. The frame packing SEI message
+ contains the arrangement of L and R planes for 3D viewing.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0 (boolean)``
+ Sets current frame as frame0 in frame packing SEI. Applicable to the
+ H264 encoder.
+
+.. _v4l2-mpeg-video-h264-sei-fp-arrangement-type:
+
+``V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE (enum v4l2_mpeg_video_h264_sei_fp_arrangement_type)``
+ Frame packing arrangement type for H264 SEI. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD``
+
+ - Pixels are alternatively from L and R.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN``
+
+ - L and R are interlaced by column.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW``
+
+ - L and R are interlaced by row.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE``
+
+ - L is on the left, R on the right.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM``
+
+ - L is on top, R on bottom.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL``
+
+ - One view per frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO (boolean)``
+ Enables flexible macroblock ordering in the encoded bitstream. It is
+ a technique used for restructuring the ordering of macroblocks in
+ pictures. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-fmo-map-type:
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE (enum v4l2_mpeg_video_h264_fmo_map_type)``
+ When using FMO, the map type divides the image in different scan
+ patterns of macroblocks. Applicable to the H264 encoder. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES``
+
+ - Slices are interleaved one after other with macroblocks in run
+ length order.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES``
+
+ - Scatters the macroblocks based on a mathematical function known to
+ both encoder and decoder.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER``
+
+ - Macroblocks arranged in rectangular areas or regions of interest.
+
+ - .. row 4
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT``
+
+ - Slice groups grow in a cyclic way from centre to outwards.
+
+ - .. row 5
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN``
+
+ - Slice groups grow in raster scan pattern from left to right.
+
+ - .. row 6
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN``
+
+ - Slice groups grow in wipe scan pattern from top to bottom.
+
+ - .. row 7
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT``
+
+ - User defined map type.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP (integer)``
+ Number of slice groups in FMO. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-fmo-change-direction:
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION (enum v4l2_mpeg_video_h264_fmo_change_dir)``
+ Specifies a direction of the slice group change for raster and wipe
+ maps. Applicable to the H264 encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT``
+
+ - Raster scan or wipe right.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT``
+
+ - Reverse raster scan or wipe left.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE (integer)``
+ Specifies the size of the first slice group for raster and wipe map.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH (integer)``
+ Specifies the number of consecutive macroblocks for the interleaved
+ map. Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_ASO (boolean)``
+ Enables arbitrary slice ordering in encoded bitstream. Applicable to
+ the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER (integer)``
+ Specifies the slice order in ASO. Applicable to the H264 encoder.
+ The supplied 32-bit integer is interpreted as follows (bit 0 = least
+ significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:15
+
+ - Slice ID
+
+ - .. row 2
+
+ - Bit 16:32
+
+ - Slice position or order
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING (boolean)``
+ Enables H264 hierarchical coding. Applicable to the H264 encoder.
+
+.. _v4l2-mpeg-video-h264-hierarchical-coding-type:
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE (enum v4l2_mpeg_video_h264_hierarchical_coding_type)``
+ Specifies the hierarchical coding type. Applicable to the H264
+ encoder. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B``
+
+ - Hierarchical B coding.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P``
+
+ - Hierarchical P coding.
+
+
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER (integer)``
+ Specifies the number of hierarchical coding layers. Applicable to
+ the H264 encoder.
+
+``V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP (integer)``
+ Specifies a user defined QP for each layer. Applicable to the H264
+ encoder. The supplied 32-bit integer is interpreted as follows (bit
+ 0 = least significant bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:15
+
+ - QP value
+
+ - .. row 2
+
+ - Bit 16:32
+
+ - Layer number
+
+
+
+
+MFC 5.1 MPEG Controls
+---------------------
+
+The following MPEG class controls deal with MPEG decoding and encoding
+settings that are specific to the Multi Format Codec 5.1 device present
+in the S5P family of SoCs by Samsung.
+
+
+.. _mfc51-control-id:
+
+MFC 5.1 Control IDs
+^^^^^^^^^^^^^^^^^^^
+
+``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY_ENABLE (boolean)``
+ If the display delay is enabled then the decoder is forced to return
+ a CAPTURE buffer (decoded frame) after processing a certain number
+ of OUTPUT buffers. The delay can be set through
+ ``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY``. This
+ feature can be used for example for generating thumbnails of videos.
+ Applicable to the H264 decoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_DECODER_H264_DISPLAY_DELAY (integer)``
+ Display delay value for H264 decoder. The decoder is forced to
+ return a decoded frame after the set 'display delay' number of
+ frames. If this number is low it may result in frames returned out
+ of dispaly order, in addition the hardware may still be using the
+ returned buffer as a reference picture for subsequent frames.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_NUM_REF_PIC_FOR_P (integer)``
+ The number of reference pictures used for encoding a P picture.
+ Applicable to the H264 encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_PADDING (boolean)``
+ Padding enable in the encoder - use a color instead of repeating
+ border pixels. Applicable to encoders.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_PADDING_YUV (integer)``
+ Padding color in the encoder. Applicable to encoders. The supplied
+ 32-bit integer is interpreted as follows (bit 0 = least significant
+ bit):
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Bit 0:7
+
+ - V chrominance information
+
+ - .. row 2
+
+ - Bit 8:15
+
+ - U chrominance information
+
+ - .. row 3
+
+ - Bit 16:23
+
+ - Y luminance information
+
+ - .. row 4
+
+ - Bit 24:31
+
+ - Must be zero.
+
+
+
+``V4L2_CID_MPEG_MFC51_VIDEO_RC_REACTION_COEFF (integer)``
+ Reaction coefficient for MFC rate control. Applicable to encoders.
+
+ Note 1: Valid only when the frame level RC is enabled.
+
+ Note 2: For tight CBR, this field must be small (ex. 2 ~ 10). For
+ VBR, this field must be large (ex. 100 ~ 1000).
+
+ Note 3: It is not recommended to use the greater number than
+ FRAME_RATE * (10^9 / BIT_RATE).
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_DARK (boolean)``
+ Adaptive rate control for dark region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_SMOOTH (boolean)``
+ Adaptive rate control for smooth region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_STATIC (boolean)``
+ Adaptive rate control for static region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+``V4L2_CID_MPEG_MFC51_VIDEO_H264_ADAPTIVE_RC_ACTIVITY (boolean)``
+ Adaptive rate control for activity region. Valid only when H.264 and
+ macroblock level RC is enabled
+ (``V4L2_CID_MPEG_VIDEO_MB_RC_ENABLE``). Applicable to the H264
+ encoder.
+
+.. _v4l2-mpeg-mfc51-video-frame-skip-mode:
+
+``V4L2_CID_MPEG_MFC51_VIDEO_FRAME_SKIP_MODE (enum v4l2_mpeg_mfc51_video_frame_skip_mode)``
+ Indicates in what conditions the encoder should skip frames. If
+ encoding a frame would cause the encoded stream to be larger then a
+ chosen data limit then the frame will be skipped. Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_DISABLED``
+
+ - Frame skip mode is disabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_LEVEL_LIMIT``
+
+ - Frame skip mode enabled and buffer limit is set by the chosen
+ level and is defined by the standard.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_MFC51_FRAME_SKIP_MODE_BUF_LIMIT``
+
+ - Frame skip mode enabled and buffer limit is set by the VBV
+ (MPEG1/2/4) or CPB (H264) buffer size control.
+
+
+
+``V4L2_CID_MPEG_MFC51_VIDEO_RC_FIXED_TARGET_BIT (integer)``
+ Enable rate-control with fixed target bit. If this setting is
+ enabled, then the rate control logic of the encoder will calculate
+ the average bitrate for a GOP and keep it below or equal the set
+ bitrate target. Otherwise the rate control logic calculates the
+ overall average bitrate for the stream and keeps it below or equal
+ to the set bitrate. In the first case the average bitrate for the
+ whole stream will be smaller then the set bitrate. This is caused
+ because the average is calculated for smaller number of frames, on
+ the other hand enabling this setting will ensure that the stream
+ will meet tight bandwidth constraints. Applicable to encoders.
+
+.. _v4l2-mpeg-mfc51-video-force-frame-type:
+
+``V4L2_CID_MPEG_MFC51_VIDEO_FORCE_FRAME_TYPE (enum v4l2_mpeg_mfc51_video_force_frame_type)``
+ Force a frame type for the next queued buffer. Applicable to
+ encoders. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_DISABLED``
+
+ - Forcing a specific frame type disabled.
+
+ - .. row 2
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_I_FRAME``
+
+ - Force an I-frame.
+
+ - .. row 3
+
+ - ``V4L2_MPEG_MFC51_FORCE_FRAME_TYPE_NOT_CODED``
+
+ - Force a non-coded frame.
+
+
+
+
+CX2341x MPEG Controls
+---------------------
+
+The following MPEG class controls deal with MPEG encoding settings that
+are specific to the Conexant CX23415 and CX23416 MPEG encoding chips.
+
+
+.. _cx2341x-control-id:
+
+CX2341x Control IDs
+^^^^^^^^^^^^^^^^^^^
+
+.. _v4l2-mpeg-cx2341x-video-spatial-filter-mode:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_spatial_filter_mode)``
+ Sets the Spatial Filter mode (default ``MANUAL``). Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL``
+
+ - Choose the filter manually
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO``
+
+ - Choose the filter automatically
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (integer (0-15))``
+ The setting for the Spatial Filter. 0 = off, 15 = maximum. (Default
+ is 0.)
+
+.. _luma-spatial-filter-type:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_luma_spatial_filter_type)``
+ Select the algorithm to use for the Luma Spatial Filter (default
+ ``1D_HOR``). Possible values:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR``
+
+ - One-dimensional horizontal
+
+ - .. row 3
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT``
+
+ - One-dimensional vertical
+
+ - .. row 4
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE``
+
+ - Two-dimensional separable
+
+ - .. row 5
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE``
+
+ - Two-dimensional symmetrical non-separable
+
+
+
+.. _chroma-spatial-filter-type:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type)``
+ Select the algorithm for the Chroma Spatial Filter (default
+ ``1D_HOR``). Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR``
+
+ - One-dimensional horizontal
+
+
+
+.. _v4l2-mpeg-cx2341x-video-temporal-filter-mode:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (enum v4l2_mpeg_cx2341x_video_temporal_filter_mode)``
+ Sets the Temporal Filter mode (default ``MANUAL``). Possible values
+ are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL``
+
+ - Choose the filter manually
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO``
+
+ - Choose the filter automatically
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (integer (0-31))``
+ The setting for the Temporal Filter. 0 = off, 31 = maximum. (Default
+ is 8 for full-scale capturing and 0 for scaled capturing.)
+
+.. _v4l2-mpeg-cx2341x-video-median-filter-type:
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (enum v4l2_mpeg_cx2341x_video_median_filter_type)``
+ Median Filter Type (default ``OFF``). Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF``
+
+ - No filter
+
+ - .. row 2
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR``
+
+ - Horizontal filter
+
+ - .. row 3
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT``
+
+ - Vertical filter
+
+ - .. row 4
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT``
+
+ - Horizontal and vertical filter
+
+ - .. row 5
+
+ - ``V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG``
+
+ - Diagonal filter
+
+
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
+ Threshold above which the luminance median filter is enabled
+ (default 0)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (integer (0-255))``
+ Threshold below which the luminance median filter is enabled
+ (default 255)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (integer (0-255))``
+ Threshold above which the chroma median filter is enabled (default
+ 0)
+
+``V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (integer (0-255))``
+ Threshold below which the chroma median filter is enabled (default
+ 255)
+
+``V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (boolean)``
+ The CX2341X MPEG encoder can insert one empty MPEG-2 PES packet into
+ the stream between every four video frames. The packet size is 2048
+ bytes, including the packet_start_code_prefix and stream_id
+ fields. The stream_id is 0xBF (private stream 2). The payload
+ consists of 0x00 bytes, to be filled in by the application. 0 = do
+ not insert, 1 = insert packets.
+
+
+VPX Control Reference
+---------------------
+
+The VPX controls include controls for encoding parameters of VPx video
+codec.
+
+
+.. _vpx-control-id:
+
+VPX Control IDs
+^^^^^^^^^^^^^^^
+
+.. _v4l2-vpx-num-partitions:
+
+``V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS (enum v4l2_vp8_num_partitions)``
+ The number of token partitions to use in VP8 encoder. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION``
+
+ - 1 coefficient partition
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS``
+
+ - 2 coefficient partitions
+
+ - .. row 3
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS``
+
+ - 4 coefficient partitions
+
+ - .. row 4
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS``
+
+ - 8 coefficient partitions
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4 (boolean)``
+ Setting this prevents intra 4x4 mode in the intra mode decision.
+
+.. _v4l2-vpx-num-ref-frames:
+
+``V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES (enum v4l2_vp8_num_ref_frames)``
+ The number of reference pictures for encoding P frames. Possible
+ values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME``
+
+ - Last encoded frame will be searched
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME``
+
+ - Two frames will be searched among the last encoded frame, the
+ golden frame and the alternate reference (altref) frame. The
+ encoder implementation will decide which two are chosen.
+
+ - .. row 3
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME``
+
+ - The last encoded frame, the golden frame and the altref frame will
+ be searched.
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL (integer)``
+ Indicates the loop filter level. The adjustment of the loop filter
+ level is done via a delta value against a baseline loop filter
+ value.
+
+``V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS (integer)``
+ This parameter affects the loop filter. Anything above zero weakens
+ the deblocking effect on the loop filter.
+
+``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD (integer)``
+ Sets the refresh period for the golden frame. The period is defined
+ in number of frames. For a value of 'n', every nth frame starting
+ from the first key frame will be taken as a golden frame. For eg.
+ for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden
+ frame refresh period is set as 4, the frames 0, 4, 8 etc will be
+ taken as the golden frames as frame 0 is always a key frame.
+
+.. _v4l2-vpx-golden-frame-sel:
+
+``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL (enum v4l2_vp8_golden_frame_sel)``
+ Selects the golden frame for encoding. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV``
+
+ - Use the (n-2)th frame as a golden frame, current frame index being
+ 'n'.
+
+ - .. row 2
+
+ - ``V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD``
+
+ - Use the previous specific frame indicated by
+ V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a
+ golden frame.
+
+
+
+``V4L2_CID_MPEG_VIDEO_VPX_MIN_QP (integer)``
+ Minimum quantization parameter for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_MAX_QP (integer)``
+ Maximum quantization parameter for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_I_FRAME_QP (integer)``
+ Quantization parameter for an I frame for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_P_FRAME_QP (integer)``
+ Quantization parameter for a P frame for VP8.
+
+``V4L2_CID_MPEG_VIDEO_VPX_PROFILE (integer)``
+ Select the desired profile for VPx encoder. Acceptable values are 0,
+ 1, 2 and 3 corresponding to encoder profiles 0, 1, 2 and 3.
+
+
+.. _camera-controls:
+
+Camera Control Reference
+========================
+
+The Camera class includes controls for mechanical (or equivalent
+digital) features of a device such as controllable lenses or sensors.
+
+
+.. _camera-control-id:
+
+Camera Control IDs
+------------------
+
+``V4L2_CID_CAMERA_CLASS (class)``
+ The Camera class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+.. _v4l2-exposure-auto-type:
+
+``V4L2_CID_EXPOSURE_AUTO (enum v4l2_exposure_auto_type)``
+ Enables automatic adjustments of the exposure time and/or iris
+ aperture. The effect of manual changes of the exposure time or iris
+ aperture while these features are enabled is undefined, drivers
+ should ignore such requests. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_EXPOSURE_AUTO``
+
+ - Automatic exposure time, automatic iris aperture.
+
+ - .. row 2
+
+ - ``V4L2_EXPOSURE_MANUAL``
+
+ - Manual exposure time, manual iris.
+
+ - .. row 3
+
+ - ``V4L2_EXPOSURE_SHUTTER_PRIORITY``
+
+ - Manual exposure time, auto iris.
+
+ - .. row 4
+
+ - ``V4L2_EXPOSURE_APERTURE_PRIORITY``
+
+ - Auto exposure time, manual iris.
+
+
+
+``V4L2_CID_EXPOSURE_ABSOLUTE (integer)``
+ Determines the exposure time of the camera sensor. The exposure time
+ is limited by the frame interval. Drivers should interpret the
+ values as 100 µs units, where the value 1 stands for 1/10000th of a
+ second, 10000 for 1 second and 100000 for 10 seconds.
+
+``V4L2_CID_EXPOSURE_AUTO_PRIORITY (boolean)``
+ When ``V4L2_CID_EXPOSURE_AUTO`` is set to ``AUTO`` or
+ ``APERTURE_PRIORITY``, this control determines if the device may
+ dynamically vary the frame rate. By default this feature is disabled
+ (0) and the frame rate must remain constant.
+
+``V4L2_CID_EXPOSURE_BIAS (integer menu)``
+ Determines the automatic exposure compensation, it is effective only
+ when ``V4L2_CID_EXPOSURE_AUTO`` control is set to ``AUTO``,
+ ``SHUTTER_PRIORITY`` or ``APERTURE_PRIORITY``. It is expressed in
+ terms of EV, drivers should interpret the values as 0.001 EV units,
+ where the value 1000 stands for +1 EV.
+
+ Increasing the exposure compensation value is equivalent to
+ decreasing the exposure value (EV) and will increase the amount of
+ light at the image sensor. The camera performs the exposure
+ compensation by adjusting absolute exposure time and/or aperture.
+
+.. _v4l2-exposure-metering:
+
+``V4L2_CID_EXPOSURE_METERING (enum v4l2_exposure_metering)``
+ Determines how the camera measures the amount of light available for
+ the frame exposure. Possible values are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_EXPOSURE_METERING_AVERAGE``
+
+ - Use the light information coming from the entire frame and average
+ giving no weighting to any particular portion of the metered area.
+
+ - .. row 2
+
+ - ``V4L2_EXPOSURE_METERING_CENTER_WEIGHTED``
+
+ - Average the light information coming from the entire frame giving
+ priority to the center of the metered area.
+
+ - .. row 3
+
+ - ``V4L2_EXPOSURE_METERING_SPOT``
+
+ - Measure only very small area at the center of the frame.
+
+ - .. row 4
+
+ - ``V4L2_EXPOSURE_METERING_MATRIX``
+
+ - A multi-zone metering. The light intensity is measured in several
+ points of the frame and the results are combined. The algorithm of
+ the zones selection and their significance in calculating the
+ final value is device dependent.
+
+
+
+``V4L2_CID_PAN_RELATIVE (integer)``
+ This control turns the camera horizontally by the specified amount.
+ The unit is undefined. A positive value moves the camera to the
+ right (clockwise when viewed from above), a negative value to the
+ left. A value of zero does not cause motion. This is a write-only
+ control.
+
+``V4L2_CID_TILT_RELATIVE (integer)``
+ This control turns the camera vertically by the specified amount.
+ The unit is undefined. A positive value moves the camera up, a
+ negative value down. A value of zero does not cause motion. This is
+ a write-only control.
+
+``V4L2_CID_PAN_RESET (button)``
+ When this control is set, the camera moves horizontally to the
+ default position.
+
+``V4L2_CID_TILT_RESET (button)``
+ When this control is set, the camera moves vertically to the default
+ position.
+
+``V4L2_CID_PAN_ABSOLUTE (integer)``
+ This control turns the camera horizontally to the specified
+ position. Positive values move the camera to the right (clockwise
+ when viewed from above), negative values to the left. Drivers should
+ interpret the values as arc seconds, with valid values between -180
+ * 3600 and +180 * 3600 inclusive.
+
+``V4L2_CID_TILT_ABSOLUTE (integer)``
+ This control turns the camera vertically to the specified position.
+ Positive values move the camera up, negative values down. Drivers
+ should interpret the values as arc seconds, with valid values
+ between -180 * 3600 and +180 * 3600 inclusive.
+
+``V4L2_CID_FOCUS_ABSOLUTE (integer)``
+ This control sets the focal point of the camera to the specified
+ position. The unit is undefined. Positive values set the focus
+ closer to the camera, negative values towards infinity.
+
+``V4L2_CID_FOCUS_RELATIVE (integer)``
+ This control moves the focal point of the camera by the specified
+ amount. The unit is undefined. Positive values move the focus closer
+ to the camera, negative values towards infinity. This is a
+ write-only control.
+
+``V4L2_CID_FOCUS_AUTO (boolean)``
+ Enables continuous automatic focus adjustments. The effect of manual
+ focus adjustments while this feature is enabled is undefined,
+ drivers should ignore such requests.
+
+``V4L2_CID_AUTO_FOCUS_START (button)``
+ Starts single auto focus process. The effect of setting this control
+ when ``V4L2_CID_FOCUS_AUTO`` is set to ``TRUE`` (1) is undefined,
+ drivers should ignore such requests.
+
+``V4L2_CID_AUTO_FOCUS_STOP (button)``
+ Aborts automatic focusing started with ``V4L2_CID_AUTO_FOCUS_START``
+ control. It is effective only when the continuous autofocus is
+ disabled, that is when ``V4L2_CID_FOCUS_AUTO`` control is set to
+ ``FALSE`` (0).
+
+.. _v4l2-auto-focus-status:
+
+``V4L2_CID_AUTO_FOCUS_STATUS (bitmask)``
+ The automatic focus status. This is a read-only control.
+
+ Setting ``V4L2_LOCK_FOCUS`` lock bit of the ``V4L2_CID_3A_LOCK``
+ control may stop updates of the ``V4L2_CID_AUTO_FOCUS_STATUS``
+ control value.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_AUTO_FOCUS_STATUS_IDLE``
+
+ - Automatic focus is not active.
+
+ - .. row 2
+
+ - ``V4L2_AUTO_FOCUS_STATUS_BUSY``
+
+ - Automatic focusing is in progress.
+
+ - .. row 3
+
+ - ``V4L2_AUTO_FOCUS_STATUS_REACHED``
+
+ - Focus has been reached.
+
+ - .. row 4
+
+ - ``V4L2_AUTO_FOCUS_STATUS_FAILED``
+
+ - Automatic focus has failed, the driver will not transition from
+ this state until another action is performed by an application.
+
+
+
+.. _v4l2-auto-focus-range:
+
+``V4L2_CID_AUTO_FOCUS_RANGE (enum v4l2_auto_focus_range)``
+ Determines auto focus distance range for which lens may be adjusted.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_AUTO_FOCUS_RANGE_AUTO``
+
+ - The camera automatically selects the focus range.
+
+ - .. row 2
+
+ - ``V4L2_AUTO_FOCUS_RANGE_NORMAL``
+
+ - Normal distance range, limited for best automatic focus
+ performance.
+
+ - .. row 3
+
+ - ``V4L2_AUTO_FOCUS_RANGE_MACRO``
+
+ - Macro (close-up) auto focus. The camera will use its minimum
+ possible distance for auto focus.
+
+ - .. row 4
+
+ - ``V4L2_AUTO_FOCUS_RANGE_INFINITY``
+
+ - The lens is set to focus on an object at infinite distance.
+
+
+
+``V4L2_CID_ZOOM_ABSOLUTE (integer)``
+ Specify the objective lens focal length as an absolute value. The
+ zoom unit is driver-specific and its value should be a positive
+ integer.
+
+``V4L2_CID_ZOOM_RELATIVE (integer)``
+ Specify the objective lens focal length relatively to the current
+ value. Positive values move the zoom lens group towards the
+ telephoto direction, negative values towards the wide-angle
+ direction. The zoom unit is driver-specific. This is a write-only
+ control.
+
+``V4L2_CID_ZOOM_CONTINUOUS (integer)``
+ Move the objective lens group at the specified speed until it
+ reaches physical device limits or until an explicit request to stop
+ the movement. A positive value moves the zoom lens group towards the
+ telephoto direction. A value of zero stops the zoom lens group
+ movement. A negative value moves the zoom lens group towards the
+ wide-angle direction. The zoom speed unit is driver-specific.
+
+``V4L2_CID_IRIS_ABSOLUTE (integer)``
+ This control sets the camera's aperture to the specified value. The
+ unit is undefined. Larger values open the iris wider, smaller values
+ close it.
+
+``V4L2_CID_IRIS_RELATIVE (integer)``
+ This control modifies the camera's aperture by the specified amount.
+ The unit is undefined. Positive values open the iris one step
+ further, negative values close it one step further. This is a
+ write-only control.
+
+``V4L2_CID_PRIVACY (boolean)``
+ Prevent video from being acquired by the camera. When this control
+ is set to ``TRUE`` (1), no image can be captured by the camera.
+ Common means to enforce privacy are mechanical obturation of the
+ sensor and firmware image processing, but the device is not
+ restricted to these methods. Devices that implement the privacy
+ control must support read access and may support write access.
+
+``V4L2_CID_BAND_STOP_FILTER (integer)``
+ Switch the band-stop filter of a camera sensor on or off, or specify
+ its strength. Such band-stop filters can be used, for example, to
+ filter out the fluorescent light component.
+
+.. _v4l2-auto-n-preset-white-balance:
+
+``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE (enum v4l2_auto_n_preset_white_balance)``
+ Sets white balance to automatic, manual or a preset. The presets
+ determine color temperature of the light as a hint to the camera for
+ white balance adjustments resulting in most accurate color
+ representation. The following white balance presets are listed in
+ order of increasing color temperature.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_WHITE_BALANCE_MANUAL``
+
+ - Manual white balance.
+
+ - .. row 2
+
+ - ``V4L2_WHITE_BALANCE_AUTO``
+
+ - Automatic white balance adjustments.
+
+ - .. row 3
+
+ - ``V4L2_WHITE_BALANCE_INCANDESCENT``
+
+ - White balance setting for incandescent (tungsten) lighting. It
+ generally cools down the colors and corresponds approximately to
+ 2500...3500 K color temperature range.
+
+ - .. row 4
+
+ - ``V4L2_WHITE_BALANCE_FLUORESCENT``
+
+ - White balance preset for fluorescent lighting. It corresponds
+ approximately to 4000...5000 K color temperature.
+
+ - .. row 5
+
+ - ``V4L2_WHITE_BALANCE_FLUORESCENT_H``
+
+ - With this setting the camera will compensate for fluorescent H
+ lighting.
+
+ - .. row 6
+
+ - ``V4L2_WHITE_BALANCE_HORIZON``
+
+ - White balance setting for horizon daylight. It corresponds
+ approximately to 5000 K color temperature.
+
+ - .. row 7
+
+ - ``V4L2_WHITE_BALANCE_DAYLIGHT``
+
+ - White balance preset for daylight (with clear sky). It corresponds
+ approximately to 5000...6500 K color temperature.
+
+ - .. row 8
+
+ - ``V4L2_WHITE_BALANCE_FLASH``
+
+ - With this setting the camera will compensate for the flash light.
+ It slightly warms up the colors and corresponds roughly to
+ 5000...5500 K color temperature.
+
+ - .. row 9
+
+ - ``V4L2_WHITE_BALANCE_CLOUDY``
+
+ - White balance preset for moderately overcast sky. This option
+ corresponds approximately to 6500...8000 K color temperature
+ range.
+
+ - .. row 10
+
+ - ``V4L2_WHITE_BALANCE_SHADE``
+
+ - White balance preset for shade or heavily overcast sky. It
+ corresponds approximately to 9000...10000 K color temperature.
+
+
+
+.. _v4l2-wide-dynamic-range:
+
+``V4L2_CID_WIDE_DYNAMIC_RANGE (boolean)``
+ Enables or disables the camera's wide dynamic range feature. This
+ feature allows to obtain clear images in situations where intensity
+ of the illumination varies significantly throughout the scene, i.e.
+ there are simultaneously very dark and very bright areas. It is most
+ commonly realized in cameras by combining two subsequent frames with
+ different exposure times. [1]_
+
+.. _v4l2-image-stabilization:
+
+``V4L2_CID_IMAGE_STABILIZATION (boolean)``
+ Enables or disables image stabilization.
+
+``V4L2_CID_ISO_SENSITIVITY (integer menu)``
+ Determines ISO equivalent of an image sensor indicating the sensor's
+ sensitivity to light. The numbers are expressed in arithmetic scale,
+ as per :ref:`iso12232` standard, where doubling the sensor
+ sensitivity is represented by doubling the numerical ISO value.
+ Applications should interpret the values as standard ISO values
+ multiplied by 1000, e.g. control value 800 stands for ISO 0.8.
+ Drivers will usually support only a subset of standard ISO values.
+ The effect of setting this control while the
+ ``V4L2_CID_ISO_SENSITIVITY_AUTO`` control is set to a value other
+ than ``V4L2_CID_ISO_SENSITIVITY_MANUAL`` is undefined, drivers
+ should ignore such requests.
+
+.. _v4l2-iso-sensitivity-auto-type:
+
+``V4L2_CID_ISO_SENSITIVITY_AUTO (enum v4l2_iso_sensitivity_type)``
+ Enables or disables automatic ISO sensitivity adjustments.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_CID_ISO_SENSITIVITY_MANUAL``
+
+ - Manual ISO sensitivity.
+
+ - .. row 2
+
+ - ``V4L2_CID_ISO_SENSITIVITY_AUTO``
+
+ - Automatic ISO sensitivity adjustments.
+
+
+
+.. _v4l2-scene-mode:
+
+``V4L2_CID_SCENE_MODE (enum v4l2_scene_mode)``
+ This control allows to select scene programs as the camera automatic
+ modes optimized for common shooting scenes. Within these modes the
+ camera determines best exposure, aperture, focusing, light metering,
+ white balance and equivalent sensitivity. The controls of those
+ parameters are influenced by the scene mode control. An exact
+ behavior in each mode is subject to the camera specification.
+
+ When the scene mode feature is not used, this control should be set
+ to ``V4L2_SCENE_MODE_NONE`` to make sure the other possibly related
+ controls are accessible. The following scene programs are defined:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_SCENE_MODE_NONE``
+
+ - The scene mode feature is disabled.
+
+ - .. row 2
+
+ - ``V4L2_SCENE_MODE_BACKLIGHT``
+
+ - Backlight. Compensates for dark shadows when light is coming from
+ behind a subject, also by automatically turning on the flash.
+
+ - .. row 3
+
+ - ``V4L2_SCENE_MODE_BEACH_SNOW``
+
+ - Beach and snow. This mode compensates for all-white or bright
+ scenes, which tend to look gray and low contrast, when camera's
+ automatic exposure is based on an average scene brightness. To
+ compensate, this mode automatically slightly overexposes the
+ frames. The white balance may also be adjusted to compensate for
+ the fact that reflected snow looks bluish rather than white.
+
+ - .. row 4
+
+ - ``V4L2_SCENE_MODE_CANDLELIGHT``
+
+ - Candle light. The camera generally raises the ISO sensitivity and
+ lowers the shutter speed. This mode compensates for relatively
+ close subject in the scene. The flash is disabled in order to
+ preserve the ambiance of the light.
+
+ - .. row 5
+
+ - ``V4L2_SCENE_MODE_DAWN_DUSK``
+
+ - Dawn and dusk. Preserves the colors seen in low natural light
+ before dusk and after down. The camera may turn off the flash, and
+ automatically focus at infinity. It will usually boost saturation
+ and lower the shutter speed.
+
+ - .. row 6
+
+ - ``V4L2_SCENE_MODE_FALL_COLORS``
+
+ - Fall colors. Increases saturation and adjusts white balance for
+ color enhancement. Pictures of autumn leaves get saturated reds
+ and yellows.
+
+ - .. row 7
+
+ - ``V4L2_SCENE_MODE_FIREWORKS``
+
+ - Fireworks. Long exposure times are used to capture the expanding
+ burst of light from a firework. The camera may invoke image
+ stabilization.
+
+ - .. row 8
+
+ - ``V4L2_SCENE_MODE_LANDSCAPE``
+
+ - Landscape. The camera may choose a small aperture to provide deep
+ depth of field and long exposure duration to help capture detail
+ in dim light conditions. The focus is fixed at infinity. Suitable
+ for distant and wide scenery.
+
+ - .. row 9
+
+ - ``V4L2_SCENE_MODE_NIGHT``
+
+ - Night, also known as Night Landscape. Designed for low light
+ conditions, it preserves detail in the dark areas without blowing
+ out bright objects. The camera generally sets itself to a
+ medium-to-high ISO sensitivity, with a relatively long exposure
+ time, and turns flash off. As such, there will be increased image
+ noise and the possibility of blurred image.
+
+ - .. row 10
+
+ - ``V4L2_SCENE_MODE_PARTY_INDOOR``
+
+ - Party and indoor. Designed to capture indoor scenes that are lit
+ by indoor background lighting as well as the flash. The camera
+ usually increases ISO sensitivity, and adjusts exposure for the
+ low light conditions.
+
+ - .. row 11
+
+ - ``V4L2_SCENE_MODE_PORTRAIT``
+
+ - Portrait. The camera adjusts the aperture so that the depth of
+ field is reduced, which helps to isolate the subject against a
+ smooth background. Most cameras recognize the presence of faces in
+ the scene and focus on them. The color hue is adjusted to enhance
+ skin tones. The intensity of the flash is often reduced.
+
+ - .. row 12
+
+ - ``V4L2_SCENE_MODE_SPORTS``
+
+ - Sports. Significantly increases ISO and uses a fast shutter speed
+ to freeze motion of rapidly-moving subjects. Increased image noise
+ may be seen in this mode.
+
+ - .. row 13
+
+ - ``V4L2_SCENE_MODE_SUNSET``
+
+ - Sunset. Preserves deep hues seen in sunsets and sunrises. It bumps
+ up the saturation.
+
+ - .. row 14
+
+ - ``V4L2_SCENE_MODE_TEXT``
+
+ - Text. It applies extra contrast and sharpness, it is typically a
+ black-and-white mode optimized for readability. Automatic focus
+ may be switched to close-up mode and this setting may also involve
+ some lens-distortion correction.
+
+
+
+``V4L2_CID_3A_LOCK (bitmask)``
+ This control locks or unlocks the automatic focus, exposure and
+ white balance. The automatic adjustments can be paused independently
+ by setting the corresponding lock bit to 1. The camera then retains
+ the settings until the lock bit is cleared. The following lock bits
+ are defined:
+
+ When a given algorithm is not enabled, drivers should ignore
+ requests to lock it and should return no error. An example might be
+ an application setting bit ``V4L2_LOCK_WHITE_BALANCE`` when the
+ ``V4L2_CID_AUTO_WHITE_BALANCE`` control is set to ``FALSE``. The
+ value of this control may be changed by exposure, white balance or
+ focus controls.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_LOCK_EXPOSURE``
+
+ - Automatic exposure adjustments lock.
+
+ - .. row 2
+
+ - ``V4L2_LOCK_WHITE_BALANCE``
+
+ - Automatic white balance adjustments lock.
+
+ - .. row 3
+
+ - ``V4L2_LOCK_FOCUS``
+
+ - Automatic focus lock.
+
+
+
+``V4L2_CID_PAN_SPEED (integer)``
+ This control turns the camera horizontally at the specific speed.
+ The unit is undefined. A positive value moves the camera to the
+ right (clockwise when viewed from above), a negative value to the
+ left. A value of zero stops the motion if one is in progress and has
+ no effect otherwise.
+
+``V4L2_CID_TILT_SPEED (integer)``
+ This control turns the camera vertically at the specified speed. The
+ unit is undefined. A positive value moves the camera up, a negative
+ value down. A value of zero stops the motion if one is in progress
+ and has no effect otherwise.
+
+
+.. _fm-tx-controls:
+
+FM Transmitter Control Reference
+================================
+
+The FM Transmitter (FM_TX) class includes controls for common features
+of FM transmissions capable devices. Currently this class includes
+parameters for audio compression, pilot tone generation, audio deviation
+limiter, RDS transmission and tuning power features.
+
+
+.. _fm-tx-control-id:
+
+FM_TX Control IDs
+-----------------
+
+``V4L2_CID_FM_TX_CLASS (class)``
+ The FM_TX class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RDS_TX_DEVIATION (integer)``
+ Configures RDS signal frequency deviation level in Hz. The range and
+ step are driver-specific.
+
+``V4L2_CID_RDS_TX_PI (integer)``
+ Sets the RDS Programme Identification field for transmission.
+
+``V4L2_CID_RDS_TX_PTY (integer)``
+ Sets the RDS Programme Type field for transmission. This encodes up
+ to 31 pre-defined programme types.
+
+``V4L2_CID_RDS_TX_PS_NAME (string)``
+ Sets the Programme Service name (PS_NAME) for transmission. It is
+ intended for static display on a receiver. It is the primary aid to
+ listeners in programme service identification and selection. In
+ Annex E of :ref:`iec62106`, the RDS specification, there is a full
+ description of the correct character encoding for Programme Service
+ name strings. Also from RDS specification, PS is usually a single
+ eight character text. However, it is also possible to find receivers
+ which can scroll strings sized as 8 x N characters. So, this control
+ must be configured with steps of 8 characters. The result is it must
+ always contain a string with size multiple of 8.
+
+``V4L2_CID_RDS_TX_RADIO_TEXT (string)``
+ Sets the Radio Text info for transmission. It is a textual
+ description of what is being broadcasted. RDS Radio Text can be
+ applied when broadcaster wishes to transmit longer PS names,
+ programme-related information or any other text. In these cases,
+ RadioText should be used in addition to ``V4L2_CID_RDS_TX_PS_NAME``.
+ The encoding for Radio Text strings is also fully described in Annex
+ E of :ref:`iec62106`. The length of Radio Text strings depends on
+ which RDS Block is being used to transmit it, either 32 (2A block)
+ or 64 (2B block). However, it is also possible to find receivers
+ which can scroll strings sized as 32 x N or 64 x N characters. So,
+ this control must be configured with steps of 32 or 64 characters.
+ The result is it must always contain a string with size multiple of
+ 32 or 64.
+
+``V4L2_CID_RDS_TX_MONO_STEREO (boolean)``
+ Sets the Mono/Stereo bit of the Decoder Identification code. If set,
+ then the audio was recorded as stereo.
+
+``V4L2_CID_RDS_TX_ARTIFICIAL_HEAD (boolean)``
+ Sets the
+ `Artificial Head <http://en.wikipedia.org/wiki/Artificial_head>`__
+ bit of the Decoder Identification code. If set, then the audio was
+ recorded using an artificial head.
+
+``V4L2_CID_RDS_TX_COMPRESSED (boolean)``
+ Sets the Compressed bit of the Decoder Identification code. If set,
+ then the audio is compressed.
+
+``V4L2_CID_RDS_TX_DYNAMIC_PTY (boolean)``
+ Sets the Dynamic PTY bit of the Decoder Identification code. If set,
+ then the PTY code is dynamically switched.
+
+``V4L2_CID_RDS_TX_TRAFFIC_ANNOUNCEMENT (boolean)``
+ If set, then a traffic announcement is in progress.
+
+``V4L2_CID_RDS_TX_TRAFFIC_PROGRAM (boolean)``
+ If set, then the tuned programme carries traffic announcements.
+
+``V4L2_CID_RDS_TX_MUSIC_SPEECH (boolean)``
+ If set, then this channel broadcasts music. If cleared, then it
+ broadcasts speech. If the transmitter doesn't make this distinction,
+ then it should be set.
+
+``V4L2_CID_RDS_TX_ALT_FREQS_ENABLE (boolean)``
+ If set, then transmit alternate frequencies.
+
+``V4L2_CID_RDS_TX_ALT_FREQS (__u32 array)``
+ The alternate frequencies in kHz units. The RDS standard allows for
+ up to 25 frequencies to be defined. Drivers may support fewer
+ frequencies so check the array size.
+
+``V4L2_CID_AUDIO_LIMITER_ENABLED (boolean)``
+ Enables or disables the audio deviation limiter feature. The limiter
+ is useful when trying to maximize the audio volume, minimize
+ receiver-generated distortion and prevent overmodulation.
+
+``V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (integer)``
+ Sets the audio deviation limiter feature release time. Unit is in
+ useconds. Step and range are driver-specific.
+
+``V4L2_CID_AUDIO_LIMITER_DEVIATION (integer)``
+ Configures audio frequency deviation level in Hz. The range and step
+ are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_ENABLED (boolean)``
+ Enables or disables the audio compression feature. This feature
+ amplifies signals below the threshold by a fixed gain and compresses
+ audio signals above the threshold by the ratio of Threshold/(Gain +
+ Threshold).
+
+``V4L2_CID_AUDIO_COMPRESSION_GAIN (integer)``
+ Sets the gain for audio compression feature. It is a dB value. The
+ range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (integer)``
+ Sets the threshold level for audio compression freature. It is a dB
+ value. The range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (integer)``
+ Sets the attack time for audio compression feature. It is a useconds
+ value. The range and step are driver-specific.
+
+``V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (integer)``
+ Sets the release time for audio compression feature. It is a
+ useconds value. The range and step are driver-specific.
+
+``V4L2_CID_PILOT_TONE_ENABLED (boolean)``
+ Enables or disables the pilot tone generation feature.
+
+``V4L2_CID_PILOT_TONE_DEVIATION (integer)``
+ Configures pilot tone frequency deviation level. Unit is in Hz. The
+ range and step are driver-specific.
+
+``V4L2_CID_PILOT_TONE_FREQUENCY (integer)``
+ Configures pilot tone frequency value. Unit is in Hz. The range and
+ step are driver-specific.
+
+``V4L2_CID_TUNE_PREEMPHASIS (enum v4l2_preemphasis)``
+ Configures the pre-emphasis value for broadcasting. A pre-emphasis
+ filter is applied to the broadcast to accentuate the high audio
+ frequencies. Depending on the region, a time constant of either 50
+ or 75 useconds is used. The enum v4l2_preemphasis defines possible
+ values for pre-emphasis. Here they are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_PREEMPHASIS_DISABLED``
+
+ - No pre-emphasis is applied.
+
+ - .. row 2
+
+ - ``V4L2_PREEMPHASIS_50_uS``
+
+ - A pre-emphasis of 50 uS is used.
+
+ - .. row 3
+
+ - ``V4L2_PREEMPHASIS_75_uS``
+
+ - A pre-emphasis of 75 uS is used.
+
+
+
+``V4L2_CID_TUNE_POWER_LEVEL (integer)``
+ Sets the output power level for signal transmission. Unit is in
+ dBuV. Range and step are driver-specific.
+
+``V4L2_CID_TUNE_ANTENNA_CAPACITOR (integer)``
+ This selects the value of antenna tuning capacitor manually or
+ automatically if set to zero. Unit, range and step are
+ driver-specific.
+
+For more details about RDS specification, refer to :ref:`iec62106`
+document, from CENELEC.
+
+
+.. _flash-controls:
+
+Flash Control Reference
+=======================
+
+The V4L2 flash controls are intended to provide generic access to flash
+controller devices. Flash controller devices are typically used in
+digital cameras.
+
+The interface can support both LED and xenon flash devices. As of
+writing this, there is no xenon flash driver using this interface.
+
+
+.. _flash-controls-use-cases:
+
+Supported use cases
+-------------------
+
+
+Unsynchronised LED flash (software strobe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unsynchronised LED flash is controlled directly by the host as the
+sensor. The flash must be enabled by the host before the exposure of the
+image starts and disabled once it ends. The host is fully responsible
+for the timing of the flash.
+
+Example of such device: Nokia N900.
+
+
+Synchronised LED flash (hardware strobe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The synchronised LED flash is pre-programmed by the host (power and
+timeout) but controlled by the sensor through a strobe signal from the
+sensor to the flash.
+
+The sensor controls the flash duration and timing. This information
+typically must be made available to the sensor.
+
+
+LED flash as torch
+^^^^^^^^^^^^^^^^^^
+
+LED flash may be used as torch in conjunction with another use case
+involving camera or individually.
+
+
+.. _flash-control-id:
+
+Flash Control IDs
+"""""""""""""""""
+
+``V4L2_CID_FLASH_CLASS (class)``
+ The FLASH class descriptor.
+
+``V4L2_CID_FLASH_LED_MODE (menu)``
+ Defines the mode of the flash LED, the high-power white LED attached
+ to the flash controller. Setting this control may not be possible in
+ presence of some faults. See V4L2_CID_FLASH_FAULT.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_LED_MODE_NONE``
+
+ - Off.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_LED_MODE_FLASH``
+
+ - Flash mode.
+
+ - .. row 3
+
+ - ``V4L2_FLASH_LED_MODE_TORCH``
+
+ - Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.
+
+
+
+``V4L2_CID_FLASH_STROBE_SOURCE (menu)``
+ Defines the source of the flash LED strobe.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_STROBE_SOURCE_SOFTWARE``
+
+ - The flash strobe is triggered by using the
+ V4L2_CID_FLASH_STROBE control.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_STROBE_SOURCE_EXTERNAL``
+
+ - The flash strobe is triggered by an external source. Typically
+ this is a sensor, which makes it possible to synchronises the
+ flash strobe start to exposure start.
+
+
+
+``V4L2_CID_FLASH_STROBE (button)``
+ Strobe flash. Valid when V4L2_CID_FLASH_LED_MODE is set to
+ V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE
+ is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this
+ control may not be possible in presence of some faults. See
+ V4L2_CID_FLASH_FAULT.
+
+``V4L2_CID_FLASH_STROBE_STOP (button)``
+ Stop flash strobe immediately.
+
+``V4L2_CID_FLASH_STROBE_STATUS (boolean)``
+ Strobe status: whether the flash is strobing at the moment or not.
+ This is a read-only control.
+
+``V4L2_CID_FLASH_TIMEOUT (integer)``
+ Hardware timeout for flash. The flash strobe is stopped after this
+ period of time has passed from the start of the strobe.
+
+``V4L2_CID_FLASH_INTENSITY (integer)``
+ Intensity of the flash strobe when the flash LED is in flash mode
+ (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps (mA)
+ if possible.
+
+``V4L2_CID_FLASH_TORCH_INTENSITY (integer)``
+ Intensity of the flash LED in torch mode
+ (V4L2_FLASH_LED_MODE_TORCH). The unit should be milliamps (mA)
+ if possible. Setting this control may not be possible in presence of
+ some faults. See V4L2_CID_FLASH_FAULT.
+
+``V4L2_CID_FLASH_INDICATOR_INTENSITY (integer)``
+ Intensity of the indicator LED. The indicator LED may be fully
+ independent of the flash LED. The unit should be microamps (uA) if
+ possible.
+
+``V4L2_CID_FLASH_FAULT (bitmask)``
+ Faults related to the flash. The faults tell about specific problems
+ in the flash chip itself or the LEDs attached to it. Faults may
+ prevent further use of some of the flash controls. In particular,
+ V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE
+ if the fault affects the flash LED. Exactly which faults have such
+ an effect is chip dependent. Reading the faults resets the control
+ and returns the chip to a usable state if possible.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_FLASH_FAULT_OVER_VOLTAGE``
+
+ - Flash controller voltage to the flash LED has exceeded the limit
+ specific to the flash controller.
+
+ - .. row 2
+
+ - ``V4L2_FLASH_FAULT_TIMEOUT``
+
+ - The flash strobe was still on when the timeout set by the user ---
+ V4L2_CID_FLASH_TIMEOUT control --- has expired. Not all flash
+ controllers may set this in all such conditions.
+
+ - .. row 3
+
+ - ``V4L2_FLASH_FAULT_OVER_TEMPERATURE``
+
+ - The flash controller has overheated.
+
+ - .. row 4
+
+ - ``V4L2_FLASH_FAULT_SHORT_CIRCUIT``
+
+ - The short circuit protection of the flash controller has been
+ triggered.
+
+ - .. row 5
+
+ - ``V4L2_FLASH_FAULT_OVER_CURRENT``
+
+ - Current in the LED power supply has exceeded the limit specific to
+ the flash controller.
+
+ - .. row 6
+
+ - ``V4L2_FLASH_FAULT_INDICATOR``
+
+ - The flash controller has detected a short or open circuit
+ condition on the indicator LED.
+
+ - .. row 7
+
+ - ``V4L2_FLASH_FAULT_UNDER_VOLTAGE``
+
+ - Flash controller voltage to the flash LED has been below the
+ minimum limit specific to the flash controller.
+
+ - .. row 8
+
+ - ``V4L2_FLASH_FAULT_INPUT_VOLTAGE``
+
+ - The input voltage of the flash controller is below the limit under
+ which strobing the flash at full current will not be possible.The
+ condition persists until this flag is no longer set.
+
+ - .. row 9
+
+ - ``V4L2_FLASH_FAULT_LED_OVER_TEMPERATURE``
+
+ - The temperature of the LED has exceeded its allowed upper limit.
+
+
+
+``V4L2_CID_FLASH_CHARGE (boolean)``
+ Enable or disable charging of the xenon flash capacitor.
+
+``V4L2_CID_FLASH_READY (boolean)``
+ Is the flash ready to strobe? Xenon flashes require their capacitors
+ charged before strobing. LED flashes often require a cooldown period
+ after strobe during which another strobe will not be possible. This
+ is a read-only control.
+
+
+.. _jpeg-controls:
+
+JPEG Control Reference
+======================
+
+The JPEG class includes controls for common features of JPEG encoders
+and decoders. Currently it includes features for codecs implementing
+progressive baseline DCT compression process with Huffman entrophy
+coding.
+
+
+.. _jpeg-control-id:
+
+JPEG Control IDs
+----------------
+
+``V4L2_CID_JPEG_CLASS (class)``
+ The JPEG class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_JPEG_CHROMA_SUBSAMPLING (menu)``
+ The chroma subsampling factors describe how each component of an
+ input image is sampled, in respect to maximum sample rate in each
+ spatial dimension. See :ref:`itu-t81`, clause A.1.1. for more
+ details. The ``V4L2_CID_JPEG_CHROMA_SUBSAMPLING`` control determines
+ how Cb and Cr components are downsampled after coverting an input
+ image from RGB to Y'CbCr color space.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_444``
+
+ - No chroma subsampling, each pixel has Y, Cr and Cb values.
+
+ - .. row 2
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_422``
+
+ - Horizontally subsample Cr, Cb components by a factor of 2.
+
+ - .. row 3
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_420``
+
+ - Subsample Cr, Cb components horizontally and vertically by 2.
+
+ - .. row 4
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_411``
+
+ - Horizontally subsample Cr, Cb components by a factor of 4.
+
+ - .. row 5
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_410``
+
+ - Subsample Cr, Cb components horizontally by 4 and vertically by 2.
+
+ - .. row 6
+
+ - ``V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY``
+
+ - Use only luminance component.
+
+
+
+``V4L2_CID_JPEG_RESTART_INTERVAL (integer)``
+ The restart interval determines an interval of inserting RSTm
+ markers (m = 0..7). The purpose of these markers is to additionally
+ reinitialize the encoder process, in order to process blocks of an
+ image independently. For the lossy compression processes the restart
+ interval unit is MCU (Minimum Coded Unit) and its value is contained
+ in DRI (Define Restart Interval) marker. If
+ ``V4L2_CID_JPEG_RESTART_INTERVAL`` control is set to 0, DRI and RSTm
+ markers will not be inserted.
+
+.. _jpeg-quality-control:
+
+``V4L2_CID_JPEG_COMPRESSION_QUALITY (integer)``
+ ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control determines trade-off
+ between image quality and size. It provides simpler method for
+ applications to control image quality, without a need for direct
+ reconfiguration of luminance and chrominance quantization tables. In
+ cases where a driver uses quantization tables configured directly by
+ an application, using interfaces defined elsewhere,
+ ``V4L2_CID_JPEG_COMPRESSION_QUALITY`` control should be set by
+ driver to 0.
+
+ The value range of this control is driver-specific. Only positive,
+ non-zero values are meaningful. The recommended range is 1 - 100,
+ where larger values correspond to better image quality.
+
+.. _jpeg-active-marker-control:
+
+``V4L2_CID_JPEG_ACTIVE_MARKER (bitmask)``
+ Specify which JPEG markers are included in compressed stream. This
+ control is valid only for encoders.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_APP0``
+
+ - Application data segment APP\ :sub:`0`.
+
+ - .. row 2
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_APP1``
+
+ - Application data segment APP\ :sub:`1`.
+
+ - .. row 3
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_COM``
+
+ - Comment segment.
+
+ - .. row 4
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_DQT``
+
+ - Quantization tables segment.
+
+ - .. row 5
+
+ - ``V4L2_JPEG_ACTIVE_MARKER_DHT``
+
+ - Huffman tables segment.
+
+
+
+For more details about JPEG specification, refer to :ref:`itu-t81`,
+:ref:`jfif`, :ref:`w3c-jpeg-jfif`.
+
+
+.. _image-source-controls:
+
+Image Source Control Reference
+==============================
+
+The Image Source control class is intended for low-level control of
+image source devices such as image sensors. The devices feature an
+analogue to digital converter and a bus transmitter to transmit the
+image data out of the device.
+
+
+.. _image-source-control-id:
+
+Image Source Control IDs
+------------------------
+
+``V4L2_CID_IMAGE_SOURCE_CLASS (class)``
+ The IMAGE_SOURCE class descriptor.
+
+``V4L2_CID_VBLANK (integer)``
+ Vertical blanking. The idle period after every frame during which no
+ image data is produced. The unit of vertical blanking is a line.
+ Every line has length of the image width plus horizontal blanking at
+ the pixel rate defined by ``V4L2_CID_PIXEL_RATE`` control in the
+ same sub-device.
+
+``V4L2_CID_HBLANK (integer)``
+ Horizontal blanking. The idle period after every line of image data
+ during which no image data is produced. The unit of horizontal
+ blanking is pixels.
+
+``V4L2_CID_ANALOGUE_GAIN (integer)``
+ Analogue gain is gain affecting all colour components in the pixel
+ matrix. The gain operation is performed in the analogue domain
+ before A/D conversion.
+
+``V4L2_CID_TEST_PATTERN_RED (integer)``
+ Test pattern red colour component.
+
+``V4L2_CID_TEST_PATTERN_GREENR (integer)``
+ Test pattern green (next to red) colour component.
+
+``V4L2_CID_TEST_PATTERN_BLUE (integer)``
+ Test pattern blue colour component.
+
+``V4L2_CID_TEST_PATTERN_GREENB (integer)``
+ Test pattern green (next to blue) colour component.
+
+
+.. _image-process-controls:
+
+Image Process Control Reference
+===============================
+
+The Image Process control class is intended for low-level control of
+image processing functions. Unlike ``V4L2_CID_IMAGE_SOURCE_CLASS``, the
+controls in this class affect processing the image, and do not control
+capturing of it.
+
+
+.. _image-process-control-id:
+
+Image Process Control IDs
+-------------------------
+
+``V4L2_CID_IMAGE_PROC_CLASS (class)``
+ The IMAGE_PROC class descriptor.
+
+``V4L2_CID_LINK_FREQ (integer menu)``
+ Data bus frequency. Together with the media bus pixel code, bus type
+ (clock cycles per sample), the data bus frequency defines the pixel
+ rate (``V4L2_CID_PIXEL_RATE``) in the pixel array (or possibly
+ elsewhere, if the device is not an image sensor). The frame rate can
+ be calculated from the pixel clock, image width and height and
+ horizontal and vertical blanking. While the pixel rate control may
+ be defined elsewhere than in the subdev containing the pixel array,
+ the frame rate cannot be obtained from that information. This is
+ because only on the pixel array it can be assumed that the vertical
+ and horizontal blanking information is exact: no other blanking is
+ allowed in the pixel array. The selection of frame rate is performed
+ by selecting the desired horizontal and vertical blanking. The unit
+ of this control is Hz.
+
+``V4L2_CID_PIXEL_RATE (64-bit integer)``
+ Pixel rate in the source pads of the subdev. This control is
+ read-only and its unit is pixels / second.
+
+``V4L2_CID_TEST_PATTERN (menu)``
+ Some capture/display/sensor devices have the capability to generate
+ test pattern images. These hardware specific test patterns can be
+ used to test if a device is working properly.
+
+
+.. _dv-controls:
+
+Digital Video Control Reference
+===============================
+
+The Digital Video control class is intended to control receivers and
+transmitters for `VGA <http://en.wikipedia.org/wiki/Vga>`__,
+`DVI <http://en.wikipedia.org/wiki/Digital_Visual_Interface>`__
+(Digital Visual Interface), HDMI (:ref:`hdmi`) and DisplayPort
+(:ref:`dp`). These controls are generally expected to be private to
+the receiver or transmitter subdevice that implements them, so they are
+only exposed on the ``/dev/v4l-subdev*`` device node.
+
+Note that these devices can have multiple input or output pads which are
+hooked up to e.g. HDMI connectors. Even though the subdevice will
+receive or transmit video from/to only one of those pads, the other pads
+can still be active when it comes to EDID (Extended Display
+Identification Data, :ref:`vesaedid`) and HDCP (High-bandwidth Digital
+Content Protection System, :ref:`hdcp`) processing, allowing the
+device to do the fairly slow EDID/HDCP handling in advance. This allows
+for quick switching between connectors.
+
+These pads appear in several of the controls in this section as
+bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad
+1, etc. The maximum value of the control is the set of valid pads.
+
+
+.. _dv-control-id:
+
+Digital Video Control IDs
+-------------------------
+
+``V4L2_CID_DV_CLASS (class)``
+ The Digital Video class descriptor.
+
+``V4L2_CID_DV_TX_HOTPLUG (bitmask)``
+ Many connectors have a hotplug pin which is high if EDID information
+ is available from the source. This control shows the state of the
+ hotplug pin as seen by the transmitter. Each bit corresponds to an
+ output pad on the transmitter. If an output pad does not have an
+ associated hotplug pin, then the bit for that pad will be 0. This
+ read-only control is applicable to DVI-D, HDMI and DisplayPort
+ connectors.
+
+``V4L2_CID_DV_TX_RXSENSE (bitmask)``
+ Rx Sense is the detection of pull-ups on the TMDS clock lines. This
+ normally means that the sink has left/entered standby (i.e. the
+ transmitter can sense that the receiver is ready to receive video).
+ Each bit corresponds to an output pad on the transmitter. If an
+ output pad does not have an associated Rx Sense, then the bit for
+ that pad will be 0. This read-only control is applicable to DVI-D
+ and HDMI devices.
+
+``V4L2_CID_DV_TX_EDID_PRESENT (bitmask)``
+ When the transmitter sees the hotplug signal from the receiver it
+ will attempt to read the EDID. If set, then the transmitter has read
+ at least the first block (= 128 bytes). Each bit corresponds to an
+ output pad on the transmitter. If an output pad does not support
+ EDIDs, then the bit for that pad will be 0. This read-only control
+ is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_TX_MODE (enum v4l2_dv_tx_mode)``
+ HDMI transmitters can transmit in DVI-D mode (just video) or in HDMI
+ mode (video + audio + auxiliary data). This control selects which
+ mode to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI.
+ This control is applicable to HDMI connectors.
+
+``V4L2_CID_DV_TX_RGB_RANGE (enum v4l2_dv_rgb_range)``
+ Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO
+ follows the RGB quantization range specified in the standard for the
+ video interface (ie. :ref:`cea861` for HDMI).
+ V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
+ standard to be compatible with sinks that have not implemented the
+ standard correctly (unfortunately quite common for HDMI and DVI-D).
+ Full range allows all possible values to be used whereas limited
+ range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
+ the number of bits per component. This control is applicable to VGA,
+ DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_TX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
+ Configures the IT Content Type of the transmitted video. This
+ information is sent over HDMI and DisplayPort connectors as part of
+ the AVI InfoFrame. The term 'IT Content' is used for content that
+ originates from a computer as opposed to content from a TV broadcast
+ or an analog source. The enum v4l2_dv_it_content_type defines
+ the possible content types:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_GRAPHICS``
+
+ - Graphics content. Pixel data should be passed unfiltered and
+ without analog reconstruction.
+
+ - .. row 2
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_PHOTO``
+
+ - Photo content. The content is derived from digital still pictures.
+ The content should be passed through with minimal scaling and
+ picture enhancements.
+
+ - .. row 3
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_CINEMA``
+
+ - Cinema content.
+
+ - .. row 4
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_GAME``
+
+ - Game content. Audio and video latency should be minimized.
+
+ - .. row 5
+
+ - ``V4L2_DV_IT_CONTENT_TYPE_NO_ITC``
+
+ - No IT Content information is available and the ITC bit in the AVI
+ InfoFrame is set to 0.
+
+
+
+``V4L2_CID_DV_RX_POWER_PRESENT (bitmask)``
+ Detects whether the receiver receives power from the source (e.g.
+ HDMI carries 5V on one of the pins). This is often used to power an
+ eeprom which contains EDID information, such that the source can
+ read the EDID even if the sink is in standby/power off. Each bit
+ corresponds to an input pad on the transmitter. If an input pad
+ cannot detect whether power is present, then the bit for that pad
+ will be 0. This read-only control is applicable to DVI-D, HDMI and
+ DisplayPort connectors.
+
+``V4L2_CID_DV_RX_RGB_RANGE (enum v4l2_dv_rgb_range)``
+ Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO
+ follows the RGB quantization range specified in the standard for the
+ video interface (ie. :ref:`cea861` for HDMI).
+ V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the
+ standard to be compatible with sources that have not implemented the
+ standard correctly (unfortunately quite common for HDMI and DVI-D).
+ Full range allows all possible values to be used whereas limited
+ range sets the range to (16 << (N-8)) - (235 << (N-8)) where N is
+ the number of bits per component. This control is applicable to VGA,
+ DVI-A/D, HDMI and DisplayPort connectors.
+
+``V4L2_CID_DV_RX_IT_CONTENT_TYPE (enum v4l2_dv_it_content_type)``
+ Reads the IT Content Type of the received video. This information is
+ sent over HDMI and DisplayPort connectors as part of the AVI
+ InfoFrame. The term 'IT Content' is used for content that originates
+ from a computer as opposed to content from a TV broadcast or an
+ analog source. See ``V4L2_CID_DV_TX_IT_CONTENT_TYPE`` for the
+ available content types.
+
+
+.. _fm-rx-controls:
+
+FM Receiver Control Reference
+=============================
+
+The FM Receiver (FM_RX) class includes controls for common features of
+FM Reception capable devices.
+
+
+.. _fm-rx-control-id:
+
+FM_RX Control IDs
+-----------------
+
+``V4L2_CID_FM_RX_CLASS (class)``
+ The FM_RX class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RDS_RECEPTION (boolean)``
+ Enables/disables RDS reception by the radio tuner
+
+``V4L2_CID_RDS_RX_PTY (integer)``
+ Gets RDS Programme Type field. This encodes up to 31 pre-defined
+ programme types.
+
+``V4L2_CID_RDS_RX_PS_NAME (string)``
+ Gets the Programme Service name (PS_NAME). It is intended for
+ static display on a receiver. It is the primary aid to listeners in
+ programme service identification and selection. In Annex E of
+ :ref:`iec62106`, the RDS specification, there is a full
+ description of the correct character encoding for Programme Service
+ name strings. Also from RDS specification, PS is usually a single
+ eight character text. However, it is also possible to find receivers
+ which can scroll strings sized as 8 x N characters. So, this control
+ must be configured with steps of 8 characters. The result is it must
+ always contain a string with size multiple of 8.
+
+``V4L2_CID_RDS_RX_RADIO_TEXT (string)``
+ Gets the Radio Text info. It is a textual description of what is
+ being broadcasted. RDS Radio Text can be applied when broadcaster
+ wishes to transmit longer PS names, programme-related information or
+ any other text. In these cases, RadioText can be used in addition to
+ ``V4L2_CID_RDS_RX_PS_NAME``. The encoding for Radio Text strings is
+ also fully described in Annex E of :ref:`iec62106`. The length of
+ Radio Text strings depends on which RDS Block is being used to
+ transmit it, either 32 (2A block) or 64 (2B block). However, it is
+ also possible to find receivers which can scroll strings sized as 32
+ x N or 64 x N characters. So, this control must be configured with
+ steps of 32 or 64 characters. The result is it must always contain a
+ string with size multiple of 32 or 64.
+
+``V4L2_CID_RDS_RX_TRAFFIC_ANNOUNCEMENT (boolean)``
+ If set, then a traffic announcement is in progress.
+
+``V4L2_CID_RDS_RX_TRAFFIC_PROGRAM (boolean)``
+ If set, then the tuned programme carries traffic announcements.
+
+``V4L2_CID_RDS_RX_MUSIC_SPEECH (boolean)``
+ If set, then this channel broadcasts music. If cleared, then it
+ broadcasts speech. If the transmitter doesn't make this distinction,
+ then it will be set.
+
+``V4L2_CID_TUNE_DEEMPHASIS (enum v4l2_deemphasis)``
+ Configures the de-emphasis value for reception. A de-emphasis filter
+ is applied to the broadcast to accentuate the high audio
+ frequencies. Depending on the region, a time constant of either 50
+ or 75 useconds is used. The enum v4l2_deemphasis defines possible
+ values for de-emphasis. Here they are:
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DEEMPHASIS_DISABLED``
+
+ - No de-emphasis is applied.
+
+ - .. row 2
+
+ - ``V4L2_DEEMPHASIS_50_uS``
+
+ - A de-emphasis of 50 uS is used.
+
+ - .. row 3
+
+ - ``V4L2_DEEMPHASIS_75_uS``
+
+ - A de-emphasis of 75 uS is used.
+
+
+
+
+.. _detect-controls:
+
+Detect Control Reference
+========================
+
+The Detect class includes controls for common features of various motion
+or object detection capable devices.
+
+
+.. _detect-control-id:
+
+Detect Control IDs
+------------------
+
+``V4L2_CID_DETECT_CLASS (class)``
+ The Detect class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_DETECT_MD_MODE (menu)``
+ Sets the motion detection mode.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - ``V4L2_DETECT_MD_MODE_DISABLED``
+
+ - Disable motion detection.
+
+ - .. row 2
+
+ - ``V4L2_DETECT_MD_MODE_GLOBAL``
+
+ - Use a single motion detection threshold.
+
+ - .. row 3
+
+ - ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID``
+
+ - The image is divided into a grid, each cell with its own motion
+ detection threshold. These thresholds are set through the
+ ``V4L2_CID_DETECT_MD_THRESHOLD_GRID`` matrix control.
+
+ - .. row 4
+
+ - ``V4L2_DETECT_MD_MODE_REGION_GRID``
+
+ - The image is divided into a grid, each cell with its own region
+ value that specifies which per-region motion detection thresholds
+ should be used. Each region has its own thresholds. How these
+ per-region thresholds are set up is driver-specific. The region
+ values for the grid are set through the
+ ``V4L2_CID_DETECT_MD_REGION_GRID`` matrix control.
+
+
+
+``V4L2_CID_DETECT_MD_GLOBAL_THRESHOLD (integer)``
+ Sets the global motion detection threshold to be used with the
+ ``V4L2_DETECT_MD_MODE_GLOBAL`` motion detection mode.
+
+``V4L2_CID_DETECT_MD_THRESHOLD_GRID (__u16 matrix)``
+ Sets the motion detection thresholds for each cell in the grid. To
+ be used with the ``V4L2_DETECT_MD_MODE_THRESHOLD_GRID`` motion
+ detection mode. Matrix element (0, 0) represents the cell at the
+ top-left of the grid.
+
+``V4L2_CID_DETECT_MD_REGION_GRID (__u8 matrix)``
+ Sets the motion detection region value for each cell in the grid. To
+ be used with the ``V4L2_DETECT_MD_MODE_REGION_GRID`` motion
+ detection mode. Matrix element (0, 0) represents the cell at the
+ top-left of the grid.
+
+
+.. _rf-tuner-controls:
+
+RF Tuner Control Reference
+==========================
+
+The RF Tuner (RF_TUNER) class includes controls for common features of
+devices having RF tuner.
+
+In this context, RF tuner is radio receiver circuit between antenna and
+demodulator. It receives radio frequency (RF) from the antenna and
+converts that received signal to lower intermediate frequency (IF) or
+baseband frequency (BB). Tuners that could do baseband output are often
+called Zero-IF tuners. Older tuners were typically simple PLL tuners
+inside a metal box, whilst newer ones are highly integrated chips
+without a metal box "silicon tuners". These controls are mostly
+applicable for new feature rich silicon tuners, just because older
+tuners does not have much adjustable features.
+
+For more information about RF tuners see
+`Tuner (radio) <http://en.wikipedia.org/wiki/Tuner_%28radio%29>`__
+and `RF front end <http://en.wikipedia.org/wiki/RF_front_end>`__
+from Wikipedia.
+
+
+.. _rf-tuner-control-id:
+
+RF_TUNER Control IDs
+--------------------
+
+``V4L2_CID_RF_TUNER_CLASS (class)``
+ The RF_TUNER class descriptor. Calling
+ :ref:`VIDIOC_QUERYCTRL` for this control will
+ return a description of this control class.
+
+``V4L2_CID_RF_TUNER_BANDWIDTH_AUTO (boolean)``
+ Enables/disables tuner radio channel bandwidth configuration. In
+ automatic mode bandwidth configuration is performed by the driver.
+
+``V4L2_CID_RF_TUNER_BANDWIDTH (integer)``
+ Filter(s) on tuner signal path are used to filter signal according
+ to receiving party needs. Driver configures filters to fulfill
+ desired bandwidth requirement. Used when
+ V4L2_CID_RF_TUNER_BANDWIDTH_AUTO is not set. Unit is in Hz. The
+ range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO (boolean)``
+ Enables/disables LNA automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO (boolean)``
+ Enables/disables mixer automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_IF_GAIN_AUTO (boolean)``
+ Enables/disables IF automatic gain control (AGC)
+
+``V4L2_CID_RF_TUNER_RF_GAIN (integer)``
+ The RF amplifier is the very first amplifier on the receiver signal
+ path, just right after the antenna input. The difference between the
+ LNA gain and the RF gain in this document is that the LNA gain is
+ integrated in the tuner chip while the RF gain is a separate chip.
+ There may be both RF and LNA gain controls in the same device. The
+ range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_LNA_GAIN (integer)``
+ LNA (low noise amplifier) gain is first gain stage on the RF tuner
+ signal path. It is located very close to tuner antenna input. Used
+ when ``V4L2_CID_RF_TUNER_LNA_GAIN_AUTO`` is not set. See
+ ``V4L2_CID_RF_TUNER_RF_GAIN`` to understand how RF gain and LNA gain
+ differs from the each others. The range and step are
+ driver-specific.
+
+``V4L2_CID_RF_TUNER_MIXER_GAIN (integer)``
+ Mixer gain is second gain stage on the RF tuner signal path. It is
+ located inside mixer block, where RF signal is down-converted by the
+ mixer. Used when ``V4L2_CID_RF_TUNER_MIXER_GAIN_AUTO`` is not set.
+ The range and step are driver-specific.
+
+``V4L2_CID_RF_TUNER_IF_GAIN (integer)``
+ IF gain is last gain stage on the RF tuner signal path. It is
+ located on output of RF tuner. It controls signal level of
+ intermediate frequency output or baseband output. Used when
+ ``V4L2_CID_RF_TUNER_IF_GAIN_AUTO`` is not set. The range and step
+ are driver-specific.
+
+``V4L2_CID_RF_TUNER_PLL_LOCK (boolean)``
+ Is synthesizer PLL locked? RF tuner is receiving given frequency
+ when that control is set. This is a read-only control.
+
+.. [1]
+ This control may be changed to a menu control in the future, if more
+ options are required.
diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst
new file mode 100644
index 000000000000..979fedbb2bda
--- /dev/null
+++ b/Documentation/media/uapi/v4l/field-order.rst
@@ -0,0 +1,205 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _field-order:
+
+***********
+Field Order
+***********
+
+We have to distinguish between progressive and interlaced video.
+Progressive video transmits all lines of a video image sequentially.
+Interlaced video divides an image into two fields, containing only the
+odd and even lines of the image, respectively. Alternating the so called
+odd and even field are transmitted, and due to a small delay between
+fields a cathode ray TV displays the lines interleaved, yielding the
+original frame. This curious technique was invented because at refresh
+rates similar to film the image would fade out too quickly. Transmitting
+fields reduces the flicker without the necessity of doubling the frame
+rate and with it the bandwidth required for each channel.
+
+It is important to understand a video camera does not expose one frame
+at a time, merely transmitting the frames separated into fields. The
+fields are in fact captured at two different instances in time. An
+object on screen may well move between one field and the next. For
+applications analysing motion it is of paramount importance to recognize
+which field of a frame is older, the *temporal order*.
+
+When the driver provides or accepts images field by field rather than
+interleaved, it is also important applications understand how the fields
+combine to frames. We distinguish between top (aka odd) and bottom (aka
+even) fields, the *spatial order*: The first line of the top field is
+the first line of an interlaced frame, the first line of the bottom
+field is the second line of that frame.
+
+However because fields were captured one after the other, arguing
+whether a frame commences with the top or bottom field is pointless. Any
+two successive top and bottom, or bottom and top fields yield a valid
+frame. Only when the source was progressive to begin with, e. g. when
+transferring film to video, two fields may come from the same frame,
+creating a natural order.
+
+Counter to intuition the top field is not necessarily the older field.
+Whether the older field contains the top or bottom lines is a convention
+determined by the video standard. Hence the distinction between temporal
+and spatial order of fields. The diagrams below should make this
+clearer.
+
+All video capture and output devices must report the current field
+order. Some drivers may permit the selection of a different order, to
+this end applications initialize the ``field`` field of struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` before calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. If this is not desired it
+should have the value ``V4L2_FIELD_ANY`` (0).
+
+
+.. _v4l2-field:
+
+enum v4l2_field
+===============
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FIELD_ANY``
+
+ - 0
+
+ - Applications request this field order when any one of the
+ ``V4L2_FIELD_NONE``, ``V4L2_FIELD_TOP``, ``V4L2_FIELD_BOTTOM``, or
+ ``V4L2_FIELD_INTERLACED`` formats is acceptable. Drivers choose
+ depending on hardware capabilities or e. g. the requested image
+ size, and return the actual field order. Drivers must never return
+ ``V4L2_FIELD_ANY``. If multiple field orders are possible the
+ driver must choose one of the possible field orders during
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
+ :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`. struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``field`` can never be
+ ``V4L2_FIELD_ANY``.
+
+ - .. row 2
+
+ - ``V4L2_FIELD_NONE``
+
+ - 1
+
+ - Images are in progressive format, not interlaced. The driver may
+ also indicate this order when it cannot distinguish between
+ ``V4L2_FIELD_TOP`` and ``V4L2_FIELD_BOTTOM``.
+
+ - .. row 3
+
+ - ``V4L2_FIELD_TOP``
+
+ - 2
+
+ - Images consist of the top (aka odd) field only.
+
+ - .. row 4
+
+ - ``V4L2_FIELD_BOTTOM``
+
+ - 3
+
+ - Images consist of the bottom (aka even) field only. Applications
+ may wish to prevent a device from capturing interlaced images
+ because they will have "comb" or "feathering" artefacts around
+ moving objects.
+
+ - .. row 5
+
+ - ``V4L2_FIELD_INTERLACED``
+
+ - 4
+
+ - Images contain both fields, interleaved line by line. The temporal
+ order of the fields (whether the top or bottom field is first
+ transmitted) depends on the current video standard. M/NTSC
+ transmits the bottom field first, all other standards the top
+ field first.
+
+ - .. row 6
+
+ - ``V4L2_FIELD_SEQ_TB``
+
+ - 5
+
+ - Images contain both fields, the top field lines are stored first
+ in memory, immediately followed by the bottom field lines. Fields
+ are always stored in temporal order, the older one first in
+ memory. Image sizes refer to the frame, not fields.
+
+ - .. row 7
+
+ - ``V4L2_FIELD_SEQ_BT``
+
+ - 6
+
+ - Images contain both fields, the bottom field lines are stored
+ first in memory, immediately followed by the top field lines.
+ Fields are always stored in temporal order, the older one first in
+ memory. Image sizes refer to the frame, not fields.
+
+ - .. row 8
+
+ - ``V4L2_FIELD_ALTERNATE``
+
+ - 7
+
+ - The two fields of a frame are passed in separate buffers, in
+ temporal order, i. e. the older one first. To indicate the field
+ parity (whether the current field is a top or bottom field) the
+ driver or application, depending on data direction, must set
+ struct :ref:`v4l2_buffer <v4l2-buffer>` ``field`` to
+ ``V4L2_FIELD_TOP`` or ``V4L2_FIELD_BOTTOM``. Any two successive
+ fields pair to build a frame. If fields are successive, without
+ any dropped fields between them (fields can drop individually),
+ can be determined from the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``sequence`` field. This
+ format cannot be selected when using the read/write I/O method
+ since there is no way to communicate if a field was a top or
+ bottom field.
+
+ - .. row 9
+
+ - ``V4L2_FIELD_INTERLACED_TB``
+
+ - 8
+
+ - Images contain both fields, interleaved line by line, top field
+ first. The top field is transmitted first.
+
+ - .. row 10
+
+ - ``V4L2_FIELD_INTERLACED_BT``
+
+ - 9
+
+ - Images contain both fields, interleaved line by line, top field
+ first. The bottom field is transmitted first.
+
+
+
+.. _fieldseq-tb:
+
+Field Order, Top Field First Transmitted
+========================================
+
+.. figure:: field-order_files/fieldseq_tb.*
+ :alt: fieldseq_tb.pdf / fieldseq_tb.gif
+ :align: center
+
+
+.. _fieldseq-bt:
+
+Field Order, Bottom Field First Transmitted
+===========================================
+
+.. figure:: field-order_files/fieldseq_bt.*
+ :alt: fieldseq_bt.pdf / fieldseq_bt.gif
+ :align: center
+
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif
new file mode 100644
index 000000000000..60e8569a76c9
--- /dev/null
+++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf
new file mode 100644
index 000000000000..26598b23f80d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif
new file mode 100644
index 000000000000..718492f1cfc7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf
new file mode 100644
index 000000000000..4965b22ddb3a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf
Binary files differ
diff --git a/Documentation/media/uapi/v4l/format.rst b/Documentation/media/uapi/v4l/format.rst
new file mode 100644
index 000000000000..a29dd9466b8f
--- /dev/null
+++ b/Documentation/media/uapi/v4l/format.rst
@@ -0,0 +1,92 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _format:
+
+************
+Data Formats
+************
+
+
+Data Format Negotiation
+=======================
+
+Different devices exchange different kinds of data with applications,
+for example video images, raw or sliced VBI data, RDS datagrams. Even
+within one kind many different formats are possible, in particular an
+abundance of image formats. Although drivers must provide a default and
+the selection persists across closing and reopening a device,
+applications should always negotiate a data format before engaging in
+data exchange. Negotiation means the application asks for a particular
+format and the driver selects and reports the best the hardware can do
+to satisfy the request. Of course applications can also just query the
+current selection.
+
+A single mechanism exists to negotiate all data formats using the
+aggregate struct :ref:`v4l2_format <v4l2-format>` and the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine
+what the hardware *could* do, without actually selecting a new data
+format. The data formats supported by the V4L2 API are covered in the
+respective device section in :ref:`devices`. For a closer look at
+image formats see :ref:`pixfmt`.
+
+The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl is a major turning-point in the
+initialization sequence. Prior to this point multiple panel applications
+can access the same device concurrently to select the current input,
+change controls or modify other properties. The first :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+assigns a logical stream (video data, VBI data etc.) exclusively to one
+file descriptor.
+
+Exclusive means no other application, more precisely no other file
+descriptor, can grab this stream or change device properties
+inconsistent with the negotiated parameters. A video standard change for
+example, when the new standard uses a different number of scan lines,
+can invalidate the selected image format. Therefore only the file
+descriptor owning the stream can make invalidating changes. Accordingly
+multiple file descriptors which grabbed different logical streams
+prevent each other from interfering with their settings. When for
+example video overlay is about to start or already in progress,
+simultaneous video capturing may be restricted to the same cropping and
+image size.
+
+When applications omit the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl its locking side
+effects are implied by the next step, the selection of an I/O method
+with the :ref:`VIDIOC_REQBUFS` ioctl or implicit
+with the first :ref:`read() <func-read>` or
+:ref:`write() <func-write>` call.
+
+Generally only one logical stream can be assigned to a file descriptor,
+the exception being drivers permitting simultaneous video capturing and
+overlay using the same file descriptor for compatibility with V4L and
+earlier versions of V4L2. Switching the logical stream or returning into
+"panel mode" is possible by closing and reopening the device. Drivers
+*may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
+
+All drivers exchanging data with applications must support the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional.
+
+
+Image Format Enumeration
+========================
+
+Apart of the generic format negotiation functions a special ioctl to
+enumerate all image formats supported by video capture, overlay or
+output devices is available. [1]_
+
+The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported
+by all drivers exchanging image data with applications.
+
+ **Important**
+
+ Drivers are not supposed to convert image formats in kernel space.
+ They must enumerate only formats directly supported by the hardware.
+ If necessary driver writers should publish an example conversion
+ routine or library for integration into applications.
+
+.. [1]
+ Enumerating formats an application has no a-priori knowledge of
+ (otherwise it could explicitly ask for them and need not enumerate)
+ seems useless, but there are applications serving as proxy between
+ drivers and the actual video applications for which this is useful.
diff --git a/Documentation/media/uapi/v4l/func-close.rst b/Documentation/media/uapi/v4l/func-close.rst
new file mode 100644
index 000000000000..926a2ccc32e5
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-close.rst
@@ -0,0 +1,49 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-close:
+
+************
+V4L2 close()
+************
+
+Name
+====
+
+v4l2-close - Close a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: int close( int fd )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+
+Description
+===========
+
+Closes the device. Any I/O in progress is terminated and resources
+associated with the file descriptor are freed. However data format
+parameters, current input or output, control values or other properties
+remain unchanged.
+
+
+Return Value
+============
+
+The function returns 0 on success, -1 on failure and the ``errno`` is
+set appropriately. Possible error codes:
+
+EBADF
+ ``fd`` is not a valid open file descriptor.
diff --git a/Documentation/media/uapi/v4l/func-ioctl.rst b/Documentation/media/uapi/v4l/func-ioctl.rst
new file mode 100644
index 000000000000..5632f48fce1b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-ioctl.rst
@@ -0,0 +1,62 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-ioctl:
+
+************
+V4L2 ioctl()
+************
+
+Name
+====
+
+v4l2-ioctl - Program a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/ioctl.h>
+
+
+.. cpp:function:: int ioctl( int fd, int request, void *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ V4L2 ioctl request code as defined in the ``videodev2.h`` header
+ file, for example VIDIOC_QUERYCAP.
+
+``argp``
+ Pointer to a function parameter, usually a structure.
+
+
+Description
+===========
+
+The :ref:`ioctl() <func-ioctl>` function is used to program V4L2 devices. The
+argument ``fd`` must be an open file descriptor. An ioctl ``request``
+has encoded in it whether the argument is an input, output or read/write
+parameter, and the size of the argument ``argp`` in bytes. Macros and
+defines specifying V4L2 ioctl requests are located in the
+``videodev2.h`` header file. Applications should use their own copy, not
+include the version in the kernel sources on the system they compile on.
+All V4L2 ioctl requests, their respective function and parameters are
+specified in :ref:`user-func`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+When an ioctl that takes an output or read/write parameter fails, the
+parameter remains unmodified.
diff --git a/Documentation/media/uapi/v4l/func-mmap.rst b/Documentation/media/uapi/v4l/func-mmap.rst
new file mode 100644
index 000000000000..3502c2afd894
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-mmap.rst
@@ -0,0 +1,134 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-mmap:
+
+***********
+V4L2 mmap()
+***********
+
+Name
+====
+
+v4l2-mmap - Map device memory into application address space
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+ #include <sys/mman.h>
+
+
+.. cpp:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset )
+
+
+Arguments
+=========
+
+``start``
+ Map the buffer to this address in the application's address space.
+ When the ``MAP_FIXED`` flag is specified, ``start`` must be a
+ multiple of the pagesize and mmap will fail when the specified
+ address cannot be used. Use of this option is discouraged;
+ applications should just specify a ``NULL`` pointer here.
+
+``length``
+ Length of the memory area to map. This must be the same value as
+ returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
+ single-planar API, and the same value as returned by the driver in
+ the struct :ref:`v4l2_plane <v4l2-plane>` ``length`` field for
+ the multi-planar API.
+
+``prot``
+ The ``prot`` argument describes the desired memory protection.
+ Regardless of the device type and the direction of data exchange it
+ should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read
+ and write access to image buffers. Drivers should support at least
+ this combination of flags. Note the Linux ``video-buf`` kernel
+ module, which is used by the bttv, saa7134, saa7146, cx88 and vivi
+ driver supports only ``PROT_READ`` | ``PROT_WRITE``. When the
+ driver does not support the desired protection the
+ :ref:`mmap() <func-mmap>` function fails.
+
+ Note device memory accesses (e. g. the memory on a graphics card
+ with video capturing hardware) may incur a performance penalty
+ compared to main memory accesses, or reads may be significantly
+ slower than writes or vice versa. Other I/O methods may be more
+ efficient in this case.
+
+``flags``
+ The ``flags`` parameter specifies the type of the mapped object,
+ mapping options and whether modifications made to the mapped copy of
+ the page are private to the process or are to be shared with other
+ references.
+
+ ``MAP_FIXED`` requests that the driver selects no other address than
+ the one specified. If the specified address cannot be used,
+ :ref:`mmap() <func-mmap>` will fail. If ``MAP_FIXED`` is specified,
+ ``start`` must be a multiple of the pagesize. Use of this option is
+ discouraged.
+
+ One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set.
+ ``MAP_SHARED`` allows applications to share the mapped memory with
+ other (e. g. child-) processes. Note the Linux ``video-buf`` module
+ which is used by the bttv, saa7134, saa7146, cx88 and vivi driver
+ supports only ``MAP_SHARED``. ``MAP_PRIVATE`` requests copy-on-write
+ semantics. V4L2 applications should not set the ``MAP_PRIVATE``,
+ ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` flag.
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``offset``
+ Offset of the buffer in device memory. This must be the same value
+ as returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``m`` union ``offset`` field for
+ the single-planar API, and the same value as returned by the driver
+ in the struct :ref:`v4l2_plane <v4l2-plane>` ``m`` union
+ ``mem_offset`` field for the multi-planar API.
+
+
+Description
+===========
+
+The :ref:`mmap() <func-mmap>` function asks to map ``length`` bytes starting at
+``offset`` in the memory of the device specified by ``fd`` into the
+application address space, preferably at address ``start``. This latter
+address is a hint only, and is usually specified as 0.
+
+Suitable length and offset parameters are queried with the
+:ref:`VIDIOC_QUERYBUF` ioctl. Buffers must be
+allocated with the :ref:`VIDIOC_REQBUFS` ioctl
+before they can be queried.
+
+To unmap buffers the :ref:`munmap() <func-munmap>` function is used.
+
+
+Return Value
+============
+
+On success :ref:`mmap() <func-mmap>` returns a pointer to the mapped buffer. On
+error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set
+appropriately. Possible error codes are:
+
+EBADF
+ ``fd`` is not a valid file descriptor.
+
+EACCES
+ ``fd`` is not open for reading and writing.
+
+EINVAL
+ The ``start`` or ``length`` or ``offset`` are not suitable. (E. g.
+ they are too large, or not aligned on a ``PAGESIZE`` boundary.)
+
+ The ``flags`` or ``prot`` value is not supported.
+
+ No buffers have been allocated with the
+ :ref:`VIDIOC_REQBUFS` ioctl.
+
+ENOMEM
+ Not enough physical or virtual memory was available to complete the
+ request.
diff --git a/Documentation/media/uapi/v4l/func-munmap.rst b/Documentation/media/uapi/v4l/func-munmap.rst
new file mode 100644
index 000000000000..c29c03f21279
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-munmap.rst
@@ -0,0 +1,58 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-munmap:
+
+*************
+V4L2 munmap()
+*************
+
+Name
+====
+
+v4l2-munmap - Unmap device memory
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+ #include <sys/mman.h>
+
+
+.. cpp:function:: int munmap( void *start, size_t length )
+
+
+Arguments
+=========
+
+``start``
+ Address of the mapped buffer as returned by the
+ :ref:`mmap() <func-mmap>` function.
+
+``length``
+ Length of the mapped buffer. This must be the same value as given to
+ :ref:`mmap() <func-mmap>` and returned by the driver in the struct
+ :ref:`v4l2_buffer <v4l2-buffer>` ``length`` field for the
+ single-planar API and in the struct
+ :ref:`v4l2_plane <v4l2-plane>` ``length`` field for the
+ multi-planar API.
+
+
+Description
+===========
+
+Unmaps a previously with the :ref:`mmap() <func-mmap>` function mapped
+buffer and frees it, if possible.
+
+
+Return Value
+============
+
+On success :ref:`munmap() <func-munmap>` returns 0, on failure -1 and the
+``errno`` variable is set appropriately:
+
+EINVAL
+ The ``start`` or ``length`` is incorrect, or no buffers have been
+ mapped yet.
diff --git a/Documentation/media/uapi/v4l/func-open.rst b/Documentation/media/uapi/v4l/func-open.rst
new file mode 100644
index 000000000000..06bcadc269a4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-open.rst
@@ -0,0 +1,83 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-open:
+
+***********
+V4L2 open()
+***********
+
+Name
+====
+
+v4l2-open - Open a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <fcntl.h>
+
+
+.. cpp:function:: int open( const char *device_name, int flags )
+
+
+Arguments
+=========
+
+``device_name``
+ Device to be opened.
+
+``flags``
+ Open flags. Access mode must be ``O_RDWR``. This is just a
+ technicality, input devices still support only reading and output
+ devices only writing.
+
+ When the ``O_NONBLOCK`` flag is given, the :ref:`read() <func-read>`
+ function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will
+ return the ``EAGAIN`` error code when no data is available or no
+ buffer is in the driver outgoing queue, otherwise these functions
+ block until data becomes available. All V4L2 drivers exchanging data
+ with applications must support the ``O_NONBLOCK`` flag.
+
+ Other flags have no effect.
+
+
+Description
+===========
+
+To open a V4L2 device applications call :ref:`open() <func-open>` with the
+desired device name. This function has no side effects; all data format
+parameters, current input or output, control values or other properties
+remain unchanged. At the first :ref:`open() <func-open>` call after loading the
+driver they will be reset to default values, drivers are never in an
+undefined state.
+
+
+Return Value
+============
+
+On success :ref:`open() <func-open>` returns the new file descriptor. On error
+-1 is returned, and the ``errno`` variable is set appropriately.
+Possible error codes are:
+
+EACCES
+ The caller has no permission to access the device.
+
+EBUSY
+ The driver does not support multiple opens and the device is already
+ in use.
+
+ENXIO
+ No device corresponding to this device special file exists.
+
+ENOMEM
+ Not enough kernel memory was available to complete the request.
+
+EMFILE
+ The process already has the maximum number of files open.
+
+ENFILE
+ The limit on the total number of files open on the system has been
+ reached.
diff --git a/Documentation/media/uapi/v4l/func-poll.rst b/Documentation/media/uapi/v4l/func-poll.rst
new file mode 100644
index 000000000000..e6ceb712b783
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-poll.rst
@@ -0,0 +1,116 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-poll:
+
+***********
+V4L2 poll()
+***********
+
+Name
+====
+
+v4l2-poll - Wait for some event on a file descriptor
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/poll.h>
+
+
+.. cpp:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
+
+
+Arguments
+=========
+
+
+
+Description
+===========
+
+With the :ref:`poll() <func-poll>` function applications can suspend execution
+until the driver has captured data or is ready to accept data for
+output.
+
+When streaming I/O has been negotiated this function waits until a
+buffer has been filled by the capture device and can be dequeued with
+the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. For output devices this
+function waits until the device is ready to accept a new buffer to be
+queued up with the :ref:`VIDIOC_QBUF` ioctl for
+display. When buffers are already in the outgoing queue of the driver
+(capture) or the incoming queue isn't full (display) the function
+returns immediately.
+
+On success :ref:`poll() <func-poll>` returns the number of file descriptors
+that have been selected (that is, file descriptors for which the
+``revents`` field of the respective :c:func:`struct pollfd` structure
+is non-zero). Capture devices set the ``POLLIN`` and ``POLLRDNORM``
+flags in the ``revents`` field, output devices the ``POLLOUT`` and
+``POLLWRNORM`` flags. When the function timed out it returns a value of
+zero, on failure it returns -1 and the ``errno`` variable is set
+appropriately. When the application did not call
+:ref:`VIDIOC_STREAMON` the :ref:`poll() <func-poll>`
+function succeeds, but sets the ``POLLERR`` flag in the ``revents``
+field. When the application has called
+:ref:`VIDIOC_STREAMON` for a capture device but
+hasn't yet called :ref:`VIDIOC_QBUF`, the
+:ref:`poll() <func-poll>` function succeeds and sets the ``POLLERR`` flag in
+the ``revents`` field. For output devices this same situation will cause
+:ref:`poll() <func-poll>` to succeed as well, but it sets the ``POLLOUT`` and
+``POLLWRNORM`` flags in the ``revents`` field.
+
+If an event occurred (see :ref:`VIDIOC_DQEVENT`)
+then ``POLLPRI`` will be set in the ``revents`` field and
+:ref:`poll() <func-poll>` will return.
+
+When use of the :ref:`read() <func-read>` function has been negotiated and the
+driver does not capture yet, the :ref:`poll() <func-poll>` function starts
+capturing. When that fails it returns a ``POLLERR`` as above. Otherwise
+it waits until data has been captured and can be read. When the driver
+captures continuously (as opposed to, for example, still images) the
+function may return immediately.
+
+When use of the :ref:`write() <func-write>` function has been negotiated and the
+driver does not stream yet, the :ref:`poll() <func-poll>` function starts
+streaming. When that fails it returns a ``POLLERR`` as above. Otherwise
+it waits until the driver is ready for a non-blocking
+:ref:`write() <func-write>` call.
+
+If the caller is only interested in events (just ``POLLPRI`` is set in
+the ``events`` field), then :ref:`poll() <func-poll>` will *not* start
+streaming if the driver does not stream yet. This makes it possible to
+just poll for events and not for buffers.
+
+All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
+function or streaming I/O must also support the :ref:`poll() <func-poll>`
+function.
+
+For more details see the :ref:`poll() <func-poll>` manual page.
+
+
+Return Value
+============
+
+On success, :ref:`poll() <func-poll>` returns the number structures which have
+non-zero ``revents`` fields, or zero if the call timed out. On error -1
+is returned, and the ``errno`` variable is set appropriately:
+
+EBADF
+ One or more of the ``ufds`` members specify an invalid file
+ descriptor.
+
+EBUSY
+ The driver does not support multiple read or write streams and the
+ device is already in use.
+
+EFAULT
+ ``ufds`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal.
+
+EINVAL
+ The ``nfds`` argument is greater than ``OPEN_MAX``.
diff --git a/Documentation/media/uapi/v4l/func-read.rst b/Documentation/media/uapi/v4l/func-read.rst
new file mode 100644
index 000000000000..9a2aa5210233
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-read.rst
@@ -0,0 +1,131 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-read:
+
+***********
+V4L2 read()
+***********
+
+Name
+====
+
+v4l2-read - Read from a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: ssize_t read( int fd, void *buf, size_t count )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``buf``
+``count``
+
+
+Description
+===========
+
+:ref:`read() <func-read>` attempts to read up to ``count`` bytes from file
+descriptor ``fd`` into the buffer starting at ``buf``. The layout of the
+data in the buffer is discussed in the respective device interface
+section, see ##. If ``count`` is zero, :ref:`read() <func-read>` returns zero
+and has no other results. If ``count`` is greater than ``SSIZE_MAX``,
+the result is unspecified. Regardless of the ``count`` value each
+:ref:`read() <func-read>` call will provide at most one frame (two fields)
+worth of data.
+
+By default :ref:`read() <func-read>` blocks until data becomes available. When
+the ``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>`
+function it returns immediately with an ``EAGAIN`` error code when no data
+is available. The :ref:`select() <func-select>` or
+:ref:`poll() <func-poll>` functions can always be used to suspend
+execution until data becomes available. All drivers supporting the
+:ref:`read() <func-read>` function must also support :ref:`select() <func-select>` and
+:ref:`poll() <func-poll>`.
+
+Drivers can implement read functionality in different ways, using a
+single or multiple buffers and discarding the oldest or newest frames
+once the internal buffers are filled.
+
+:ref:`read() <func-read>` never returns a "snapshot" of a buffer being filled.
+Using a single buffer the driver will stop capturing when the
+application starts reading the buffer until the read is finished. Thus
+only the period of the vertical blanking interval is available for
+reading, or the capture rate must fall below the nominal frame rate of
+the video standard.
+
+The behavior of :ref:`read() <func-read>` when called during the active picture
+period or the vertical blanking separating the top and bottom field
+depends on the discarding policy. A driver discarding the oldest frames
+keeps capturing into an internal buffer, continuously overwriting the
+previously, not read frame, and returns the frame being received at the
+time of the :ref:`read() <func-read>` call as soon as it is complete.
+
+A driver discarding the newest frames stops capturing until the next
+:ref:`read() <func-read>` call. The frame being received at :ref:`read() <func-read>`
+time is discarded, returning the following frame instead. Again this
+implies a reduction of the capture rate to one half or less of the
+nominal frame rate. An example of this model is the video read mode of
+the bttv driver, initiating a DMA to user memory when :ref:`read() <func-read>`
+is called and returning when the DMA finished.
+
+In the multiple buffer model drivers maintain a ring of internal
+buffers, automatically advancing to the next free buffer. This allows
+continuous capturing when the application can empty the buffers fast
+enough. Again, the behavior when the driver runs out of free buffers
+depends on the discarding policy.
+
+Applications can get and set the number of buffers used internally by
+the driver with the :ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
+:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctls. They are optional,
+however. The discarding policy is not reported and cannot be changed.
+For minimum requirements see :ref:`devices`.
+
+
+Return Value
+============
+
+On success, the number of bytes read is returned. It is not an error if
+this number is smaller than the number of bytes requested, or the amount
+of data required for one frame. This may happen for example because
+:ref:`read() <func-read>` was interrupted by a signal. On error, -1 is
+returned, and the ``errno`` variable is set appropriately. In this case
+the next read will start at the beginning of a new frame. Possible error
+codes are:
+
+EAGAIN
+ Non-blocking I/O has been selected using O_NONBLOCK and no data was
+ immediately available for reading.
+
+EBADF
+ ``fd`` is not a valid file descriptor or is not open for reading, or
+ the process already has the maximum number of files open.
+
+EBUSY
+ The driver does not support multiple read streams and the device is
+ already in use.
+
+EFAULT
+ ``buf`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal before any data was read.
+
+EIO
+ I/O error. This indicates some hardware problem or a failure to
+ communicate with a remote device (USB camera etc.).
+
+EINVAL
+ The :ref:`read() <func-read>` function is not supported by this driver, not
+ on this device, or generally not on this type of device.
diff --git a/Documentation/media/uapi/v4l/func-select.rst b/Documentation/media/uapi/v4l/func-select.rst
new file mode 100644
index 000000000000..954dd00b8301
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-select.rst
@@ -0,0 +1,106 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-select:
+
+*************
+V4L2 select()
+*************
+
+Name
+====
+
+v4l2-select - Synchronous I/O multiplexing
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <sys/time.h>
+ #include <sys/types.h>
+ #include <unistd.h>
+
+
+.. cpp:function:: int select( int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout )
+
+
+Arguments
+=========
+
+
+
+Description
+===========
+
+With the :ref:`select() <func-select>` function applications can suspend
+execution until the driver has captured data or is ready to accept data
+for output.
+
+When streaming I/O has been negotiated this function waits until a
+buffer has been filled or displayed and can be dequeued with the
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. When buffers are already in
+the outgoing queue of the driver the function returns immediately.
+
+On success :ref:`select() <func-select>` returns the total number of bits set in
+:c:func:`struct fd_set`. When the function timed out it returns
+a value of zero. On failure it returns -1 and the ``errno`` variable is
+set appropriately. When the application did not call
+:ref:`VIDIOC_QBUF` or
+:ref:`VIDIOC_STREAMON` yet the :ref:`select() <func-select>`
+function succeeds, setting the bit of the file descriptor in ``readfds``
+or ``writefds``, but subsequent :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
+calls will fail. [1]_
+
+When use of the :ref:`read() <func-read>` function has been negotiated and the
+driver does not capture yet, the :ref:`select() <func-select>` function starts
+capturing. When that fails, :ref:`select() <func-select>` returns successful and
+a subsequent :ref:`read() <func-read>` call, which also attempts to start
+capturing, will return an appropriate error code. When the driver
+captures continuously (as opposed to, for example, still images) and
+data is already available the :ref:`select() <func-select>` function returns
+immediately.
+
+When use of the :ref:`write() <func-write>` function has been negotiated the
+:ref:`select() <func-select>` function just waits until the driver is ready for a
+non-blocking :ref:`write() <func-write>` call.
+
+All drivers implementing the :ref:`read() <func-read>` or :ref:`write() <func-write>`
+function or streaming I/O must also support the :ref:`select() <func-select>`
+function.
+
+For more details see the :ref:`select() <func-select>` manual page.
+
+
+Return Value
+============
+
+On success, :ref:`select() <func-select>` returns the number of descriptors
+contained in the three returned descriptor sets, which will be zero if
+the timeout expired. On error -1 is returned, and the ``errno`` variable
+is set appropriately; the sets and ``timeout`` are undefined. Possible
+error codes are:
+
+EBADF
+ One or more of the file descriptor sets specified a file descriptor
+ that is not open.
+
+EBUSY
+ The driver does not support multiple read or write streams and the
+ device is already in use.
+
+EFAULT
+ The ``readfds``, ``writefds``, ``exceptfds`` or ``timeout`` pointer
+ references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal.
+
+EINVAL
+ The ``nfds`` argument is less than zero or greater than
+ ``FD_SETSIZE``.
+
+.. [1]
+ The Linux kernel implements :ref:`select() <func-select>` like the
+ :ref:`poll() <func-poll>` function, but :ref:`select() <func-select>` cannot
+ return a ``POLLERR``.
diff --git a/Documentation/media/uapi/v4l/func-write.rst b/Documentation/media/uapi/v4l/func-write.rst
new file mode 100644
index 000000000000..a3bc9b26fe56
--- /dev/null
+++ b/Documentation/media/uapi/v4l/func-write.rst
@@ -0,0 +1,82 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _func-write:
+
+************
+V4L2 write()
+************
+
+Name
+====
+
+v4l2-write - Write to a V4L2 device
+
+
+Synopsis
+========
+
+.. code-block:: c
+
+ #include <unistd.h>
+
+
+.. cpp:function:: ssize_t write( int fd, void *buf, size_t count )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``buf``
+``count``
+
+
+Description
+===========
+
+:ref:`write() <func-write>` writes up to ``count`` bytes to the device
+referenced by the file descriptor ``fd`` from the buffer starting at
+``buf``. When the hardware outputs are not active yet, this function
+enables them. When ``count`` is zero, :ref:`write() <func-write>` returns 0
+without any other effect.
+
+When the application does not provide more data in time, the previous
+video frame, raw VBI image, sliced VPS or WSS data is displayed again.
+Sliced Teletext or Closed Caption data is not repeated, the driver
+inserts a blank line instead.
+
+
+Return Value
+============
+
+On success, the number of bytes written are returned. Zero indicates
+nothing was written. On error, -1 is returned, and the ``errno``
+variable is set appropriately. In this case the next write will start at
+the beginning of a new frame. Possible error codes are:
+
+EAGAIN
+ Non-blocking I/O has been selected using the
+ :ref:`O_NONBLOCK <func-open>` flag and no buffer space was
+ available to write the data immediately.
+
+EBADF
+ ``fd`` is not a valid file descriptor or is not open for writing.
+
+EBUSY
+ The driver does not support multiple write streams and the device is
+ already in use.
+
+EFAULT
+ ``buf`` references an inaccessible memory area.
+
+EINTR
+ The call was interrupted by a signal before any data was written.
+
+EIO
+ I/O error. This indicates some hardware problem.
+
+EINVAL
+ The :ref:`write() <func-write>` function is not supported by this driver,
+ not on this device, or generally not on this type of device.
diff --git a/Documentation/media/uapi/v4l/hist-v4l2.rst b/Documentation/media/uapi/v4l/hist-v4l2.rst
new file mode 100644
index 000000000000..a571e099fde7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/hist-v4l2.rst
@@ -0,0 +1,1480 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _hist-v4l2:
+
+***********************
+Changes of the V4L2 API
+***********************
+
+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.
+
+
+Early Versions
+==============
+
+1998-08-20: First version.
+
+1998-08-27: The :ref:`select() <func-select>` function was introduced.
+
+1998-09-10: New video standard interface.
+
+1998-09-18: The ``VIDIOC_NONCAP`` ioctl was replaced by the otherwise
+meaningless ``O_TRUNC`` :ref:`open() <func-open>` flag, and the
+aliases ``O_NONCAP`` and ``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
+:c:func:`video_std_construct()` helper function takes id and
+transmission arguments.
+
+1998-09-28: Revamped video standard. Made video controls individually
+enumerable.
+
+1998-10-02: The ``id`` field was removed from struct
+:c:type:`struct video_standard` and the color subcarrier fields were
+renamed. The :ref:`VIDIOC_QUERYSTD` ioctl was
+renamed to :ref:`VIDIOC_ENUMSTD`,
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` to
+:ref:`VIDIOC_ENUMINPUT`. A first draft of the
+Codec API was released.
+
+1998-11-08: Many minor changes. Most symbols have been renamed. Some
+material changes to struct :ref:`v4l2_capability <v4l2-capability>`.
+
+1998-11-12: The read/write directon of some ioctls was misdefined.
+
+1998-11-14: ``V4L2_PIX_FMT_RGB24`` changed to ``V4L2_PIX_FMT_BGR24``,
+and ``V4L2_PIX_FMT_RGB32`` changed to ``V4L2_PIX_FMT_BGR32``. Audio
+controls are now accessible with the
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` and
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctls under names starting
+with ``V4L2_CID_AUDIO``. The ``V4L2_MAJOR`` define was removed from
+``videodev.h`` since it was only used once in the ``videodev`` kernel
+module. The ``YUV422`` and ``YUV411`` planar 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-19: The ``VIDIOC_NEXTBUF`` ioctl was removed.
+
+
+V4L2 Version 0.16 1999-01-31
+============================
+
+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.
+
+
+V4L2 Version 0.18 1999-03-16
+============================
+
+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.
+
+
+V4L2 Version 0.19 1999-06-05
+============================
+
+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.
+
+
+V4L2 Version 0.20 (1999-09-10)
+==============================
+
+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.
+
+1. Some typos in ``V4L2_FMT_FLAG`` symbols were fixed. struct
+ :ref:`v4l2_clip <v4l2-clip>` was changed for compatibility with
+ v4l. (1999-08-30)
+
+2. ``V4L2_TUNER_SUB_LANG1`` was added. (1999-09-05)
+
+3. 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
+
+
+ .. code-block:: c
+
+ err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
+
+ becomes
+
+
+ .. code-block:: c
+
+ int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &a);
+
+4. All the different get- and set-format commands were swept into one
+ :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_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_S_INFMT``,
+ ``VIDIOC_G_INFMT``, ``VIDIOC_S_OUTFMT``, ``VIDIOC_G_OUTFMT``,
+ ``VIDIOC_S_VBIFMT`` and ``VIDIOC_G_VBIFMT``. The image format
+ structure :c:type:`struct v4l2_format` was renamed to struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`, while struct
+ :ref:`v4l2_format <v4l2-format>` is now the envelopping structure
+ for all format negotiations.
+
+5. Similar to the changes above, the ``VIDIOC_G_PARM`` and
+ ``VIDIOC_S_PARM`` ioctls were merged with ``VIDIOC_G_OUTPARM`` and
+ ``VIDIOC_S_OUTPARM``. A ``type`` field in the new struct
+ :ref:`v4l2_streamparm <v4l2-streamparm>` selects the respective
+ union member.
+
+ This change obsoletes the ``VIDIOC_G_OUTPARM`` and
+ ``VIDIOC_S_OUTPARM`` ioctls.
+
+6. Control enumeration was simplified, and two new control flags were
+ introduced and one dropped. The ``catname`` field was replaced by a
+ ``group`` field.
+
+ Drivers can now flag unsupported and temporarily unavailable controls
+ with ``V4L2_CTRL_FLAG_DISABLED`` and ``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.
+
+7. The struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` 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://web.archive.org/web/\*/http://reality.sgi.com
+ /cpirazzi_engr/lg/time/intro.html. 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.
+
+8. A ``sequence`` field was added to struct
+ :ref:`v4l2_buffer <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 skipped.
+
+
+V4L2 Version 0.20 incremental changes
+=====================================
+
+1999-12-23: In struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` the
+``reserved1`` field became ``offset``. Previously drivers were required
+to clear the ``reserved1`` field.
+
+2000-01-13: The ``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.
+
+2000-11-20: ``V4L2_TYPE_VBI_OUTPUT`` and ``V4L2_PIX_FMT_Y41P`` were
+added.
+
+2000-11-25: ``V4L2_TYPE_VBI_INPUT`` was 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 ``v4l2_fourcc``.
+
+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.
+
+2001-09-17: New YUV formats and the
+:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctls were added.
+(The old ``VIDIOC_G_FREQ`` and ``VIDIOC_S_FREQ`` ioctls did not take
+multiple tuners into account.)
+
+2000-09-18: ``V4L2_BUF_TYPE_VBI`` was added. This may *break
+compatibility* as the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls may fail now if the struct
+:c:type:`struct v4l2_fmt` ``type`` field does not contain
+``V4L2_BUF_TYPE_VBI``. In the documentation of the struct
+:ref:`v4l2_vbi_format <v4l2-vbi-format>` ``offset`` field the
+ambiguous phrase "rising edge" was changed to "leading edge".
+
+
+V4L2 Version 0.20 2000-11-23
+============================
+
+A number of changes were made to the raw VBI interface.
+
+1. Figures clarifying the line numbering scheme were added to the V4L2
+ API specification. The ``start``\ [0] and ``start``\ [1] 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.
+
+2. The restriction "count[0] > 0 and count[1] > 0" has been relaxed to
+ "(count[0] + count[1]) > 0". Rationale: Drivers may allocate
+ resources at scan line granularity and some data services are
+ transmitted only on the first field. The comment that both ``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 correctly.
+
+3. 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 ``EBUSY`` and ``EINVAL``
+ error codes with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl was
+ clarified. The ``EBUSY`` error code was finally documented, and the
+ ``reserved2`` field which was previously mentioned only in the
+ ``videodev.h`` header file.
+
+4. New buffer types ``V4L2_TYPE_VBI_INPUT`` and ``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.
+
+
+V4L2 Version 0.20 2002-07-25
+============================
+
+Added sliced VBI interface proposal.
+
+
+V4L2 in Linux 2.5.46, 2002-10
+=============================
+
+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.
+
+1. As specified in :ref:`related`, drivers must make related device
+ functions available under all minor device numbers.
+
+2. The :ref:`open() <func-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 ``O_NOIO`` 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
+ :ref:`open`.
+
+3. The struct :ref:`v4l2_capability <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 the new
+ :ref:`VIDIOC_QUERYCAP` ioctl.
+
+ There are new fields to identify the driver, a new RDS device
+ function ``V4L2_CAP_RDS_CAPTURE``, the ``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
+ ``flags`` field. ``V4L2_FLAG_TUNER`` was renamed to
+ ``V4L2_CAP_TUNER``, ``V4L2_CAP_VIDEO_OVERLAY`` replaced
+ ``V4L2_FLAG_PREVIEW`` and ``V4L2_CAP_VBI_CAPTURE`` and
+ ``V4L2_CAP_VBI_OUTPUT`` replaced ``V4L2_FLAG_DATA_SERVICE``.
+ ``V4L2_FLAG_READ`` and ``V4L2_FLAG_WRITE`` were merged into
+ ``V4L2_CAP_READWRITE``.
+
+ The redundant fields ``inputs``, ``outputs`` and ``audios`` were
+ removed. These properties can be determined as described in
+ :ref:`video` and :ref:`audio`.
+
+ The somewhat volatile and therefore barely useful fields
+ ``maxwidth``, ``maxheight``, ``minwidth``, ``minheight``,
+ ``maxframerate`` were removed. This information is available as
+ described in :ref:`format` and :ref:`standard`.
+
+ ``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 redundant
+ ``V4L2_FLAG_MONOCHROME`` flag was removed, this information is
+ available as described in :ref:`format`.
+
+4. In struct :ref:`v4l2_input <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 ``tuner`` (reversing the former link from tuners to
+ video inputs), ``std`` and ``status``.
+
+ Accordingly struct :ref:`v4l2_output <v4l2-output>` lost its
+ ``capability`` and ``assoc_audio`` fields. ``audioset``,
+ ``modulator`` and ``std`` where added instead.
+
+5. The struct :ref:`v4l2_audio <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
+ :ref:`v4l2_audioout <v4l2-audioout>` field ``audio`` was renamed
+ to ``index``.
+
+6. The struct :ref:`v4l2_tuner <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
+ :ref:`v4l2_input <v4l2-input>`. A ``type`` field was added.
+
+ Accordingly in struct :ref:`v4l2_modulator <v4l2-modulator>` the
+ ``output`` was replaced by an ``index`` field.
+
+ In struct :ref:`v4l2_frequency <v4l2-frequency>` the ``port``
+ field was replaced by a ``tuner`` field containing the respective
+ tuner or modulator index number. A tuner ``type`` field was added
+ and the ``reserved`` field became larger for future extensions
+ (satellite tuners in particular).
+
+7. 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 :ref:`v4l2_std_id <v4l2-std-id>` and symbols
+ defined in the ``videodev2.h`` header file. For details see
+ :ref:`standard`. The :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
+ :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` now take a pointer to this
+ type as argument. :ref:`VIDIOC_QUERYSTD` was
+ added to autodetect the received standard, if the hardware has this
+ capability. In struct :ref:`v4l2_standard <v4l2-standard>` an
+ ``index`` field was added for
+ :ref:`VIDIOC_ENUMSTD`. A
+ :ref:`v4l2_std_id <v4l2-std-id>` field named ``id`` was added as
+ machine readable identifier, also replacing the ``transmission``
+ field. The misleading ``framerate`` field was renamed to
+ ``frameperiod``. The now obsolete ``colorstandard`` information,
+ originally needed to distguish between variations of standards, were
+ removed.
+
+ Struct :c:type:`struct v4l2_enumstd` ceased to be.
+ :ref:`VIDIOC_ENUMSTD` now takes a pointer to a
+ struct :ref:`v4l2_standard <v4l2-standard>` directly. The
+ information which standards are supported by a particular video
+ input or output moved into struct :ref:`v4l2_input <v4l2-input>`
+ and struct :ref:`v4l2_output <v4l2-output>` fields named ``std``,
+ respectively.
+
+8. The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` fields
+ ``category`` and ``group`` did not catch on and/or were not
+ implemented as expected and therefore removed.
+
+9. The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl was added to
+ negotiate data formats as with
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, but without the overhead of
+ programming the hardware and regardless of I/O in progress.
+
+ In struct :ref:`v4l2_format <v4l2-format>` the ``fmt`` union was
+ extended to contain struct :ref:`v4l2_window <v4l2-window>`. All
+ image format negotiations are now possible with ``VIDIOC_G_FMT``,
+ ``VIDIOC_S_FMT`` and ``VIDIOC_TRY_FMT``; ioctl. The ``VIDIOC_G_WIN``
+ and ``VIDIOC_S_WIN`` ioctls to prepare for a video overlay were
+ removed. The ``type`` field changed to type enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>` and the buffer type names
+ changed as follows.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Old defines
+
+ - enum :ref:`v4l2_buf_type <v4l2-buf-type>`
+
+ - .. row 2
+
+ - ``V4L2_BUF_TYPE_CAPTURE``
+
+ - ``V4L2_BUF_TYPE_VIDEO_CAPTURE``
+
+ - .. row 3
+
+ - ``V4L2_BUF_TYPE_CODECIN``
+
+ - Omitted for now
+
+ - .. row 4
+
+ - ``V4L2_BUF_TYPE_CODECOUT``
+
+ - Omitted for now
+
+ - .. row 5
+
+ - ``V4L2_BUF_TYPE_EFFECTSIN``
+
+ - Omitted for now
+
+ - .. row 6
+
+ - ``V4L2_BUF_TYPE_EFFECTSIN2``
+
+ - Omitted for now
+
+ - .. row 7
+
+ - ``V4L2_BUF_TYPE_EFFECTSOUT``
+
+ - Omitted for now
+
+ - .. row 8
+
+ - ``V4L2_BUF_TYPE_VIDEOOUT``
+
+ - ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+
+ - .. row 9
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VIDEO_OVERLAY``
+
+ - .. row 10
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VBI_CAPTURE``
+
+ - .. row 11
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_VBI_OUTPUT``
+
+ - .. row 12
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE``
+
+ - .. row 13
+
+ - ``-``
+
+ - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``
+
+ - .. row 14
+
+ - ``V4L2_BUF_TYPE_PRIVATE_BASE``
+
+ - ``V4L2_BUF_TYPE_PRIVATE`` (but this is deprecated)
+
+
+10. In struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` a enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>` field named ``type`` was
+ added as in struct :ref:`v4l2_format <v4l2-format>`. The
+ ``VIDIOC_ENUM_FBUFFMT`` ioctl is no longer needed and was removed.
+ These calls can be replaced by
+ :ref:`VIDIOC_ENUM_FMT` with type
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
+
+11. In struct :ref:`v4l2_pix_format <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 ``bytesperline`` field to zero to get a reasonable default.
+ Since the remaining flags were replaced as well, the ``flags`` field
+ itself was removed.
+
+ The interlace flags were replaced by a enum
+ :ref:`v4l2_field <v4l2-field>` value in a newly added ``field``
+ field.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Old flag
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - .. row 2
+
+ - ``V4L2_FMT_FLAG_NOT_INTERLACED``
+
+ - ?
+
+ - .. row 3
+
+ - ``V4L2_FMT_FLAG_INTERLACED`` = ``V4L2_FMT_FLAG_COMBINED``
+
+ - ``V4L2_FIELD_INTERLACED``
+
+ - .. row 4
+
+ - ``V4L2_FMT_FLAG_TOPFIELD`` = ``V4L2_FMT_FLAG_ODDFIELD``
+
+ - ``V4L2_FIELD_TOP``
+
+ - .. row 5
+
+ - ``V4L2_FMT_FLAG_BOTFIELD`` = ``V4L2_FMT_FLAG_EVENFIELD``
+
+ - ``V4L2_FIELD_BOTTOM``
+
+ - .. row 6
+
+ - ``-``
+
+ - ``V4L2_FIELD_SEQ_TB``
+
+ - .. row 7
+
+ - ``-``
+
+ - ``V4L2_FIELD_SEQ_BT``
+
+ - .. row 8
+
+ - ``-``
+
+ - ``V4L2_FIELD_ALTERNATE``
+
+
+ The color space flags were replaced by a enum
+ :ref:`v4l2_colorspace <v4l2-colorspace>` value in a newly added
+ ``colorspace`` field, where one of ``V4L2_COLORSPACE_SMPTE170M``,
+ ``V4L2_COLORSPACE_BT878``, ``V4L2_COLORSPACE_470_SYSTEM_M`` or
+ ``V4L2_COLORSPACE_470_SYSTEM_BG`` replaces ``V4L2_FMT_CS_601YUV``.
+
+12. In struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` the
+ ``type`` field was properly defined as enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>`. Buffer types changed as
+ mentioned above. A new ``memory`` field of type enum
+ :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between
+ I/O methods using buffers allocated by the driver or the
+ application. See :ref:`io` for details.
+
+13. In struct :ref:`v4l2_buffer <v4l2-buffer>` the ``type`` field was
+ properly defined as enum :ref:`v4l2_buf_type <v4l2-buf-type>`.
+ Buffer types changed as mentioned above. A ``field`` field of type
+ enum :ref:`v4l2_field <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 :c:type:`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
+ :ref:`v4l2_memory <v4l2-memory>` was added to distinguish between
+ I/O methods. See :ref:`io` for details.
+
+ The ``V4L2_BUF_REQ_CONTIG`` 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.
+
+14. In struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` the
+ ``base[3]`` 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_SCALEUP`` and ``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
+ ``V4L2_FBUF_CAP_LIST_CLIPPING`` and
+ ``V4L2_FBUF_CAP_BITMAP_CLIPPING``.
+
+15. In struct :ref:`v4l2_clip <v4l2-clip>` the ``x``, ``y``,
+ ``width`` and ``height`` field moved into a ``c`` substructure of
+ type struct :ref:`v4l2_rect <v4l2-rect>`. The ``x`` and ``y``
+ fields were renamed to ``left`` and ``top``, i. e. offsets to a
+ context dependent origin.
+
+16. In struct :ref:`v4l2_window <v4l2-window>` the ``x``, ``y``,
+ ``width`` and ``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.
+
+17. The digital zoom interface, including struct
+ :c:type:`struct v4l2_zoomcap`, struct
+ :c:type:`struct v4l2_zoom`, ``V4L2_ZOOM_NONCAP`` and
+ ``V4L2_ZOOM_WHILESTREAMING`` was replaced by a new cropping and
+ scaling interface. The previously unused struct
+ :c:type:`struct v4l2_cropcap` and :c:type:`struct v4l2_crop`
+ where redefined for this purpose. See :ref:`crop` for details.
+
+18. In struct :ref:`v4l2_vbi_format <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.
+
+19. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` the type of
+ the ``timeperframe`` field changed from unsigned long to struct
+ :ref:`v4l2_fract <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
+ :ref:`v4l2_outputparm <v4l2-outputparm>`.
+
+20. The struct :c:type:`struct v4l2_performance` and
+ ``VIDIOC_G_PERF`` ioctl were dropped. Except when using the
+ :ref:`read/write I/O method <rw>`, which is limited anyway, this
+ information is already available to applications.
+
+21. The example transformation from RGB to YCbCr color space in the old
+ V4L2 documentation was inaccurate, this has been corrected in
+ :ref:`pixfmt`.
+
+
+V4L2 2003-06-19
+===============
+
+1. 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 ``V4L2_TUNER_RADIO``.
+
+2. An optional driver access priority mechanism was added, see
+ :ref:`app-pri` for details.
+
+3. The audio input and output interface was found to be incomplete.
+
+ Previously the :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` 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 was removed on Kernel 2.6.39. The
+ :ref:`VIDIOC_ENUMAUDIO` ioctl was added to
+ enumerate audio inputs, while
+ :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` now reports the current
+ audio input.
+
+ The same changes were made to
+ :ref:`VIDIOC_G_AUDOUT <VIDIOC_G_AUDOUT>` and
+ :ref:`VIDIOC_ENUMAUDOUT <VIDIOC_ENUMAUDOUT>`.
+
+ 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.
+
+4. The :ref:`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 was removed on Kernel 2.6.39. Until further the
+ "videodev" kernel module will automatically translate to the new
+ version, so drivers must be recompiled, but not applications.
+
+5. :ref:`overlay` 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.
+
+6. The :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` and
+ :ref:`VIDIOC_S_CTRL <VIDIOC_G_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 were removed on
+ Kernel 2.6.39. Drivers and applications assuming a constant parameter
+ need an update.
+
+
+V4L2 2003-11-05
+===============
+
+1. In :ref:`pixfmt-rgb` the following pixel formats were incorrectly
+ transferred from Bill Dirks' V4L2 specification. Descriptions below
+ refer to bytes in memory, in ascending address order.
+
+
+
+ .. flat-table::
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Symbol
+
+ - In this document prior to revision 0.5
+
+ - Corrected
+
+ - .. row 2
+
+ - ``V4L2_PIX_FMT_RGB24``
+
+ - B, G, R
+
+ - R, G, B
+
+ - .. row 3
+
+ - ``V4L2_PIX_FMT_BGR24``
+
+ - R, G, B
+
+ - B, G, R
+
+ - .. row 4
+
+ - ``V4L2_PIX_FMT_RGB32``
+
+ - B, G, R, X
+
+ - R, G, B, X
+
+ - .. row 5
+
+ - ``V4L2_PIX_FMT_BGR32``
+
+ - R, G, B, X
+
+ - B, G, R, X
+
+
+ The ``V4L2_PIX_FMT_BGR24`` example was always correct.
+
+ In :ref:`v4l-image-properties` the mapping of the V4L
+ ``VIDEO_PALETTE_RGB24`` and ``VIDEO_PALETTE_RGB32`` formats to V4L2
+ pixel formats was accordingly corrected.
+
+2. 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 :ref:`pixfmt-rgb`.
+
+
+V4L2 in Linux 2.6.6, 2004-05-09
+===============================
+
+1. The :ref:`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 was removed on Kernel 2.6.39.
+
+
+V4L2 in Linux 2.6.8
+===================
+
+1. A new field ``input`` (former ``reserved[0]``) was added to the
+ struct :ref:`v4l2_buffer <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 ``V4L2_BUF_FLAG_INPUT`` flag. The ``flags`` field is no
+ longer read-only.
+
+
+V4L2 spec erratum 2004-08-01
+============================
+
+1. The return value of the :ref:`func-open` function was incorrectly
+ documented.
+
+2. Audio output ioctls end in -AUDOUT, not -AUDIOOUT.
+
+3. In the Current Audio Input example the ``VIDIOC_G_AUDIO`` ioctl took
+ the wrong argument.
+
+4. The documentation of the :ref:`VIDIOC_QBUF` and
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctls did not mention the
+ struct :ref:`v4l2_buffer <v4l2-buffer>` ``memory`` field. It was
+ also missing from examples. Also on the ``VIDIOC_DQBUF`` page the ``EIO``
+ error code was not documented.
+
+
+V4L2 in Linux 2.6.14
+====================
+
+1. A new sliced VBI interface was added. It is documented in
+ :ref:`sliced` and replaces the interface first proposed in V4L2
+ specification 0.8.
+
+
+V4L2 in Linux 2.6.15
+====================
+
+1. The :ref:`VIDIOC_LOG_STATUS` ioctl was added.
+
+2. New video standards ``V4L2_STD_NTSC_443``, ``V4L2_STD_SECAM_LC``,
+ ``V4L2_STD_SECAM_DK`` (a set of SECAM D, K and K1), and
+ ``V4L2_STD_ATSC`` (a set of ``V4L2_STD_ATSC_8_VSB`` and
+ ``V4L2_STD_ATSC_16_VSB``) were defined. Note the ``V4L2_STD_525_60``
+ set now includes ``V4L2_STD_NTSC_443``. See also
+ :ref:`v4l2-std-id`.
+
+3. The ``VIDIOC_G_COMP`` and ``VIDIOC_S_COMP`` ioctl were renamed to
+ ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` respectively. Their
+ argument was replaced by a struct
+ :c:type:`struct v4l2_mpeg_compression` pointer. (The
+ ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls where removed
+ in Linux 2.6.25.)
+
+
+V4L2 spec erratum 2005-11-27
+============================
+
+The capture example in :ref:`capture-example` called the
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl without checking if
+cropping is supported. In the video standard selection example in
+:ref:`standard` the :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` call used
+the wrong argument type.
+
+
+V4L2 spec erratum 2006-01-10
+============================
+
+1. The ``V4L2_IN_ST_COLOR_KILL`` flag in struct
+ :ref:`v4l2_input <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 quality.)
+
+2. :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` is a write-read ioctl, not
+ write-only as stated on its reference page. The ioctl changed in 2003
+ as noted above.
+
+
+V4L2 spec erratum 2006-02-03
+============================
+
+1. In struct :ref:`v4l2_captureparm <v4l2-captureparm>` and struct
+ :ref:`v4l2_outputparm <v4l2-outputparm>` the ``timeperframe``
+ field gives the time in seconds, not microseconds.
+
+
+V4L2 spec erratum 2006-02-04
+============================
+
+1. The ``clips`` field in struct :ref:`v4l2_window <v4l2-window>`
+ must point to an array of struct :ref:`v4l2_clip <v4l2-clip>`, not
+ a linked list, because drivers ignore the struct
+ :c:type:`struct v4l2_clip`. ``next`` pointer.
+
+
+V4L2 in Linux 2.6.17
+====================
+
+1. New video standard macros were added: ``V4L2_STD_NTSC_M_KR`` (NTSC M
+ South Korea), and the sets ``V4L2_STD_MN``, ``V4L2_STD_B``,
+ ``V4L2_STD_GH`` and ``V4L2_STD_DK``. The ``V4L2_STD_NTSC`` and
+ ``V4L2_STD_SECAM`` sets now include ``V4L2_STD_NTSC_M_KR`` and
+ ``V4L2_STD_SECAM_LC`` respectively.
+
+2. A new ``V4L2_TUNER_MODE_LANG1_LANG2`` was defined to record both
+ languages of a bilingual program. The use of
+ ``V4L2_TUNER_MODE_STEREO`` for this purpose is deprecated now. See
+ the :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` section for details.
+
+
+V4L2 spec erratum 2006-09-23 (Draft 0.15)
+=========================================
+
+1. In various places ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` and
+ ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` of the sliced VBI interface were
+ not mentioned along with other buffer types.
+
+2. In :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` it was clarified that the struct
+ :ref:`v4l2_audio <v4l2-audio>` ``mode`` field is a flags field.
+
+3. :ref:`VIDIOC_QUERYCAP` did not mention the sliced VBI and radio
+ capability flags.
+
+4. In :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` it was clarified that applications
+ must initialize the tuner ``type`` field of struct
+ :ref:`v4l2_frequency <v4l2-frequency>` before calling
+ :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>`.
+
+5. The ``reserved`` array in struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` has 2 elements,
+ not 32.
+
+6. In :ref:`output` and :ref:`raw-vbi` the device file names
+ ``/dev/vout`` which never caught on were replaced by ``/dev/video``.
+
+7. 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.
+
+
+V4L2 in Linux 2.6.18
+====================
+
+1. New ioctls :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and
+ :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` were added, a
+ flag to skip unsupported controls with
+ :ref:`VIDIOC_QUERYCTRL`, new control types
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_TYPE_CTRL_CLASS``
+ (:ref:`v4l2-ctrl-type`), and new control flags
+ ``V4L2_CTRL_FLAG_READ_ONLY``, ``V4L2_CTRL_FLAG_UPDATE``,
+ ``V4L2_CTRL_FLAG_INACTIVE`` and ``V4L2_CTRL_FLAG_SLIDER``
+ (:ref:`control-flags`). See :ref:`extended-controls` for details.
+
+
+V4L2 in Linux 2.6.19
+====================
+
+1. In struct :ref:`v4l2_sliced_vbi_cap <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. The
+ :ref:`VIDIOC_G_SLICED_VBI_CAP <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.
+
+2. The ioctls :ref:`VIDIOC_ENUM_FRAMESIZES`
+ and
+ :ref:`VIDIOC_ENUM_FRAMEINTERVALS`
+ were added.
+
+3. A new pixel format ``V4L2_PIX_FMT_RGB444`` (:ref:`rgb-formats`) was
+ added.
+
+
+V4L2 spec erratum 2006-10-12 (Draft 0.17)
+=========================================
+
+1. ``V4L2_PIX_FMT_HM12`` (:ref:`reserved-formats`) is a YUV 4:2:0, not
+ 4:2:2 format.
+
+
+V4L2 in Linux 2.6.21
+====================
+
+1. 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.
+
+
+V4L2 in Linux 2.6.22
+====================
+
+1. Two new field orders ``V4L2_FIELD_INTERLACED_TB`` and
+ ``V4L2_FIELD_INTERLACED_BT`` were added. See :ref:`v4l2-field` for
+ details.
+
+2. 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 :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+ and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctls for details.
+
+ A new ``global_alpha`` field was added to
+ :ref:`v4l2_window <v4l2-window>`, extending the structure. This
+ may *break compatibility* with applications using a struct
+ :c:type:`struct v4l2_window` directly. However the
+ :ref:`VIDIOC_G/S/TRY_FMT <VIDIOC_G_FMT>` ioctls, which take a
+ pointer to a :ref:`v4l2_format <v4l2-format>` parent structure
+ with padding bytes at the end, are not affected.
+
+3. The format of the ``chromakey`` field in struct
+ :ref:`v4l2_window <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.
+
+
+V4L2 in Linux 2.6.24
+====================
+
+1. The pixel formats ``V4L2_PIX_FMT_PAL8``, ``V4L2_PIX_FMT_YUV444``,
+ ``V4L2_PIX_FMT_YUV555``, ``V4L2_PIX_FMT_YUV565`` and
+ ``V4L2_PIX_FMT_YUV32`` were added.
+
+
+V4L2 in Linux 2.6.25
+====================
+
+1. The pixel formats :ref:`V4L2_PIX_FMT_Y16 <V4L2-PIX-FMT-Y16>` and
+ :ref:`V4L2_PIX_FMT_SBGGR16 <V4L2-PIX-FMT-SBGGR16>` were added.
+
+2. New :ref:`controls <control>` ``V4L2_CID_POWER_LINE_FREQUENCY``,
+ ``V4L2_CID_HUE_AUTO``, ``V4L2_CID_WHITE_BALANCE_TEMPERATURE``,
+ ``V4L2_CID_SHARPNESS`` and ``V4L2_CID_BACKLIGHT_COMPENSATION`` were
+ added. The controls ``V4L2_CID_BLACK_LEVEL``, ``V4L2_CID_WHITENESS``,
+ ``V4L2_CID_HCENTER`` and ``V4L2_CID_VCENTER`` were deprecated.
+
+3. A :ref:`Camera controls class <camera-controls>` was added, with
+ the new controls ``V4L2_CID_EXPOSURE_AUTO``,
+ ``V4L2_CID_EXPOSURE_ABSOLUTE``, ``V4L2_CID_EXPOSURE_AUTO_PRIORITY``,
+ ``V4L2_CID_PAN_RELATIVE``, ``V4L2_CID_TILT_RELATIVE``,
+ ``V4L2_CID_PAN_RESET``, ``V4L2_CID_TILT_RESET``,
+ ``V4L2_CID_PAN_ABSOLUTE``, ``V4L2_CID_TILT_ABSOLUTE``,
+ ``V4L2_CID_FOCUS_ABSOLUTE``, ``V4L2_CID_FOCUS_RELATIVE`` and
+ ``V4L2_CID_FOCUS_AUTO``.
+
+4. The ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls, which
+ were superseded by the :ref:`extended controls <extended-controls>`
+ interface in Linux 2.6.18, where finally removed from the
+ ``videodev2.h`` header file.
+
+
+V4L2 in Linux 2.6.26
+====================
+
+1. The pixel formats ``V4L2_PIX_FMT_Y16`` and ``V4L2_PIX_FMT_SBGGR16``
+ were added.
+
+2. Added user controls ``V4L2_CID_CHROMA_AGC`` and
+ ``V4L2_CID_COLOR_KILLER``.
+
+
+V4L2 in Linux 2.6.27
+====================
+
+1. The :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
+ and the ``V4L2_CAP_HW_FREQ_SEEK`` capability were added.
+
+2. The pixel formats ``V4L2_PIX_FMT_YVYU``, ``V4L2_PIX_FMT_PCA501``,
+ ``V4L2_PIX_FMT_PCA505``, ``V4L2_PIX_FMT_PCA508``,
+ ``V4L2_PIX_FMT_PCA561``, ``V4L2_PIX_FMT_SGBRG8``,
+ ``V4L2_PIX_FMT_PAC207`` and ``V4L2_PIX_FMT_PJPG`` were added.
+
+
+V4L2 in Linux 2.6.28
+====================
+
+1. Added ``V4L2_MPEG_AUDIO_ENCODING_AAC`` and
+ ``V4L2_MPEG_AUDIO_ENCODING_AC3`` MPEG audio encodings.
+
+2. Added ``V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC`` MPEG video encoding.
+
+3. The pixel formats ``V4L2_PIX_FMT_SGRBG10`` and
+ ``V4L2_PIX_FMT_SGRBG10DPCM8`` were added.
+
+
+V4L2 in Linux 2.6.29
+====================
+
+1. The ``VIDIOC_G_CHIP_IDENT`` ioctl was renamed to
+ ``VIDIOC_G_CHIP_IDENT_OLD`` and ``VIDIOC_DBG_G_CHIP_IDENT`` was
+ introduced in its place. The old struct
+ :c:type:`struct v4l2_chip_ident` was renamed to
+ :c:type:`struct v4l2_chip_ident_old`.
+
+2. The pixel formats ``V4L2_PIX_FMT_VYUY``, ``V4L2_PIX_FMT_NV16`` and
+ ``V4L2_PIX_FMT_NV61`` were added.
+
+3. Added camera controls ``V4L2_CID_ZOOM_ABSOLUTE``,
+ ``V4L2_CID_ZOOM_RELATIVE``, ``V4L2_CID_ZOOM_CONTINUOUS`` and
+ ``V4L2_CID_PRIVACY``.
+
+
+V4L2 in Linux 2.6.30
+====================
+
+1. New control flag ``V4L2_CTRL_FLAG_WRITE_ONLY`` was added.
+
+2. New control ``V4L2_CID_COLORFX`` was added.
+
+
+V4L2 in Linux 2.6.32
+====================
+
+1. In order to be easier to compare a V4L2 API and a kernel version, now
+ V4L2 API is numbered using the Linux Kernel version numeration.
+
+2. Finalized the RDS capture API. See :ref:`rds` for more information.
+
+3. Added new capabilities for modulators and RDS encoders.
+
+4. Add description for libv4l API.
+
+5. Added support for string controls via new type
+ ``V4L2_CTRL_TYPE_STRING``.
+
+6. Added ``V4L2_CID_BAND_STOP_FILTER`` documentation.
+
+7. Added FM Modulator (FM TX) Extended Control Class:
+ ``V4L2_CTRL_CLASS_FM_TX`` and their Control IDs.
+
+8. Added FM Receiver (FM RX) Extended Control Class:
+ ``V4L2_CTRL_CLASS_FM_RX`` and their Control IDs.
+
+9. Added Remote Controller chapter, describing the default Remote
+ Controller mapping for media devices.
+
+
+V4L2 in Linux 2.6.33
+====================
+
+1. Added support for Digital Video timings in order to support HDTV
+ receivers and transmitters.
+
+
+V4L2 in Linux 2.6.34
+====================
+
+1. Added ``V4L2_CID_IRIS_ABSOLUTE`` and ``V4L2_CID_IRIS_RELATIVE``
+ controls to the :ref:`Camera controls class <camera-controls>`.
+
+
+V4L2 in Linux 2.6.37
+====================
+
+1. Remove the vtx (videotext/teletext) API. This API was no longer used
+ and no hardware exists to verify the API. Nor were any userspace
+ applications found that used it. It was originally scheduled for
+ removal in 2.6.35.
+
+
+V4L2 in Linux 2.6.39
+====================
+
+1. The old VIDIOC_*_OLD symbols and V4L1 support were removed.
+
+2. Multi-planar API added. Does not affect the compatibility of current
+ drivers and applications. See :ref:`multi-planar API <planar-apis>`
+ for details.
+
+
+V4L2 in Linux 3.1
+=================
+
+1. VIDIOC_QUERYCAP now returns a per-subsystem version instead of a
+ per-driver one.
+
+ Standardize an error code for invalid ioctl.
+
+ Added V4L2_CTRL_TYPE_BITMASK.
+
+
+V4L2 in Linux 3.2
+=================
+
+1. V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to
+ userspace.
+
+2. Add selection API for extended control over cropping and composing.
+ Does not affect the compatibility of current drivers and
+ applications. See :ref:`selection API <selection-api>` for details.
+
+
+V4L2 in Linux 3.3
+=================
+
+1. Added ``V4L2_CID_ALPHA_COMPONENT`` control to the
+ :ref:`User controls class <control>`.
+
+2. Added the device_caps field to struct v4l2_capabilities and added
+ the new V4L2_CAP_DEVICE_CAPS capability.
+
+
+V4L2 in Linux 3.4
+=================
+
+1. Added :ref:`JPEG compression control class <jpeg-controls>`.
+
+2. Extended the DV Timings API:
+ :ref:`VIDIOC_ENUM_DV_TIMINGS`,
+ :ref:`VIDIOC_QUERY_DV_TIMINGS` and
+ :ref:`VIDIOC_DV_TIMINGS_CAP`.
+
+
+V4L2 in Linux 3.5
+=================
+
+1. Added integer menus, the new type will be
+ V4L2_CTRL_TYPE_INTEGER_MENU.
+
+2. Added selection API for V4L2 subdev interface:
+ :ref:`VIDIOC_SUBDEV_G_SELECTION` and
+ :ref:`VIDIOC_SUBDEV_S_SELECTION <VIDIOC_SUBDEV_G_SELECTION>`.
+
+3. Added ``V4L2_COLORFX_ANTIQUE``, ``V4L2_COLORFX_ART_FREEZE``,
+ ``V4L2_COLORFX_AQUA``, ``V4L2_COLORFX_SILHOUETTE``,
+ ``V4L2_COLORFX_SOLARIZATION``, ``V4L2_COLORFX_VIVID`` and
+ ``V4L2_COLORFX_ARBITRARY_CBCR`` menu items to the
+ ``V4L2_CID_COLORFX`` control.
+
+4. Added ``V4L2_CID_COLORFX_CBCR`` control.
+
+5. Added camera controls ``V4L2_CID_AUTO_EXPOSURE_BIAS``,
+ ``V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE``,
+ ``V4L2_CID_IMAGE_STABILIZATION``, ``V4L2_CID_ISO_SENSITIVITY``,
+ ``V4L2_CID_ISO_SENSITIVITY_AUTO``, ``V4L2_CID_EXPOSURE_METERING``,
+ ``V4L2_CID_SCENE_MODE``, ``V4L2_CID_3A_LOCK``,
+ ``V4L2_CID_AUTO_FOCUS_START``, ``V4L2_CID_AUTO_FOCUS_STOP``,
+ ``V4L2_CID_AUTO_FOCUS_STATUS`` and ``V4L2_CID_AUTO_FOCUS_RANGE``.
+
+
+V4L2 in Linux 3.6
+=================
+
+1. Replaced ``input`` in :c:type:`struct v4l2_buffer` by
+ ``reserved2`` and removed ``V4L2_BUF_FLAG_INPUT``.
+
+2. Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE
+ capabilities.
+
+3. Added support for frequency band enumerations:
+ :ref:`VIDIOC_ENUM_FREQ_BANDS`.
+
+
+V4L2 in Linux 3.9
+=================
+
+1. Added timestamp types to ``flags`` field in
+ :c:type:`struct v4l2_buffer`. See :ref:`buffer-flags`.
+
+2. Added ``V4L2_EVENT_CTRL_CH_RANGE`` control event changes flag. See
+ :ref:`ctrl-changes-flags`.
+
+
+V4L2 in Linux 3.10
+==================
+
+1. Removed obsolete and unused DV_PRESET ioctls VIDIOC_G_DV_PRESET,
+ VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
+ VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
+ capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
+
+2. Added new debugging ioctl
+ :ref:`VIDIOC_DBG_G_CHIP_INFO`.
+
+
+V4L2 in Linux 3.11
+==================
+
+1. Remove obsolete ``VIDIOC_DBG_G_CHIP_IDENT`` ioctl.
+
+
+V4L2 in Linux 3.14
+==================
+
+1. In struct :c:type:`struct v4l2_rect`, the type of ``width`` and
+ ``height`` fields changed from _s32 to _u32.
+
+
+V4L2 in Linux 3.15
+==================
+
+1. Added Software Defined Radio (SDR) Interface.
+
+
+V4L2 in Linux 3.16
+==================
+
+1. Added event V4L2_EVENT_SOURCE_CHANGE.
+
+
+V4L2 in Linux 3.17
+==================
+
+1. Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added
+ format flags.
+
+2. Added compound control types and
+ :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
+
+
+V4L2 in Linux 3.18
+==================
+
+1. Added ``V4L2_CID_PAN_SPEED`` and ``V4L2_CID_TILT_SPEED`` camera
+ controls.
+
+
+V4L2 in Linux 3.19
+==================
+
+1. Rewrote Colorspace chapter, added new enum
+ :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
+ :ref:`v4l2_quantization <v4l2-quantization>` fields to struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`, struct
+ :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
+ struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
+
+
+V4L2 in Linux 4.4
+=================
+
+1. Renamed ``V4L2_TUNER_ADC`` to ``V4L2_TUNER_SDR``. The use of
+ ``V4L2_TUNER_ADC`` is deprecated now.
+
+2. Added ``V4L2_CID_RF_TUNER_RF_GAIN`` RF Tuner control.
+
+3. Added transmitter support for Software Defined Radio (SDR) Interface.
+
+
+.. _other:
+
+Relation of V4L2 to other Linux multimedia APIs
+===============================================
+
+
+.. _xvideo:
+
+X Video Extension
+-----------------
+
+The X Video Extension (abbreviated XVideo or just Xv) is an extension of
+the X Window system, implemented for example by the XFree86 project. Its
+scope is similar to V4L2, an API to video capture and output devices for
+X clients. Xv allows applications to display live video in a window,
+send window contents to a TV output, and capture or output still images
+in XPixmaps [1]_. With their implementation XFree86 makes the extension
+available across many operating systems and architectures.
+
+Because the driver is embedded into the X server Xv has a number of
+advantages over the V4L2 :ref:`video overlay interface <overlay>`. The
+driver can easily determine the overlay target, i. e. visible graphics
+memory or off-screen buffers for a destructive overlay. It can program
+the RAMDAC for a non-destructive overlay, scaling or color-keying, or
+the clipping functions of the video capture hardware, always in sync
+with drawing operations or windows moving or changing their stacking
+order.
+
+To combine the advantages of Xv and V4L a special Xv driver exists in
+XFree86 and XOrg, just programming any overlay capable Video4Linux
+device it finds. To enable it ``/etc/X11/XF86Config`` must contain these
+lines:
+
+::
+
+ Section "Module"
+ Load "v4l"
+ EndSection
+
+As of XFree86 4.2 this driver still supports only V4L ioctls, however it
+should work just fine with all V4L2 devices through the V4L2
+backward-compatibility layer. Since V4L2 permits multiple opens it is
+possible (if supported by the V4L2 driver) to capture video while an X
+client requested video overlay. Restrictions of simultaneous capturing
+and overlay are discussed in :ref:`overlay` apply.
+
+Only marginally related to V4L2, XFree86 extended Xv to support hardware
+YUV to RGB conversion and scaling for faster video playback, and added
+an interface to MPEG-2 decoding hardware. This API is useful to display
+images captured with V4L2 devices.
+
+
+Digital Video
+-------------
+
+V4L2 does not support digital terrestrial, cable or satellite broadcast.
+A separate project aiming at digital receivers exists. You can find its
+homepage at `https://linuxtv.org <https://linuxtv.org>`__. The Linux
+DVB API has no connection to the V4L2 API except that drivers for hybrid
+hardware may support both.
+
+
+Audio Interfaces
+----------------
+
+[to do - OSS/ALSA]
+
+
+.. _experimental:
+
+Experimental API Elements
+=========================
+
+The following V4L2 API elements are currently experimental and may
+change in the future.
+
+- :ref:`VIDIOC_DBG_G_REGISTER` and
+ :ref:`VIDIOC_DBG_S_REGISTER <VIDIOC_DBG_G_REGISTER>` ioctls.
+
+- :ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
+
+
+.. _obsolete:
+
+Obsolete API Elements
+=====================
+
+The following V4L2 API elements were superseded by new interfaces and
+should not be implemented in new drivers.
+
+- ``VIDIOC_G_MPEGCOMP`` and ``VIDIOC_S_MPEGCOMP`` ioctls. Use Extended
+ Controls, :ref:`extended-controls`.
+
+- VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET,
+ VIDIOC_ENUM_DV_PRESETS and VIDIOC_QUERY_DV_PRESET ioctls. Use
+ the DV Timings API (:ref:`dv-timings`).
+
+- ``VIDIOC_SUBDEV_G_CROP`` and ``VIDIOC_SUBDEV_S_CROP`` ioctls. Use
+ ``VIDIOC_SUBDEV_G_SELECTION`` and ``VIDIOC_SUBDEV_S_SELECTION``,
+ :ref:`VIDIOC_SUBDEV_G_SELECTION`.
+
+.. [1]
+ This is not implemented in XFree86.
diff --git a/Documentation/media/uapi/v4l/io.rst b/Documentation/media/uapi/v4l/io.rst
new file mode 100644
index 000000000000..94b38a10ee65
--- /dev/null
+++ b/Documentation/media/uapi/v4l/io.rst
@@ -0,0 +1,51 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _io:
+
+############
+Input/Output
+############
+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 :ref:`read() <func-read>` and
+:ref:`write() <func-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
+:ref:`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 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl. For more information see :ref:`overlay`.
+
+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 :ref:`open`)
+and drivers permitting simultaneous video capturing and overlay using
+the same file descriptor, for compatibility with V4L and earlier
+versions of V4L2.
+
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` and :ref:`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.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ rw
+ mmap
+ userp
+ dmabuf
+ async
+ buffer
+ field-order
diff --git a/Documentation/media/uapi/v4l/libv4l-introduction.rst b/Documentation/media/uapi/v4l/libv4l-introduction.rst
new file mode 100644
index 000000000000..61d085f9f105
--- /dev/null
+++ b/Documentation/media/uapi/v4l/libv4l-introduction.rst
@@ -0,0 +1,169 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _libv4l-introduction:
+
+************
+Introduction
+************
+
+libv4l is a collection of libraries which adds a thin abstraction layer
+on top of video4linux2 devices. The purpose of this (thin) layer is to
+make it easy for application writers to support a wide variety of
+devices without having to write separate code for different devices in
+the same class.
+
+An example of using libv4l is provided by
+:ref:`v4l2grab <v4l2grab-example>`.
+
+libv4l consists of 3 different libraries:
+
+
+libv4lconvert
+=============
+
+libv4lconvert is a library that converts several different pixelformats
+found in V4L2 drivers into a few common RGB and YUY formats.
+
+It currently accepts the following V4L2 driver formats:
+:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
+:ref:`V4L2_PIX_FMT_HM12 <V4L2-PIX-FMT-HM12>`,
+:ref:`V4L2_PIX_FMT_JPEG <V4L2-PIX-FMT-JPEG>`,
+:ref:`V4L2_PIX_FMT_MJPEG <V4L2-PIX-FMT-MJPEG>`,
+:ref:`V4L2_PIX_FMT_MR97310A <V4L2-PIX-FMT-MR97310A>`,
+:ref:`V4L2_PIX_FMT_OV511 <V4L2-PIX-FMT-OV511>`,
+:ref:`V4L2_PIX_FMT_OV518 <V4L2-PIX-FMT-OV518>`,
+:ref:`V4L2_PIX_FMT_PAC207 <V4L2-PIX-FMT-PAC207>`,
+:ref:`V4L2_PIX_FMT_PJPG <V4L2-PIX-FMT-PJPG>`,
+:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
+:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`,
+:ref:`V4L2_PIX_FMT_SGBRG8 <V4L2-PIX-FMT-SGBRG8>`,
+:ref:`V4L2_PIX_FMT_SGRBG8 <V4L2-PIX-FMT-SGRBG8>`,
+:ref:`V4L2_PIX_FMT_SN9C10X <V4L2-PIX-FMT-SN9C10X>`,
+:ref:`V4L2_PIX_FMT_SN9C20X_I420 <V4L2-PIX-FMT-SN9C20X-I420>`,
+:ref:`V4L2_PIX_FMT_SPCA501 <V4L2-PIX-FMT-SPCA501>`,
+:ref:`V4L2_PIX_FMT_SPCA505 <V4L2-PIX-FMT-SPCA505>`,
+:ref:`V4L2_PIX_FMT_SPCA508 <V4L2-PIX-FMT-SPCA508>`,
+:ref:`V4L2_PIX_FMT_SPCA561 <V4L2-PIX-FMT-SPCA561>`,
+:ref:`V4L2_PIX_FMT_SQ905C <V4L2-PIX-FMT-SQ905C>`,
+:ref:`V4L2_PIX_FMT_SRGGB8 <V4L2-PIX-FMT-SRGGB8>`,
+:ref:`V4L2_PIX_FMT_UYVY <V4L2-PIX-FMT-UYVY>`,
+:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`,
+:ref:`V4L2_PIX_FMT_YUYV <V4L2-PIX-FMT-YUYV>`,
+:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, and
+:ref:`V4L2_PIX_FMT_YVYU <V4L2-PIX-FMT-YVYU>`.
+
+Later on libv4lconvert was expanded to also be able to do various video
+processing functions to improve webcam video quality. The video
+processing is split in to 2 parts: libv4lconvert/control and
+libv4lconvert/processing.
+
+The control part is used to offer video controls which can be used to
+control the video processing functions made available by
+libv4lconvert/processing. These controls are stored application wide
+(until reboot) by using a persistent shared memory object.
+
+libv4lconvert/processing offers the actual video processing
+functionality.
+
+
+libv4l1
+=======
+
+This library offers functions that can be used to quickly make v4l1
+applications work with v4l2 devices. These functions work exactly like
+the normal open/close/etc, except that libv4l1 does full emulation of
+the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it will
+just pass calls through.
+
+Since those functions are emulations of the old V4L1 API, it shouldn't
+be used for new applications.
+
+
+libv4l2
+=======
+
+This library should be used for all modern V4L2 applications.
+
+It provides handles to call V4L2 open/ioctl/close/poll methods. Instead
+of just providing the raw output of the device, it enhances the calls in
+the sense that it will use libv4lconvert to provide more video formats
+and to enhance the image quality.
+
+In most cases, libv4l2 just passes the calls directly through to the
+v4l2 driver, intercepting the calls to
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`,
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`,
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`,
+:ref:`VIDIOC_ENUM_FRAMESIZES <VIDIOC_ENUM_FRAMESIZES>` and
+:ref:`VIDIOC_ENUM_FRAMEINTERVALS <VIDIOC_ENUM_FRAMEINTERVALS>` in
+order to emulate the formats
+:ref:`V4L2_PIX_FMT_BGR24 <V4L2-PIX-FMT-BGR24>`,
+:ref:`V4L2_PIX_FMT_RGB24 <V4L2-PIX-FMT-RGB24>`,
+:ref:`V4L2_PIX_FMT_YUV420 <V4L2-PIX-FMT-YUV420>`, and
+:ref:`V4L2_PIX_FMT_YVU420 <V4L2-PIX-FMT-YVU420>`, if they aren't
+available in the driver. :ref:`VIDIOC_ENUM_FMT <VIDIOC_ENUM_FMT>`
+keeps enumerating the hardware supported formats, plus the emulated
+formats offered by libv4l at the end.
+
+
+.. _libv4l-ops:
+
+Libv4l device control functions
+-------------------------------
+
+The common file operation methods are provided by libv4l.
+
+Those functions operate just like glibc
+open/close/dup/ioctl/read/mmap/munmap:
+
+- :c:type:`int v4l2_open(const char *file, int oflag, ...)` - operates like the
+ standard :ref:`open() <func-open>` function.
+
+- :c:type:`int v4l2_close(int fd)` - operates like the standard
+ :ref:`close() <func-close>` function.
+
+- :c:type:`int v4l2_dup(int fd)` - operates like the standard dup() function,
+ duplicating a file handler.
+
+- :c:type:`int v4l2_ioctl (int fd, unsigned long int request, ...)` - operates
+ like the standard :ref:`ioctl() <func-ioctl>` function.
+
+- :c:type:`int v4l2_read (int fd, void* buffer, size_t n)` - operates like the
+ standard :ref:`read() <func-read>` function.
+
+- :c:type:`void v4l2_mmap(void *start, size_t length, int prot, int flags, int
+ fd, int64_t offset);` - operates like the standard
+ :ref:`mmap() <func-mmap>` function.
+
+- :c:type:`int v4l2_munmap(void *_start, size_t length);` - operates like the
+ standard :ref:`munmap() <func-munmap>` function.
+
+Those functions provide additional control:
+
+- :c:type:`int v4l2_fd_open(int fd, int v4l2_flags)` - opens an already opened
+ fd for further use through v4l2lib and possibly modify libv4l2's
+ default behavior through the v4l2_flags argument. Currently,
+ v4l2_flags can be ``V4L2_DISABLE_CONVERSION``, to disable format
+ conversion.
+
+- :c:type:`int v4l2_set_control(int fd, int cid, int value)` - This function
+ takes a value of 0 - 65535, and then scales that range to the actual
+ range of the given v4l control id, and then if the cid exists and is
+ not locked sets the cid to the scaled value.
+
+- :c:type:`int v4l2_get_control(int fd, int cid)` - This function returns a
+ value of 0 - 65535, scaled to from the actual range of the given v4l
+ control id. when the cid does not exist, could not be accessed for
+ some reason, or some error occurred 0 is returned.
+
+
+v4l1compat.so wrapper library
+=============================
+
+This library intercepts calls to open/close/ioctl/mmap/mmunmap
+operations and redirects them to the libv4l counterparts, by using
+LD_PRELOAD=/usr/lib/v4l1compat.so. It also emulates V4L1 calls via V4L2
+API.
+
+It allows usage of binary legacy applications that still don't use
+libv4l.
diff --git a/Documentation/media/uapi/v4l/libv4l.rst b/Documentation/media/uapi/v4l/libv4l.rst
new file mode 100644
index 000000000000..332c1d42688b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/libv4l.rst
@@ -0,0 +1,13 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _libv4l:
+
+************************
+Libv4l Userspace Library
+************************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ libv4l-introduction
diff --git a/Documentation/media/uapi/v4l/mmap.rst b/Documentation/media/uapi/v4l/mmap.rst
new file mode 100644
index 000000000000..2171b18c1aab
--- /dev/null
+++ b/Documentation/media/uapi/v4l/mmap.rst
@@ -0,0 +1,280 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _mmap:
+
+******************************
+Streaming I/O (Memory Mapping)
+******************************
+
+Input and output devices support this I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl is set. There are two
+streaming methods, to determine if the memory mapping flavor is
+supported applications must call the
+:ref:`VIDIOC_REQBUFS` ioctl.
+
+Streaming is an I/O method where only pointers to buffers are exchanged
+between application and driver, the data itself is not copied. Memory
+mapping is primarily intended to map buffers in device memory into the
+application's address space. Device memory can be for example the video
+memory on a graphics card with a video capture add-on. However, being
+the most efficient I/O method available for a long time, many other
+drivers support streaming as well, allocating buffers in DMA-able main
+memory.
+
+A driver can support many sets of buffers. Each set is identified by a
+unique buffer type value. The sets are independent and each set can hold
+a different type of data. To access different sets at the same time
+different file descriptors must be used. [1]_
+
+To allocate device buffers applications call the
+:ref:`VIDIOC_REQBUFS` ioctl with the desired number
+of buffers and buffer type, for example ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
+This ioctl can also be used to change the number of buffers or to free
+the allocated memory, provided none of the buffers are still mapped.
+
+Before applications can access the buffers they must map them into their
+address space with the :ref:`mmap() <func-mmap>` function. The
+location of the buffers in device memory can be determined with the
+:ref:`VIDIOC_QUERYBUF` ioctl. In the single-planar
+API case, the ``m.offset`` and ``length`` returned in a struct
+:ref:`v4l2_buffer <v4l2-buffer>` are passed as sixth and second
+parameter to the :ref:`mmap() <func-mmap>` function. When using the
+multi-planar API, struct :ref:`v4l2_buffer <v4l2-buffer>` contains an
+array of struct :ref:`v4l2_plane <v4l2-plane>` structures, each
+containing its own ``m.offset`` and ``length``. When using the
+multi-planar API, every plane of every buffer has to be mapped
+separately, so the number of calls to :ref:`mmap() <func-mmap>` should
+be equal to number of buffers times number of planes in each buffer. The
+offset and length values must not be modified. Remember, the buffers are
+allocated in physical memory, as opposed to virtual memory, which can be
+swapped out to disk. Applications should free the buffers as soon as
+possible with the :ref:`munmap() <func-munmap>` function.
+
+
+.. code-block:: c
+ :caption: Example 3.1. Mapping buffers in the single-planar API
+
+ struct v4l2_requestbuffers reqbuf;
+ struct {
+ void *start;
+ size_t length;
+ } *buffers;
+ unsigned int i;
+
+ memset(&reqbuf, 0, sizeof(reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_MMAP;
+ reqbuf.count = 20;
+
+ if (-1 == ioctl (fd, VIDIOC_REQBUFS, &reqbuf)) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+ /* We want at least five buffers. */
+
+ if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(reqbuf.count, sizeof(*buffers));
+ assert(buffers != NULL);
+
+ for (i = 0; i < reqbuf.count; i++) {
+ struct v4l2_buffer buffer;
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+
+ if (-1 == ioctl (fd, VIDIOC_QUERYBUF, &buffer)) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers[i].length = buffer.length; /* remember for munmap() */
+
+ buffers[i].start = mmap(NULL, buffer.length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.offset);
+
+ if (MAP_FAILED == buffers[i].start) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ /* Cleanup. */
+
+ for (i = 0; i < reqbuf.count; i++)
+ munmap(buffers[i].start, buffers[i].length);
+
+
+.. code-block:: c
+ :caption: Example 3.2. Mapping buffers in the multi-planar API
+
+ struct v4l2_requestbuffers reqbuf;
+ /* Our current format uses 3 planes per buffer */
+ #define FMT_NUM_PLANES = 3
+
+ struct {
+ void *start[FMT_NUM_PLANES];
+ size_t length[FMT_NUM_PLANES];
+ } *buffers;
+ unsigned int i, j;
+
+ memset(&reqbuf, 0, sizeof(reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
+ reqbuf.memory = V4L2_MEMORY_MMAP;
+ reqbuf.count = 20;
+
+ if (ioctl(fd, VIDIOC_REQBUFS, &reqbuf) < 0) {
+ if (errno == EINVAL)
+ printf("Video capturing or mmap-streaming is not supported\\n");
+ else
+ perror("VIDIOC_REQBUFS");
+
+ exit(EXIT_FAILURE);
+ }
+
+ /* We want at least five buffers. */
+
+ if (reqbuf.count < 5) {
+ /* You may need to free the buffers here. */
+ printf("Not enough buffer memory\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ buffers = calloc(reqbuf.count, sizeof(*buffers));
+ assert(buffers != NULL);
+
+ for (i = 0; i < reqbuf.count; i++) {
+ struct v4l2_buffer buffer;
+ struct v4l2_plane planes[FMT_NUM_PLANES];
+
+ memset(&buffer, 0, sizeof(buffer));
+ buffer.type = reqbuf.type;
+ buffer.memory = V4L2_MEMORY_MMAP;
+ buffer.index = i;
+ /* length in struct v4l2_buffer in multi-planar API stores the size
+ * of planes array. */
+ buffer.length = FMT_NUM_PLANES;
+ buffer.m.planes = planes;
+
+ if (ioctl(fd, VIDIOC_QUERYBUF, &buffer) < 0) {
+ perror("VIDIOC_QUERYBUF");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Every plane has to be mapped separately */
+ for (j = 0; j < FMT_NUM_PLANES; j++) {
+ buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
+
+ buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
+ PROT_READ | PROT_WRITE, /* recommended */
+ MAP_SHARED, /* recommended */
+ fd, buffer.m.planes[j].m.offset);
+
+ if (MAP_FAILED == buffers[i].start[j]) {
+ /* If you do not exit here you should unmap() and free()
+ the buffers and planes mapped so far. */
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+ }
+
+ /* Cleanup. */
+
+ for (i = 0; i < reqbuf.count; i++)
+ for (j = 0; j < FMT_NUM_PLANES; j++)
+ munmap(buffers[i].start[j], buffers[i].length[j]);
+
+Conceptually streaming drivers maintain two buffer queues, an incoming
+and an outgoing queue. They separate the synchronous capture or output
+operation locked to a video clock from the application which is subject
+to random disk or network delays and preemption by other processes,
+thereby reducing the probability of data loss. The queues are organized
+as FIFOs, buffers will be output in the order enqueued in the incoming
+FIFO, and were captured in the order dequeued from the outgoing FIFO.
+
+The driver may require a minimum number of buffers enqueued at all times
+to function, apart of this no limit exists on the number of buffers
+applications can enqueue in advance, or dequeue and process. They can
+also enqueue in a different order than buffers have been dequeued, and
+the driver can *fill* enqueued *empty* buffers in any order. [2]_ The
+index number of a buffer (struct :ref:`v4l2_buffer <v4l2-buffer>`
+``index``) plays no role here, it only identifies the buffer.
+
+Initially all mapped buffers are in dequeued state, inaccessible by the
+driver. For capturing applications it is customary to first enqueue all
+mapped buffers, then to start capturing and enter the read loop. Here
+the application waits until a filled buffer can be dequeued, and
+re-enqueues the buffer when the data is no longer needed. Output
+applications fill and enqueue buffers, when enough buffers are stacked
+up the output is started with :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`.
+In the write loop, when the application runs out of free buffers, it
+must wait until an empty buffer can be dequeued and reused.
+
+To enqueue and dequeue a buffer applications use the :ref:`VIDIOC_QBUF`
+and :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The status of a buffer
+being mapped, enqueued, full or empty can be determined at any time
+using the :ref:`VIDIOC_QUERYBUF` ioctl. Two methods exist to suspend
+execution of the application until one or more buffers can be dequeued.
+By default :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` blocks when no buffer is
+in the outgoing queue. When the ``O_NONBLOCK`` flag was given to the
+:ref:`open() <func-open>` function, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`
+returns immediately with an ``EAGAIN`` error code when no buffer is
+available. The :ref:`select() <func-select>` or :ref:`poll()
+<func-poll>` functions are always available.
+
+To start and stop capturing or output applications call the
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and :ref:`VIDIOC_STREAMOFF
+<VIDIOC_STREAMON>` ioctl. Note :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+removes all buffers from both queues as a side effect. Since there is
+no notion of doing anything "now" on a multitasking system, if an
+application needs to synchronize with another event it should examine
+the struct ::ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured
+or outputted buffers.
+
+Drivers implementing memory mapping I/O must support the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QUERYBUF
+<VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF
+<VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the :ref:`mmap()
+<func-mmap>`, :ref:`munmap() <func-munmap>`, :ref:`select()
+<func-select>` and :ref:`poll() <func-poll>` function. [3]_
+
+[capture example]
+
+.. [1]
+ One could use one file descriptor and set the buffer type field
+ accordingly when calling :ref:`VIDIOC_QBUF` etc.,
+ but it makes the :ref:`select() <func-select>` function ambiguous. We also
+ like the clean approach of one file descriptor per logical stream.
+ Video overlay for example is also a logical stream, although the CPU
+ is not needed for continuous operation.
+
+.. [2]
+ Random enqueue order permits applications processing images out of
+ order (such as video codecs) to return buffers earlier, reducing the
+ probability of data loss. Random fill order allows drivers to reuse
+ buffers on a LIFO-basis, taking advantage of caches holding
+ scatter-gather lists and the like.
+
+.. [3]
+ At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
+ the same, and :ref:`select() <func-select>` is too important to be optional.
+ The rest should be evident.
diff --git a/Documentation/media/uapi/v4l/open.rst b/Documentation/media/uapi/v4l/open.rst
new file mode 100644
index 000000000000..a3e39df91e9d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/open.rst
@@ -0,0 +1,158 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _open:
+
+***************************
+Opening and Closing Devices
+***************************
+
+
+Device Naming
+=============
+
+V4L2 drivers are implemented as kernel modules, loaded manually by the
+system administrator or automatically when a device is first discovered.
+The driver modules plug into the "videodev" kernel module. It provides
+helper functions and a common application interface specified in this
+document.
+
+Each driver thus loaded registers one or more device nodes with major
+number 81 and a minor number between 0 and 255. Minor numbers are
+allocated dynamically unless the kernel is compiled with the kernel
+option CONFIG_VIDEO_FIXED_MINOR_RANGES. In that case minor numbers
+are allocated in ranges depending on the device node type (video, radio,
+etc.).
+
+Many drivers support "video_nr", "radio_nr" or "vbi_nr" module
+options to select specific video/radio/vbi node numbers. This allows the
+user to request that the device node is named e.g. /dev/video5 instead
+of leaving it to chance. When the driver supports multiple devices of
+the same type more than one device node number can be assigned,
+separated by commas:
+
+.. code-block:: none
+
+ # modprobe mydriver video_nr=0,1 radio_nr=0,1
+
+In ``/etc/modules.conf`` this may be written as:
+
+::
+
+ options mydriver video_nr=0,1 radio_nr=0,1
+
+When no device node number is given as module option the driver supplies
+a default.
+
+Normally udev will create the device nodes in /dev automatically for
+you. If udev is not installed, then you need to enable the
+CONFIG_VIDEO_FIXED_MINOR_RANGES kernel option in order to be able to
+correctly relate a minor number to a device node number. I.e., you need
+to be certain that minor number 5 maps to device node name video5. With
+this kernel option different device types have different minor number
+ranges. These ranges are listed in :ref:`devices`.
+
+The creation of character special files (with mknod) is a privileged
+operation and devices cannot be opened by major and minor number. That
+means applications cannot *reliable* scan for loaded or installed
+drivers. The user must enter a device name, or the application can try
+the conventional device names.
+
+
+.. _related:
+
+Related Devices
+===============
+
+Devices can support several functions. For example video capturing, VBI
+capturing and radio support.
+
+The V4L2 API creates different nodes for each of these functions.
+
+The V4L2 API was designed with the idea that one device node could
+support all functions. However, in practice this never worked: this
+'feature' was never used by applications and many drivers did not
+support it and if they did it was certainly never tested. In addition,
+switching a device node between different functions only works when
+using the streaming I/O API, not with the
+:ref:`read() <func-read>`/\ :ref:`write() <func-write>` API.
+
+Today each device node supports just one function.
+
+Besides video input or output the hardware may also support audio
+sampling or playback. If so, these functions are implemented as ALSA PCM
+devices with optional ALSA audio mixer devices.
+
+One problem with all these devices is that the V4L2 API makes no
+provisions to find these related devices. Some really complex devices
+use the Media Controller (see :ref:`media_controller`) which can be
+used for this purpose. But most drivers do not use it, and while some
+code exists that uses sysfs to discover related devices (see
+libmedia_dev in the
+`v4l-utils <http://git.linuxtv.org/cgit.cgi/v4l-utils.git/>`__ git
+repository), there is no library yet that can provide a single API
+towards both Media Controller-based devices and devices that do not use
+the Media Controller. If you want to work on this please write to the
+linux-media mailing list:
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
+
+
+Multiple Opens
+==============
+
+V4L2 devices can be opened more than once. [1]_ When this is supported
+by the driver, users can for example start a "panel" application to
+change controls like brightness or audio volume, while another
+application captures video and audio. In other words, panel applications
+are comparable to an ALSA audio mixer application. Just opening a V4L2
+device should not change the state of the device. [2]_
+
+Once an application has allocated the memory buffers needed for
+streaming data (by calling the :ref:`VIDIOC_REQBUFS`
+or :ref:`VIDIOC_CREATE_BUFS` ioctls, or
+implicitly by calling the :ref:`read() <func-read>` or
+:ref:`write() <func-write>` functions) that application (filehandle)
+becomes the owner of the device. It is no longer allowed to make changes
+that would affect the buffer sizes (e.g. by calling the
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl) and other applications are
+no longer allowed to allocate buffers or start or stop streaming. The
+EBUSY error code will be returned instead.
+
+Merely opening a V4L2 device does not grant exclusive access. [3]_
+Initiating data exchange however assigns the right to read or write the
+requested type of data, and to change related properties, to this file
+descriptor. Applications can request additional access privileges using
+the priority mechanism described in :ref:`app-pri`.
+
+
+Shared Data Streams
+===================
+
+V4L2 drivers should not support multiple applications reading or writing
+the same data stream on a device by copying buffers, time multiplexing
+or similar means. This is better handled by a proxy application in user
+space.
+
+
+Functions
+=========
+
+To open and close V4L2 devices applications use the
+:ref:`open() <func-open>` and :ref:`close() <func-close>` function,
+respectively. Devices are programmed using the
+:ref:`ioctl() <func-ioctl>` function as explained in the following
+sections.
+
+.. [1]
+ There are still some old and obscure drivers that have not been
+ updated to allow for multiple opens. This implies that for such
+ drivers :ref:`open() <func-open>` can return an ``EBUSY`` error code
+ when the device is already in use.
+
+.. [2]
+ Unfortunately, opening a radio device often switches the state of the
+ device to radio mode in many drivers. This behavior should be fixed
+ eventually as it violates the V4L2 specification.
+
+.. [3]
+ Drivers could recognize the ``O_EXCL`` open flag. Presently this is
+ not required, so applications cannot know if it really works.
diff --git a/Documentation/media/uapi/v4l/pixfmt-002.rst b/Documentation/media/uapi/v4l/pixfmt-002.rst
new file mode 100644
index 000000000000..fae9b2d40a85
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-002.rst
@@ -0,0 +1,196 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Single-planar format structure
+******************************
+
+
+.. _v4l2-pix-format:
+
+.. flat-table:: struct v4l2_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height in pixels. If ``field`` is one of ``V4L2_FIELD_TOP``,
+ ``V4L2_FIELD_BOTTOM`` or ``V4L2_FIELD_ALTERNATE`` then height
+ refers to the number of lines in the field, otherwise it refers to
+ the number of lines in the frame (which is twice the field height
+ for interlaced formats).
+
+ - .. row 3
+
+ - :cspan:`2` Applications set these fields to request an image
+ size, drivers return the closest possible values. In case of
+ planar formats the ``width`` and ``height`` applies to the largest
+ plane. To avoid ambiguities drivers must return values rounded up
+ to a multiple of the scale factor of any smaller planes. For
+ example when the image format is YUV 4:2:0, ``width`` and
+ ``height`` must be multiples of two.
+
+ - .. row 4
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format or type of compression, set by the application.
+ This is a little endian
+ :ref:`four character code <v4l2-fourcc>`. V4L2 defines standard
+ RGB formats in :ref:`rgb-formats`, YUV formats in
+ :ref:`yuv-formats`, and reserved codes in
+ :ref:`reserved-formats`
+
+ - .. row 5
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - Video images are typically interlaced. Applications can request to
+ capture or output only the top or bottom field, or both fields
+ interlaced or sequentially stored in one buffer or alternating in
+ separate buffers. Drivers return the actual field order selected.
+ For more details on fields see :ref:`field-order`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+
+ - .. row 7
+
+ - :cspan:`2`
+
+ Both applications and drivers can set this field to request
+ padding bytes at the end of each line. Drivers however may ignore
+ the value requested by the application, returning ``width`` times
+ bytes per pixel or a larger value required by the hardware. That
+ implies applications can just set this field to zero to get a
+ reasonable default.
+
+ Video hardware may access padding bytes, therefore they must
+ reside in accessible memory. Consider cases where padding bytes
+ after the last line of an image cross a system page boundary.
+ Input devices may write padding bytes, the value is undefined.
+ Output devices ignore the contents of padding bytes.
+
+ When the image format is planar the ``bytesperline`` value applies
+ to the first plane and is divided by the same factor as the
+ ``width`` field for the other planes. For example the Cb and Cr
+ planes of a YUV 4:2:0 image have half as many padding bytes
+ following each line as the Y plane. To avoid ambiguities drivers
+ must return a ``bytesperline`` value rounded up to a multiple of
+ the scale factor.
+
+ For compressed formats the ``bytesperline`` value makes no sense.
+ Applications and drivers must set this to 0 in that case.
+
+ - .. row 8
+
+ - __u32
+
+ - ``sizeimage``
+
+ - Size in bytes of the buffer to hold a complete image, set by the
+ driver. Usually this is ``bytesperline`` times ``height``. When
+ the image consists of variable length compressed data this is the
+ maximum number of bytes required to hold an image.
+
+ - .. row 9
+
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - This information supplements the ``pixelformat`` and must be set
+ by the driver for capture streams and by the application for
+ output streams, see :ref:`colorspaces`.
+
+ - .. row 10
+
+ - __u32
+
+ - ``priv``
+
+ - This field indicates whether the remaining fields of the
+ :ref:`struct v4l2_pix_format <v4l2-pix-format>` structure, also called the
+ extended fields, are valid. When set to
+ ``V4L2_PIX_FMT_PRIV_MAGIC``, it indicates that the extended fields
+ have been correctly initialized. When set to any other value it
+ indicates that the extended fields contain undefined values.
+
+ Applications that wish to use the pixel format extended fields
+ must first ensure that the feature is supported by querying the
+ device for the :ref:`V4L2_CAP_EXT_PIX_FORMAT <querycap>`
+ capability. If the capability isn't set the pixel format extended
+ fields are not supported and using the extended fields will lead
+ to undefined results.
+
+ To use the extended fields, applications must set the ``priv``
+ field to ``V4L2_PIX_FMT_PRIV_MAGIC``, initialize all the extended
+ fields and zero the unused bytes of the
+ :ref:`struct v4l2_format <v4l2-format>` ``raw_data`` field.
+
+ When the ``priv`` field isn't set to ``V4L2_PIX_FMT_PRIV_MAGIC``
+ drivers must act as if all the extended fields were set to zero.
+ On return drivers must set the ``priv`` field to
+ ``V4L2_PIX_FMT_PRIV_MAGIC`` and all the extended fields to
+ applicable values.
+
+ - .. row 11
+
+ - __u32
+
+ - ``flags``
+
+ - Flags set by the application or driver, see :ref:`format-flags`.
+
+ - .. row 12
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 13
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``quantization``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 14
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``xfer_func``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
diff --git a/Documentation/media/uapi/v4l/pixfmt-003.rst b/Documentation/media/uapi/v4l/pixfmt-003.rst
new file mode 100644
index 000000000000..25c54872fbe1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-003.rst
@@ -0,0 +1,166 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+******************************
+Multi-planar format structures
+******************************
+
+The :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures define size
+and layout for each of the planes in a multi-planar format. The
+:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structure contains
+information common to all planes (such as image width and height) and an
+array of :ref:`struct v4l2_plane_pix_format <v4l2-plane-pix-format>` structures,
+describing all planes of that format.
+
+
+.. _v4l2-plane-pix-format:
+
+.. flat-table:: struct v4l2_plane_pix_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``sizeimage``
+
+ - Maximum size in bytes required for image data in this plane.
+
+ - .. row 2
+
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines. See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 3
+
+ - __u16
+
+ - ``reserved[6]``
+
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
+
+
+
+.. _v4l2-pix-format-mplane:
+
+.. flat-table:: struct v4l2_pix_format_mplane
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width in pixels. See struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height in pixels. See struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format. Both single- and multi-planar four character
+ codes can be used.
+
+ - .. row 4
+
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 5
+
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - See struct :ref:`v4l2_pix_format <v4l2-pix-format>`.
+
+ - .. row 6
+
+ - struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`
+
+ - ``plane_fmt[VIDEO_MAX_PLANES]``
+
+ - An array of structures describing format of each plane this pixel
+ format consists of. The number of valid entries in this array has
+ to be put in the ``num_planes`` field.
+
+ - .. row 7
+
+ - __u8
+
+ - ``num_planes``
+
+ - Number of planes (i.e. separate memory buffers) for this format
+ and the number of valid entries in the ``plane_fmt`` array.
+
+ - .. row 8
+
+ - __u8
+
+ - ``flags``
+
+ - Flags set by the application or driver, see :ref:`format-flags`.
+
+ - .. row 9
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 10
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``quantization``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 11
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``xfer_func``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 12
+
+ - __u8
+
+ - ``reserved[7]``
+
+ - Reserved for future extensions. Should be zeroed by drivers and
+ applications.
diff --git a/Documentation/media/uapi/v4l/pixfmt-004.rst b/Documentation/media/uapi/v4l/pixfmt-004.rst
new file mode 100644
index 000000000000..4bc116aa8193
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-004.rst
@@ -0,0 +1,51 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+**********************
+Standard Image Formats
+**********************
+
+In order to exchange images between drivers and applications, it is
+necessary to have standard image data formats which both sides will
+interpret the same way. V4L2 includes several such formats, and this
+section is intended to be an unambiguous specification of the standard
+image data formats in V4L2.
+
+V4L2 drivers are not limited to these formats, however. Driver-specific
+formats are possible. In that case the application may depend on a codec
+to convert images to one of the standard formats when needed. But the
+data can still be stored and retrieved in the proprietary format. For
+example, a device may support a proprietary compressed format.
+Applications can still capture and save the data in the compressed
+format, saving much disk space, and later use a codec to convert the
+images to the X Windows screen format when the video is to be displayed.
+
+Even so, ultimately, some standard formats are needed, so the V4L2
+specification would not be complete without well-defined standard
+formats.
+
+The V4L2 standard formats are mainly uncompressed formats. The pixels
+are always arranged in memory from left to right, and from top to
+bottom. The first byte of data in the image buffer is always for the
+leftmost pixel of the topmost row. Following that is the pixel
+immediately to its right, and so on until the end of the top row of
+pixels. Following the rightmost pixel of the row there may be zero or
+more bytes of padding to guarantee that each row of pixel data has a
+certain alignment. Following the pad bytes, if any, is data for the
+leftmost pixel of the second row from the top, and so on. The last row
+has just as many pad bytes after it as the other rows.
+
+In V4L2 each format has an identifier which looks like ``PIX_FMT_XXX``,
+defined in the :ref:`videodev2.h <videodev>` header file. These
+identifiers represent
+:ref:`four character (FourCC) codes <v4l2-fourcc>` which are also
+listed below, however they are not the same as those used in the Windows
+world.
+
+For some formats, data is stored in separate, discontiguous memory
+buffers. Those formats are identified by a separate set of FourCC codes
+and are referred to as "multi-planar formats". For example, a
+:ref:`YUV422 <V4L2-PIX-FMT-YUV422M>` frame is normally stored in one
+memory buffer, but it can also be placed in two or three separate
+buffers, with Y component in one buffer and CbCr components in another
+in the 2-planar version or with each component in its own buffer in the
+3-planar case. Those sub-buffers are referred to as "*planes*".
diff --git a/Documentation/media/uapi/v4l/pixfmt-006.rst b/Documentation/media/uapi/v4l/pixfmt-006.rst
new file mode 100644
index 000000000000..b9e7c6844020
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-006.rst
@@ -0,0 +1,280 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+****************************
+Defining Colorspaces in V4L2
+****************************
+
+In V4L2 colorspaces are defined by four values. The first is the
+colorspace identifier (enum :ref:`v4l2_colorspace <v4l2-colorspace>`)
+which defines the chromaticities, the default transfer function, the
+default Y'CbCr encoding and the default quantization method. The second
+is the transfer function identifier (enum
+:ref:`v4l2_xfer_func <v4l2-xfer-func>`) to specify non-standard
+transfer functions. The third is the Y'CbCr encoding identifier (enum
+:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`) to specify
+non-standard Y'CbCr encodings and the fourth is the quantization
+identifier (enum :ref:`v4l2_quantization <v4l2-quantization>`) to
+specify non-standard quantization methods. Most of the time only the
+colorspace field of struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+or struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
+needs to be filled in. Note that the default R'G'B' quantization is full
+range for all colorspaces except for BT.2020 which uses limited range
+R'G'B' quantization.
+
+
+.. _v4l2-colorspace:
+
+.. flat-table:: V4L2 Colorspaces
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_COLORSPACE_DEFAULT``
+
+ - The default colorspace. This can be used by applications to let
+ the driver fill in the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_COLORSPACE_SMPTE170M``
+
+ - See :ref:`col-smpte-170m`.
+
+ - .. row 4
+
+ - ``V4L2_COLORSPACE_REC709``
+
+ - See :ref:`col-rec709`.
+
+ - .. row 5
+
+ - ``V4L2_COLORSPACE_SRGB``
+
+ - See :ref:`col-srgb`.
+
+ - .. row 6
+
+ - ``V4L2_COLORSPACE_ADOBERGB``
+
+ - See :ref:`col-adobergb`.
+
+ - .. row 7
+
+ - ``V4L2_COLORSPACE_BT2020``
+
+ - See :ref:`col-bt2020`.
+
+ - .. row 8
+
+ - ``V4L2_COLORSPACE_DCI_P3``
+
+ - See :ref:`col-dcip3`.
+
+ - .. row 9
+
+ - ``V4L2_COLORSPACE_SMPTE240M``
+
+ - See :ref:`col-smpte-240m`.
+
+ - .. row 10
+
+ - ``V4L2_COLORSPACE_470_SYSTEM_M``
+
+ - See :ref:`col-sysm`.
+
+ - .. row 11
+
+ - ``V4L2_COLORSPACE_470_SYSTEM_BG``
+
+ - See :ref:`col-sysbg`.
+
+ - .. row 12
+
+ - ``V4L2_COLORSPACE_JPEG``
+
+ - See :ref:`col-jpeg`.
+
+ - .. row 13
+
+ - ``V4L2_COLORSPACE_RAW``
+
+ - The raw colorspace. This is used for raw image capture where the
+ image is minimally processed and is using the internal colorspace
+ of the device. The software that processes an image using this
+ 'colorspace' will have to know the internals of the capture
+ device.
+
+
+
+.. _v4l2-xfer-func:
+
+.. flat-table:: V4L2 Transfer Function
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_XFER_FUNC_DEFAULT``
+
+ - Use the default transfer function as defined by the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_XFER_FUNC_709``
+
+ - Use the Rec. 709 transfer function.
+
+ - .. row 4
+
+ - ``V4L2_XFER_FUNC_SRGB``
+
+ - Use the sRGB transfer function.
+
+ - .. row 5
+
+ - ``V4L2_XFER_FUNC_ADOBERGB``
+
+ - Use the AdobeRGB transfer function.
+
+ - .. row 6
+
+ - ``V4L2_XFER_FUNC_SMPTE240M``
+
+ - Use the SMPTE 240M transfer function.
+
+ - .. row 7
+
+ - ``V4L2_XFER_FUNC_NONE``
+
+ - Do not use a transfer function (i.e. use linear RGB values).
+
+ - .. row 8
+
+ - ``V4L2_XFER_FUNC_DCI_P3``
+
+ - Use the DCI-P3 transfer function.
+
+ - .. row 9
+
+ - ``V4L2_XFER_FUNC_SMPTE2084``
+
+ - Use the SMPTE 2084 transfer function.
+
+
+
+.. _v4l2-ycbcr-encoding:
+
+.. flat-table:: V4L2 Y'CbCr Encodings
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_YCBCR_ENC_DEFAULT``
+
+ - Use the default Y'CbCr encoding as defined by the colorspace.
+
+ - .. row 3
+
+ - ``V4L2_YCBCR_ENC_601``
+
+ - Use the BT.601 Y'CbCr encoding.
+
+ - .. row 4
+
+ - ``V4L2_YCBCR_ENC_709``
+
+ - Use the Rec. 709 Y'CbCr encoding.
+
+ - .. row 5
+
+ - ``V4L2_YCBCR_ENC_XV601``
+
+ - Use the extended gamut xvYCC BT.601 encoding.
+
+ - .. row 6
+
+ - ``V4L2_YCBCR_ENC_XV709``
+
+ - Use the extended gamut xvYCC Rec. 709 encoding.
+
+ - .. row 7
+
+ - ``V4L2_YCBCR_ENC_SYCC``
+
+ - Use the extended gamut sYCC encoding.
+
+ - .. row 8
+
+ - ``V4L2_YCBCR_ENC_BT2020``
+
+ - Use the default non-constant luminance BT.2020 Y'CbCr encoding.
+
+ - .. row 9
+
+ - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM``
+
+ - Use the constant luminance BT.2020 Yc'CbcCrc encoding.
+
+
+
+.. _v4l2-quantization:
+
+.. flat-table:: V4L2 Quantization Methods
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Details
+
+ - .. row 2
+
+ - ``V4L2_QUANTIZATION_DEFAULT``
+
+ - Use the default quantization encoding as defined by the
+ colorspace. This is always full range for R'G'B' (except for the
+ BT.2020 colorspace) and usually limited range for Y'CbCr.
+
+ - .. row 3
+
+ - ``V4L2_QUANTIZATION_FULL_RANGE``
+
+ - Use the full range quantization encoding. I.e. the range [0…1] is
+ mapped to [0…255] (with possible clipping to [1…254] to avoid the
+ 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to
+ [0…255] (with possible clipping to [1…254] to avoid the 0x00 and
+ 0xff values).
+
+ - .. row 4
+
+ - ``V4L2_QUANTIZATION_LIM_RANGE``
+
+ - Use the limited range quantization encoding. I.e. the range [0…1]
+ is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to
+ [16…240].
diff --git a/Documentation/media/uapi/v4l/pixfmt-007.rst b/Documentation/media/uapi/v4l/pixfmt-007.rst
new file mode 100644
index 000000000000..5e39cda6147a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-007.rst
@@ -0,0 +1,894 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+********************************
+Detailed Colorspace Descriptions
+********************************
+
+
+.. _col-smpte-170m:
+
+Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M)
+=================================================
+
+The :ref:`smpte170m` standard defines the colorspace used by NTSC and
+PAL and by SDTV in general. The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. flat-table:: SMPTE 170M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.630
+
+ - 0.340
+
+ - .. row 3
+
+ - Green
+
+ - 0.310
+
+ - 0.595
+
+ - .. row 4
+
+ - Blue
+
+ - 0.155
+
+ - 0.070
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+The red, green and blue chromaticities are also often referred to as the
+SMPTE C set, so this colorspace is sometimes called SMPTE C as well.
+
+The transfer function defined for SMPTE 170M is the same as the one
+defined in Rec. 709.
+
+ L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018
+
+ L' = 4.5L for -0.018 < L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018
+
+Inverse Transfer function:
+
+ L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081
+
+ L = L' / 4.5 for -0.081 < L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in
+the :ref:`itu601` standard and this colorspace is sometimes called
+BT.601 as well, even though BT.601 does not mention any color primaries.
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+
+.. _col-rec709:
+
+Colorspace Rec. 709 (V4L2_COLORSPACE_REC709)
+============================================
+
+The :ref:`itu709` standard defines the colorspace used by HDTV in
+general. The default transfer function is ``V4L2_XFER_FUNC_709``. The
+default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr
+quantization is limited range. The chromaticities of the primary colors
+and the white reference are:
+
+
+
+.. flat-table:: Rec. 709 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.640
+
+ - 0.330
+
+ - .. row 3
+
+ - Green
+
+ - 0.300
+
+ - 0.600
+
+ - .. row 4
+
+ - Blue
+
+ - 0.150
+
+ - 0.060
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+The full name of this standard is Rec. ITU-R BT.709-5.
+
+Transfer function. Normally L is in the range [0…1], but for the
+extended gamut xvYCC encoding values outside that range are allowed.
+
+ L' = -1.099(-L) :sup:`0.45` + 0.099 for L ≤ -0.018
+
+ L' = 4.5L for -0.018 < L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for L ≥ 0.018
+
+Inverse Transfer function:
+
+ L = -((L' - 0.099) / -1.099) :sup:`1/0.45` for L' ≤ -0.081
+
+ L = L' / 4.5 for -0.081 < L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_709`` encoding:
+
+ Y' = 0.2126R' + 0.7152G' + 0.0722B'
+
+ Cb = -0.1146R' - 0.3854G' + 0.5B'
+
+ Cr = 0.5R' - 0.4542G' - 0.0458B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5].
+
+The default quantization is limited range, but full range is possible
+although rarely seen.
+
+The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for
+this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``,
+in which case the BT.601 Y'CbCr encoding is used.
+
+Two additional extended gamut Y'CbCr encodings are also possible with
+this colorspace:
+
+The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is
+similar to the Rec. 709 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset:
+
+ Y' = (219 / 256) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 256)
+
+ Cb = (224 / 256) * (-0.1146R' - 0.3854G' + 0.5B')
+
+ Cr = (224 / 256) * (0.5R' - 0.4542G' - 0.0458B')
+
+The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is
+similar to the BT.601 encoding, but it allows for R', G' and B' values
+that are outside the range [0…1]. The resulting Y', Cb and Cr values are
+scaled and offset:
+
+ Y' = (219 / 256) * (0.299R' + 0.587G' + 0.114B') + (16 / 256)
+
+ Cb = (224 / 256) * (-0.169R' - 0.331G' + 0.5B')
+
+ Cr = (224 / 256) * (0.5R' - 0.419G' - 0.081B')
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The non-standard xvYCC 709 or xvYCC 601 encodings can be
+used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``.
+The xvYCC encodings always use full range quantization.
+
+
+.. _col-srgb:
+
+Colorspace sRGB (V4L2_COLORSPACE_SRGB)
+======================================
+
+The :ref:`srgb` standard defines the colorspace used by most webcams
+and computer graphics. The default transfer function is
+``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_SYCC``. The default Y'CbCr quantization is full range.
+The chromaticities of the primary colors and the white reference are:
+
+
+
+.. flat-table:: sRGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.640
+
+ - 0.330
+
+ - .. row 3
+
+ - Green
+
+ - 0.300
+
+ - 0.600
+
+ - .. row 4
+
+ - Blue
+
+ - 0.150
+
+ - 0.060
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+These chromaticities are identical to the Rec. 709 colorspace.
+
+Transfer function. Note that negative values for L are only used by the
+Y'CbCr conversion.
+
+ L' = -1.055(-L) :sup:`1/2.4` + 0.055 for L < -0.0031308
+
+ L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308
+
+ L' = 1.055L :sup:`1/2.4` - 0.055 for 0.0031308 < L ≤ 1
+
+Inverse Transfer function:
+
+ L = -((-L' + 0.055) / 1.055) :sup:`2.4` for L' < -0.04045
+
+ L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045
+
+ L = ((L' + 0.055) / 1.055) :sup:`2.4` for L' > 0.04045
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_SYCC`` encoding as defined by
+:ref:`sycc`:
+
+ Y' = 0.2990R' + 0.5870G' + 0.1140B'
+
+ Cb = -0.1687R' - 0.3313G' + 0.5B'
+
+ Cr = 0.5R' - 0.4187G' - 0.0813B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The ``V4L2_YCBCR_ENC_SYCC`` quantization is always full
+range. Although this Y'CbCr encoding looks very similar to the
+``V4L2_YCBCR_ENC_XV601`` encoding, it is not. The
+``V4L2_YCBCR_ENC_XV601`` scales and offsets the Y'CbCr values before
+quantization, but this encoding does not do that.
+
+
+.. _col-adobergb:
+
+Colorspace Adobe RGB (V4L2_COLORSPACE_ADOBERGB)
+===============================================
+
+The :ref:`adobergb` standard defines the colorspace used by computer
+graphics that use the AdobeRGB colorspace. This is also known as the
+:ref:`oprgb` standard. The default transfer function is
+``V4L2_XFER_FUNC_ADOBERGB``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. flat-table:: Adobe RGB Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.6400
+
+ - 0.3300
+
+ - .. row 3
+
+ - Green
+
+ - 0.2100
+
+ - 0.7100
+
+ - .. row 4
+
+ - Blue
+
+ - 0.1500
+
+ - 0.0600
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+Transfer function:
+
+ L' = L :sup:`1/2.19921875`
+
+Inverse Transfer function:
+
+ L = L' :sup:`2.19921875`
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. This transform is identical to one defined in SMPTE
+170M/BT.601. The Y'CbCr quantization is limited range.
+
+
+.. _col-bt2020:
+
+Colorspace BT.2020 (V4L2_COLORSPACE_BT2020)
+===========================================
+
+The :ref:`itu2020` standard defines the colorspace used by Ultra-high
+definition television (UHDTV). The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited
+range (!), and so is the default Y'CbCr quantization. The chromaticities
+of the primary colors and the white reference are:
+
+
+
+.. flat-table:: BT.2020 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.708
+
+ - 0.292
+
+ - .. row 3
+
+ - Green
+
+ - 0.170
+
+ - 0.797
+
+ - .. row 4
+
+ - Blue
+
+ - 0.131
+
+ - 0.046
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+Transfer function (same as Rec. 709):
+
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_BT2020`` encoding:
+
+ Y' = 0.2627R' + 0.6780G' + 0.0593B'
+
+ Cb = -0.1396R' - 0.3604G' + 0.5B'
+
+ Cr = 0.5R' - 0.4598G' - 0.0402B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+There is also an alternate constant luminance R'G'B' to Yc'CbcCrc
+(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding:
+
+Luma:
+
+ Yc' = (0.2627R + 0.6780G + 0.0593B)'
+
+B' - Yc' ≤ 0:
+
+ Cbc = (B' - Yc') / 1.9404
+
+B' - Yc' > 0:
+
+ Cbc = (B' - Yc') / 1.5816
+
+R' - Yc' ≤ 0:
+
+ Crc = (R' - Y') / 1.7184
+
+R' - Yc' > 0:
+
+ Crc = (R' - Y') / 0.9936
+
+Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
+range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.
+
+
+.. _col-dcip3:
+
+Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3)
+==========================================
+
+The :ref:`smpte431` standard defines the colorspace used by cinema
+projectors that use the DCI-P3 colorspace. The default transfer function
+is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_709``. Note that this colorspace does not specify a
+Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this
+default Y'CbCr encoding was picked because it is the HDTV encoding. The
+default Y'CbCr quantization is limited range. The chromaticities of the
+primary colors and the white reference are:
+
+
+
+.. flat-table:: DCI-P3 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.6800
+
+ - 0.3200
+
+ - .. row 3
+
+ - Green
+
+ - 0.2650
+
+ - 0.6900
+
+ - .. row 4
+
+ - Blue
+
+ - 0.1500
+
+ - 0.0600
+
+ - .. row 5
+
+ - White Reference
+
+ - 0.3140
+
+ - 0.3510
+
+
+
+Transfer function:
+
+ L' = L :sup:`1/2.6`
+
+Inverse Transfer function:
+
+ L = L' :sup:`2.6`
+
+Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709.
+
+
+.. _col-smpte-240m:
+
+Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M)
+=================================================
+
+The :ref:`smpte240m` standard was an interim standard used during the
+early days of HDTV (1988-1998). It has been superseded by Rec. 709. The
+default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default
+Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr
+quantization is limited range. The chromaticities of the primary colors
+and the white reference are:
+
+
+
+.. flat-table:: SMPTE 240M Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.630
+
+ - 0.340
+
+ - .. row 3
+
+ - Green
+
+ - 0.310
+
+ - 0.595
+
+ - .. row 4
+
+ - Blue
+
+ - 0.155
+
+ - 0.070
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+These chromaticities are identical to the SMPTE 170M colorspace.
+
+Transfer function:
+
+ L' = 4L for 0 ≤ L < 0.0228
+
+ L' = 1.1115L :sup:`0.45` - 0.1115 for 0.0228 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4 for 0 ≤ L' < 0.0913
+
+ L = ((L' + 0.1115) / 1.1115) :sup:`1/0.45` for L' ≥ 0.0913
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding:
+
+ Y' = 0.2122R' + 0.7013G' + 0.0865B'
+
+ Cb = -0.1161R' - 0.3839G' + 0.5B'
+
+ Cr = 0.5R' - 0.4451G' - 0.0549B'
+
+Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the
+range [-0.5…0.5]. The Y'CbCr quantization is limited range.
+
+
+.. _col-sysm:
+
+Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M)
+===================================================
+
+This standard defines the colorspace used by NTSC in 1953. In practice
+this colorspace is obsolete and SMPTE 170M should be used instead. The
+default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr
+encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is
+limited range. The chromaticities of the primary colors and the white
+reference are:
+
+
+
+.. flat-table:: NTSC 1953 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.67
+
+ - 0.33
+
+ - .. row 3
+
+ - Green
+
+ - 0.21
+
+ - 0.71
+
+ - .. row 4
+
+ - Blue
+
+ - 0.14
+
+ - 0.08
+
+ - .. row 5
+
+ - White Reference (C)
+
+ - 0.310
+
+ - 0.316
+
+
+Note that this colorspace uses Illuminant C instead of D65 as the white
+reference. To correctly convert an image in this colorspace to another
+that uses D65 you need to apply a chromatic adaptation algorithm such as
+the Bradford method.
+
+The transfer function was never properly defined for NTSC 1953. The Rec.
+709 transfer function is recommended in the literature:
+
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-sysbg:
+
+Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG)
+=========================================================
+
+The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM
+in 1975. In practice this colorspace is obsolete and SMPTE 170M should
+be used instead. The default transfer function is
+``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is
+``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited
+range. The chromaticities of the primary colors and the white reference
+are:
+
+
+
+.. flat-table:: EBU Tech. 3213 Chromaticities
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Color
+
+ - x
+
+ - y
+
+ - .. row 2
+
+ - Red
+
+ - 0.64
+
+ - 0.33
+
+ - .. row 3
+
+ - Green
+
+ - 0.29
+
+ - 0.60
+
+ - .. row 4
+
+ - Blue
+
+ - 0.15
+
+ - 0.06
+
+ - .. row 5
+
+ - White Reference (D65)
+
+ - 0.3127
+
+ - 0.3290
+
+
+
+The transfer function was never properly defined for this colorspace.
+The Rec. 709 transfer function is recommended in the literature:
+
+ L' = 4.5L for 0 ≤ L < 0.018
+
+ L' = 1.099L :sup:`0.45` - 0.099 for 0.018 ≤ L ≤ 1
+
+Inverse Transfer function:
+
+ L = L' / 4.5 for L' < 0.081
+
+ L = ((L' + 0.099) / 1.099) :sup:`1/0.45` for L' ≥ 0.081
+
+The luminance (Y') and color difference (Cb and Cr) are obtained with
+the following ``V4L2_YCBCR_ENC_601`` encoding:
+
+ Y' = 0.299R' + 0.587G' + 0.114B'
+
+ Cb = -0.169R' - 0.331G' + 0.5B'
+
+ Cr = 0.5R' - 0.419G' - 0.081B'
+
+Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range
+[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is
+identical to one defined in SMPTE 170M/BT.601.
+
+
+.. _col-jpeg:
+
+Colorspace JPEG (V4L2_COLORSPACE_JPEG)
+======================================
+
+This colorspace defines the colorspace used by most (Motion-)JPEG
+formats. The chromaticities of the primary colors and the white
+reference are identical to sRGB. The transfer function use is
+``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601``
+with full range quantization where Y' is scaled to [0…255] and Cb/Cr are
+scaled to [-128…128] and then clipped to [-128…127].
+
+Note that the JPEG standard does not actually store colorspace
+information. So if something other than sRGB is used, then the driver
+will have to set that information explicitly. Effectively
+``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for
+``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and
+``V4L2_QUANTIZATION_FULL_RANGE``.
diff --git a/Documentation/media/uapi/v4l/pixfmt-008.rst b/Documentation/media/uapi/v4l/pixfmt-008.rst
new file mode 100644
index 000000000000..4bec79784bdd
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-008.rst
@@ -0,0 +1,32 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+***************************************
+Detailed Transfer Function Descriptions
+***************************************
+
+
+.. _xf-smpte-2084:
+
+Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084)
+=======================================================
+
+The :ref:`smpte2084` standard defines the transfer function used by
+High Dynamic Range content.
+
+Constants:
+ m1 = (2610 / 4096) / 4
+
+ m2 = (2523 / 4096) * 128
+
+ c1 = 3424 / 4096
+
+ c2 = (2413 / 4096) * 32
+
+ c3 = (2392 / 4096) * 32
+
+Transfer function:
+ L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2`
+
+Inverse Transfer function:
+ L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 *
+ L'\ :sup:`1/m2`))\ :sup:`1/m1`
diff --git a/Documentation/media/uapi/v4l/pixfmt-013.rst b/Documentation/media/uapi/v4l/pixfmt-013.rst
new file mode 100644
index 000000000000..475f6e6fe785
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-013.rst
@@ -0,0 +1,129 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+******************
+Compressed Formats
+******************
+
+
+.. _compressed-formats:
+
+.. flat-table:: Compressed Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Details
+
+ - .. _V4L2-PIX-FMT-JPEG:
+
+ - ``V4L2_PIX_FMT_JPEG``
+
+ - 'JPEG'
+
+ - TBD. See also :ref:`VIDIOC_G_JPEGCOMP <VIDIOC_G_JPEGCOMP>`,
+ :ref:`VIDIOC_S_JPEGCOMP <VIDIOC_G_JPEGCOMP>`.
+
+ - .. _V4L2-PIX-FMT-MPEG:
+
+ - ``V4L2_PIX_FMT_MPEG``
+
+ - 'MPEG'
+
+ - MPEG multiplexed stream. The actual format is determined by
+ extended control ``V4L2_CID_MPEG_STREAM_TYPE``, see
+ :ref:`mpeg-control-id`.
+
+ - .. _V4L2-PIX-FMT-H264:
+
+ - ``V4L2_PIX_FMT_H264``
+
+ - 'H264'
+
+ - H264 video elementary stream with start codes.
+
+ - .. _V4L2-PIX-FMT-H264-NO-SC:
+
+ - ``V4L2_PIX_FMT_H264_NO_SC``
+
+ - 'AVC1'
+
+ - H264 video elementary stream without start codes.
+
+ - .. _V4L2-PIX-FMT-H264-MVC:
+
+ - ``V4L2_PIX_FMT_H264_MVC``
+
+ - 'M264'
+
+ - H264 MVC video elementary stream.
+
+ - .. _V4L2-PIX-FMT-H263:
+
+ - ``V4L2_PIX_FMT_H263``
+
+ - 'H263'
+
+ - H263 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-MPEG1:
+
+ - ``V4L2_PIX_FMT_MPEG1``
+
+ - 'MPG1'
+
+ - MPEG1 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-MPEG2:
+
+ - ``V4L2_PIX_FMT_MPEG2``
+
+ - 'MPG2'
+
+ - MPEG2 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-MPEG4:
+
+ - ``V4L2_PIX_FMT_MPEG4``
+
+ - 'MPG4'
+
+ - MPEG4 video elementary stream.
+
+ - .. _V4L2-PIX-FMT-XVID:
+
+ - ``V4L2_PIX_FMT_XVID``
+
+ - 'XVID'
+
+ - Xvid video elementary stream.
+
+ - .. _V4L2-PIX-FMT-VC1-ANNEX-G:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_G``
+
+ - 'VC1G'
+
+ - VC1, SMPTE 421M Annex G compliant stream.
+
+ - .. _V4L2-PIX-FMT-VC1-ANNEX-L:
+
+ - ``V4L2_PIX_FMT_VC1_ANNEX_L``
+
+ - 'VC1L'
+
+ - VC1, SMPTE 421M Annex L compliant stream.
+
+ - .. _V4L2-PIX-FMT-VP8:
+
+ - ``V4L2_PIX_FMT_VP8``
+
+ - 'VP80'
+
+ - VP8 video elementary stream.
diff --git a/Documentation/media/uapi/v4l/pixfmt-grey.rst b/Documentation/media/uapi/v4l/pixfmt-grey.rst
new file mode 100644
index 000000000000..761d783d4989
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-grey.rst
@@ -0,0 +1,77 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-GREY:
+
+**************************
+V4L2_PIX_FMT_GREY ('GREY')
+**************************
+
+*man V4L2_PIX_FMT_GREY(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image. It is really a degenerate Y'CbCr format
+which simply contains no Cb or Cr data.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
diff --git a/Documentation/media/uapi/v4l/pixfmt-indexed.rst b/Documentation/media/uapi/v4l/pixfmt-indexed.rst
new file mode 100644
index 000000000000..99a780fe6b61
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-indexed.rst
@@ -0,0 +1,73 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-indexed:
+
+**************
+Indexed Format
+**************
+
+In this format each pixel is represented by an 8 bit index into a 256
+entry ARGB palette. It is intended for
+:ref:`Video Output Overlays <osd>` only. There are no ioctls to access
+the palette, this must be done with ioctls of the Linux framebuffer API.
+
+
+
+.. flat-table:: Indexed Image Format
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-PAL8:
+
+ - ``V4L2_PIX_FMT_PAL8``
+
+ - 'PAL8'
+
+ -
+ - i\ :sub:`7`
+
+ - i\ :sub:`6`
+
+ - i\ :sub:`5`
+
+ - i\ :sub:`4`
+
+ - i\ :sub:`3`
+
+ - i\ :sub:`2`
+
+ - i\ :sub:`1`
+
+ - i\ :sub:`0`
diff --git a/Documentation/media/uapi/v4l/pixfmt-m420.rst b/Documentation/media/uapi/v4l/pixfmt-m420.rst
new file mode 100644
index 000000000000..4c5b2969c039
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-m420.rst
@@ -0,0 +1,219 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-M420:
+
+**************************
+V4L2_PIX_FMT_M420 ('M420')
+**************************
+
+*man V4L2_PIX_FMT_M420(2)*
+
+Format with ½ horizontal and vertical chroma resolution, also known as
+YUV 4:2:0. Hybrid plane line-interleaved layout.
+
+
+Description
+===========
+
+M420 is a YUV format with ½ horizontal and vertical chroma subsampling
+(YUV 4:2:0). Pixels are organized as interleaved luma and chroma planes.
+Two lines of luma data are followed by one line of chroma data.
+
+The luma plane has one byte per pixel. The chroma plane contains
+interleaved CbCr pixels subsampled by ½ in the horizontal and vertical
+directions. Each CbCr pair belongs to four pixels. For example,
+Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
+Y'\ :sub:`10`, Y'\ :sub:`11`.
+
+All line lengths are identical: if the Y lines include pad bytes so do
+the CbCr lines.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 4
+
+ - start + 16:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 5
+
+ - start + 20:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 6
+
+ - start + 24:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12.rst b/Documentation/media/uapi/v4l/pixfmt-nv12.rst
new file mode 100644
index 000000000000..cf59b28f75b7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12.rst
@@ -0,0 +1,221 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12:
+.. _V4L2-PIX-FMT-NV21:
+
+******************************************************
+V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')
+******************************************************
+
+*man V4L2_PIX_FMT_NV12(2)*
+
+V4L2_PIX_FMT_NV21
+Formats with ½ horizontal and vertical chroma resolution, also known as
+YUV 4:2:0. One luminance and one chrominance plane with alternating
+chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
+
+
+Description
+===========
+
+These are two-plane versions of the YUV 4:2:0 format. The three
+components are separated into two sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a
+combined CbCr plane immediately follows the Y plane in memory. The CbCr
+plane is the same width, in bytes, as the Y plane (and of the image),
+but is half as tall in pixels. Each CbCr pair belongs to four pixels.
+For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is
+the same except the Cb and Cr bytes are swapped, the CrCb plane starts
+with a Cr byte.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has as
+many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 20:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+ -
+
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+ -
+
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12m.rst b/Documentation/media/uapi/v4l/pixfmt-nv12m.rst
new file mode 100644
index 000000000000..a4e7eaeccea8
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12m.rst
@@ -0,0 +1,238 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12M:
+.. _v4l2-pix-fmt-nv12mt-16x16:
+.. _V4L2-PIX-FMT-NV21M:
+
+***********************************************************************************
+V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16
+***********************************************************************************
+
+*man V4L2_PIX_FMT_NV12M(2)*
+
+V4L2_PIX_FMT_NV21M
+V4L2_PIX_FMT_NV12MT_16X16
+Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes
+non contiguous in memory.
+
+
+Description
+===========
+
+This is a multi-planar, two-plane version of the YUV 4:2:0 format. The
+three components are separated into two sub-images or planes.
+``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the
+two planes are non-contiguous in memory, i.e. the chroma plane do not
+necessarily immediately follows the luma plane. The luminance data
+occupies the first plane. The Y plane has one byte per pixel. In the
+second plane there is a chrominance data with alternating chroma
+samples. The CbCr plane is the same width, in bytes, as the Y plane (and
+of the image), but is half as tall in pixels. Each CbCr pair belongs to
+four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to
+Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`.
+``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of
+``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are
+arranged in 16x16 2D tiles and tiles are arranged in linear order in
+memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M``
+except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr
+byte.
+
+``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and
+applications that support the multi-planar API, described in
+:ref:`planar-apis`.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has as
+many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
new file mode 100644
index 000000000000..6198941bb814
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
@@ -0,0 +1,62 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV12MT:
+
+****************************
+V4L2_PIX_FMT_NV12MT ('TM12')
+****************************
+
+*man V4L2_PIX_FMT_NV12MT(2)*
+
+Formats with ½ horizontal and vertical chroma resolution. This format
+has two planes - one for luminance and one for chrominance. Chroma
+samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the
+memory layout. Pixels are grouped in macroblocks of 64x32 size. The
+order of macroblocks in memory is also not standard.
+
+
+Description
+===========
+
+This is the two-plane versions of the YUV 4:2:0 format where data is
+grouped into 64x32 macroblocks. The three components are separated into
+two sub-images or planes. The Y plane has one byte per pixel and pixels
+are grouped into 64x32 macroblocks. The CbCr plane has the same width,
+in bytes, as the Y plane (and the image), but is half as tall in pixels.
+The chroma plane is also grouped into 64x32 macroblocks.
+
+Width of the buffer has to be aligned to the multiple of 128, and height
+alignment is 32. Every four adjacent buffers - two horizontally and two
+vertically are grouped together and are located in memory in Z or
+flipped Z order.
+
+Layout of macroblocks in memory is presented in the following figure.
+
+
+.. _nv12mt:
+
+.. figure:: pixfmt-nv12mt_files/nv12mt.*
+ :alt: nv12mt.gif
+ :align: center
+
+ V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
+
+The requirement that width is multiple of 128 is implemented because,
+the Z shape cannot be cut in half horizontally. In case the vertical
+resolution of macroblocks is odd then the last row of macroblocks is
+arranged in a linear order.
+
+In case of chroma the layout is identical. Cb and Cr samples are
+interleaved. Height of the buffer is aligned to 32.
+
+
+.. _nv12mt_ex:
+
+.. figure:: pixfmt-nv12mt_files/nv12mt_example.*
+ :alt: nv12mt_example.gif
+ :align: center
+
+ Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
+
+Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most
+extreme case.
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif
new file mode 100644
index 000000000000..ef2d4cf8367b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif
new file mode 100644
index 000000000000..df81d68108ee
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif
Binary files differ
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv16.rst b/Documentation/media/uapi/v4l/pixfmt-nv16.rst
new file mode 100644
index 000000000000..88aa7617f7cf
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv16.rst
@@ -0,0 +1,270 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV16:
+.. _V4L2-PIX-FMT-NV61:
+
+******************************************************
+V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')
+******************************************************
+
+*man V4L2_PIX_FMT_NV16(2)*
+
+V4L2_PIX_FMT_NV61
+Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2.
+One luminance and one chrominance plane with alternating chroma samples
+as opposed to ``V4L2_PIX_FMT_YVU420``
+
+
+Description
+===========
+
+These are two-plane versions of the YUV 4:2:2 format. The three
+components are separated into two sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a
+combined CbCr plane immediately follows the Y plane in memory. The CbCr
+plane is the same width and height, in bytes, as the Y plane (and of the
+image). Each CbCr pair belongs to two pixels. For example,
+Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
+``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are
+swapped, the CrCb plane starts with a Cr byte.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has as
+many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 20:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - .. row 7
+
+ - start + 24:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - .. row 8
+
+ - start + 28:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 6
+
+ -
+
+ - .. row 7
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 8
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 9
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 10
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv16m.rst b/Documentation/media/uapi/v4l/pixfmt-nv16m.rst
new file mode 100644
index 000000000000..b7ee068f491c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv16m.rst
@@ -0,0 +1,277 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV16M:
+.. _v4l2-pix-fmt-nv61m:
+
+********************************************************
+V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')
+********************************************************
+
+*man V4L2_PIX_FMT_NV16M(2)*
+
+V4L2_PIX_FMT_NV61M
+Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes
+non contiguous in memory.
+
+
+Description
+===========
+
+This is a multi-planar, two-plane version of the YUV 4:2:2 format. The
+three components are separated into two sub-images or planes.
+``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the
+two planes are non-contiguous in memory, i.e. the chroma plane does not
+necessarily immediately follow the luma plane. The luminance data
+occupies the first plane. The Y plane has one byte per pixel. In the
+second plane there is chrominance data with alternating chroma samples.
+The CbCr plane is the same width and height, in bytes, as the Y plane.
+Each CbCr pair belongs to two pixels. For example,
+Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
+``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the
+Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.
+
+``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`02`
+
+ - Cr\ :sub:`02`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`12`
+
+ - Cr\ :sub:`12`
+
+ - .. row 8
+
+ - start1 + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`22`
+
+ - Cr\ :sub:`22`
+
+ - .. row 9
+
+ - start1 + 12:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`32`
+
+ - Cr\ :sub:`32`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 6
+
+ -
+
+ - .. row 7
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 8
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
+
+ - .. row 9
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ - Y
+
+ -
+ - Y
+
+ - .. row 10
+
+ -
+ -
+ - C
+
+ -
+ -
+ - C
+
+ -
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv24.rst b/Documentation/media/uapi/v4l/pixfmt-nv24.rst
new file mode 100644
index 000000000000..db98f476446e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-nv24.rst
@@ -0,0 +1,171 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-NV24:
+.. _V4L2-PIX-FMT-NV42:
+
+******************************************************
+V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')
+******************************************************
+
+*man V4L2_PIX_FMT_NV24(2)*
+
+V4L2_PIX_FMT_NV42
+Formats with full horizontal and vertical chroma resolutions, also known
+as YUV 4:4:4. One luminance and one chrominance plane with alternating
+chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
+
+
+Description
+===========
+
+These are two-plane versions of the YUV 4:4:4 format. The three
+components are separated into two sub-images or planes. The Y plane is
+first, with each Y sample stored in one byte per pixel. For
+``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y
+plane in memory. The CbCr plane has the same width and height, in
+pixels, as the Y plane (and the image). Each line contains one CbCr pair
+per pixel, with each Cb and Cr sample stored in one byte.
+``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are
+swapped, the CrCb plane starts with a Cr sample.
+
+If the Y plane has pad bytes after each row, then the CbCr plane has
+twice as many pad bytes after its rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - Cb\ :sub:`02`
+
+ - Cr\ :sub:`02`
+
+ - Cb\ :sub:`03`
+
+ - Cr\ :sub:`03`
+
+ - .. row 6
+
+ - start + 24:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - Cb\ :sub:`12`
+
+ - Cr\ :sub:`12`
+
+ - Cb\ :sub:`13`
+
+ - Cr\ :sub:`13`
+
+ - .. row 7
+
+ - start + 32:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - Cb\ :sub:`22`
+
+ - Cr\ :sub:`22`
+
+ - Cb\ :sub:`23`
+
+ - Cr\ :sub:`23`
+
+ - .. row 8
+
+ - start + 40:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - Cr\ :sub:`31`
+
+ - Cb\ :sub:`32`
+
+ - Cr\ :sub:`32`
+
+ - Cb\ :sub:`33`
+
+ - Cr\ :sub:`33`
diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst
new file mode 100644
index 000000000000..c7aa2e91ac78
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst
@@ -0,0 +1,1469 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _packed-rgb:
+
+******************
+Packed RGB formats
+******************
+
+*man Packed RGB formats(2)*
+
+Packed RGB formats
+
+
+Description
+===========
+
+These formats are designed to match the pixel formats of typical PC
+graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
+These are all packed-pixel formats, meaning all the data for a pixel lie
+next to each other in memory.
+
+
+.. _rgb-formats:
+
+.. flat-table:: Packed RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ - :cspan:`7` Byte 1
+
+ - :cspan:`7` Byte 2
+
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-RGB332:
+
+ - ``V4L2_PIX_FMT_RGB332``
+
+ - 'RGB1'
+
+ -
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-ARGB444:
+
+ - ``V4L2_PIX_FMT_ARGB444``
+
+ - 'AR12'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XRGB444:
+
+ - ``V4L2_PIX_FMT_XRGB444``
+
+ - 'XR12'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-ARGB555:
+
+ - ``V4L2_PIX_FMT_ARGB555``
+
+ - 'AR15'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-XRGB555:
+
+ - ``V4L2_PIX_FMT_XRGB555``
+
+ - 'XR15'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-RGB565:
+
+ - ``V4L2_PIX_FMT_RGB565``
+
+ - 'RGBP'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-ARGB555X:
+
+ - ``V4L2_PIX_FMT_ARGB555X``
+
+ - 'AR15' | (1 << 31)
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XRGB555X:
+
+ - ``V4L2_PIX_FMT_XRGB555X``
+
+ - 'XR15' | (1 << 31)
+
+ -
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB565X:
+
+ - ``V4L2_PIX_FMT_RGB565X``
+
+ - 'RGBR'
+
+ -
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-BGR24:
+
+ - ``V4L2_PIX_FMT_BGR24``
+
+ - 'BGR3'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB24:
+
+ - ``V4L2_PIX_FMT_RGB24``
+
+ - 'RGB3'
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-BGR666:
+
+ - ``V4L2_PIX_FMT_BGR666``
+
+ - 'BGRH'
+
+ -
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ -
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - .. _V4L2-PIX-FMT-ABGR32:
+
+ - ``V4L2_PIX_FMT_ABGR32``
+
+ - 'AR24'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XBGR32:
+
+ - ``V4L2_PIX_FMT_XBGR32``
+
+ - 'XR24'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - .. _V4L2-PIX-FMT-ARGB32:
+
+ - ``V4L2_PIX_FMT_ARGB32``
+
+ - 'BA24'
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-XRGB32:
+
+ - ``V4L2_PIX_FMT_XRGB32``
+
+ - 'BX24'
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+Bit 7 is the most significant bit.
+
+The usage and value of the alpha bits (a) in the ARGB and ABGR formats
+(collectively referred to as alpha formats) depend on the device type
+and hardware operation. :ref:`Capture <capture>` devices (including
+capture queues of mem-to-mem devices) fill the alpha component in
+memory. When the device outputs an alpha channel the alpha component
+will have a meaningful value. Otherwise, when the device doesn't output
+an alpha channel but can set the alpha bit to a user-configurable value,
+the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
+is used to specify that alpha value, and the alpha component of all
+pixels will be set to the value specified by that control. Otherwise a
+corresponding format without an alpha component (XRGB or XBGR) must be
+used instead of an alpha format.
+
+:ref:`Output <output>` devices (including output queues of mem-to-mem
+devices and :ref:`video output overlay <osd>` devices) read the alpha
+component from memory. When the device processes the alpha channel the
+alpha component must be filled with meaningful values by applications.
+Otherwise a corresponding format without an alpha component (XRGB or
+XBGR) must be used instead of an alpha format.
+
+The XRGB and XBGR formats contain undefined bits (-). Applications,
+devices and drivers must ignore those bits, for both
+:ref:`capture` and :ref:`output` devices.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00`
+
+ - G\ :sub:`00`
+
+ - R\ :sub:`00`
+
+ - B\ :sub:`01`
+
+ - G\ :sub:`01`
+
+ - R\ :sub:`01`
+
+ - B\ :sub:`02`
+
+ - G\ :sub:`02`
+
+ - R\ :sub:`02`
+
+ - B\ :sub:`03`
+
+ - G\ :sub:`03`
+
+ - R\ :sub:`03`
+
+ - .. row 2
+
+ - start + 12:
+
+ - B\ :sub:`10`
+
+ - G\ :sub:`10`
+
+ - R\ :sub:`10`
+
+ - B\ :sub:`11`
+
+ - G\ :sub:`11`
+
+ - R\ :sub:`11`
+
+ - B\ :sub:`12`
+
+ - G\ :sub:`12`
+
+ - R\ :sub:`12`
+
+ - B\ :sub:`13`
+
+ - G\ :sub:`13`
+
+ - R\ :sub:`13`
+
+ - .. row 3
+
+ - start + 24:
+
+ - B\ :sub:`20`
+
+ - G\ :sub:`20`
+
+ - R\ :sub:`20`
+
+ - B\ :sub:`21`
+
+ - G\ :sub:`21`
+
+ - R\ :sub:`21`
+
+ - B\ :sub:`22`
+
+ - G\ :sub:`22`
+
+ - R\ :sub:`22`
+
+ - B\ :sub:`23`
+
+ - G\ :sub:`23`
+
+ - R\ :sub:`23`
+
+ - .. row 4
+
+ - start + 36:
+
+ - B\ :sub:`30`
+
+ - G\ :sub:`30`
+
+ - R\ :sub:`30`
+
+ - B\ :sub:`31`
+
+ - G\ :sub:`31`
+
+ - R\ :sub:`31`
+
+ - B\ :sub:`32`
+
+ - G\ :sub:`32`
+
+ - R\ :sub:`32`
+
+ - B\ :sub:`33`
+
+ - G\ :sub:`33`
+
+ - R\ :sub:`33`
+
+
+Formats defined in :ref:`rgb-formats-deprecated` are deprecated and
+must not be used by new drivers. They are documented here for reference.
+The meaning of their alpha bits (a) is ill-defined and interpreted as in
+either the corresponding ARGB or XRGB format, depending on the driver.
+
+
+.. _rgb-formats-deprecated:
+
+.. flat-table:: Deprecated Packed RGB Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ - :cspan:`7` Byte 1
+
+ - :cspan:`7` Byte 2
+
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-RGB444:
+
+ - ``V4L2_PIX_FMT_RGB444``
+
+ - 'R444'
+
+ -
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB555:
+
+ - ``V4L2_PIX_FMT_RGB555``
+
+ - 'RGBO'
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-RGB555X:
+
+ - ``V4L2_PIX_FMT_RGB555X``
+
+ - 'RGBQ'
+
+ -
+ - a
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ -
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-BGR32:
+
+ - ``V4L2_PIX_FMT_BGR32``
+
+ - 'BGR4'
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-RGB32:
+
+ - ``V4L2_PIX_FMT_RGB32``
+
+ - 'RGB4'
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ -
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ -
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ -
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+A test utility to determine which RGB formats a driver actually supports
+is available from the LinuxTV v4l-dvb repository. See
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
diff --git a/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst
new file mode 100644
index 000000000000..54716455f453
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst
@@ -0,0 +1,316 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _packed-yuv:
+
+******************
+Packed YUV formats
+******************
+
+*man Packed YUV formats(2)*
+
+Packed YUV formats
+
+
+Description
+===========
+
+Similar to the packed RGB formats these formats store the Y, Cb and Cr
+component of each pixel in one 16 or 32 bit word.
+
+
+
+.. flat-table:: Packed YUV Image Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`7` Byte 0 in memory
+
+ -
+ - :cspan:`7` Byte 1
+
+ -
+ - :cspan:`7` Byte 2
+
+ -
+ - :cspan:`7` Byte 3
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ -
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _V4L2-PIX-FMT-YUV444:
+
+ - ``V4L2_PIX_FMT_YUV444``
+
+ - 'Y444'
+
+ -
+ - Cb\ :sub:`3`
+
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - .. _V4L2-PIX-FMT-YUV555:
+
+ - ``V4L2_PIX_FMT_YUV555``
+
+ - 'YUVO'
+
+ -
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - a
+
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-YUV565:
+
+ - ``V4L2_PIX_FMT_YUV565``
+
+ - 'YUVP'
+
+ -
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+ -
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ - Cb\ :sub:`5`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - .. _V4L2-PIX-FMT-YUV32:
+
+ - ``V4L2_PIX_FMT_YUV32``
+
+ - 'YUV4'
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ -
+ - Y'\ :sub:`7`
+
+ - Y'\ :sub:`6`
+
+ - Y'\ :sub:`5`
+
+ - Y'\ :sub:`4`
+
+ - Y'\ :sub:`3`
+
+ - Y'\ :sub:`2`
+
+ - Y'\ :sub:`1`
+
+ - Y'\ :sub:`0`
+
+ -
+ - Cb\ :sub:`7`
+
+ - Cb\ :sub:`6`
+
+ - Cb\ :sub:`5`
+
+ - Cb\ :sub:`4`
+
+ - Cb\ :sub:`3`
+
+ - Cb\ :sub:`2`
+
+ - Cb\ :sub:`1`
+
+ - Cb\ :sub:`0`
+
+ -
+ - Cr\ :sub:`7`
+
+ - Cr\ :sub:`6`
+
+ - Cr\ :sub:`5`
+
+ - Cr\ :sub:`4`
+
+ - Cr\ :sub:`3`
+
+ - Cr\ :sub:`2`
+
+ - Cr\ :sub:`1`
+
+ - Cr\ :sub:`0`
+
+
+Bit 7 is the most significant bit. The value of a = alpha bits is
+undefined when reading from the driver, ignored when writing to the
+driver, except when alpha blending has been negotiated for a
+:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`.
diff --git a/Documentation/media/uapi/v4l/pixfmt-reserved.rst b/Documentation/media/uapi/v4l/pixfmt-reserved.rst
new file mode 100644
index 000000000000..9a5704baf9fe
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-reserved.rst
@@ -0,0 +1,360 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-reserved:
+
+***************************
+Reserved Format Identifiers
+***************************
+
+These formats are not defined by this specification, they are just
+listed for reference and to avoid naming conflicts. If you want to
+register your own format, send an e-mail to the linux-media mailing list
+`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__
+for inclusion in the ``videodev2.h`` file. If you want to share your
+format with other developers add a link to your documentation and send a
+copy to the linux-media mailing list for inclusion in this section. If
+you think your format should be listed in a standard format section
+please make a proposal on the linux-media mailing list.
+
+
+.. _reserved-formats:
+
+.. flat-table:: Reserved Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Details
+
+ - .. _V4L2-PIX-FMT-DV:
+
+ - ``V4L2_PIX_FMT_DV``
+
+ - 'dvsd'
+
+ - unknown
+
+ - .. _V4L2-PIX-FMT-ET61X251:
+
+ - ``V4L2_PIX_FMT_ET61X251``
+
+ - 'E625'
+
+ - Compressed format of the ET61X251 driver.
+
+ - .. _V4L2-PIX-FMT-HI240:
+
+ - ``V4L2_PIX_FMT_HI240``
+
+ - 'HI24'
+
+ - 8 bit RGB format used by the BTTV driver.
+
+ - .. _V4L2-PIX-FMT-HM12:
+
+ - ``V4L2_PIX_FMT_HM12``
+
+ - 'HM12'
+
+ - YUV 4:2:0 format used by the IVTV driver,
+ `http://www.ivtvdriver.org/ <http://www.ivtvdriver.org/>`__
+
+ The format is documented in the kernel sources in the file
+ ``Documentation/video4linux/cx2341x/README.hm12``
+
+ - .. _V4L2-PIX-FMT-CPIA1:
+
+ - ``V4L2_PIX_FMT_CPIA1``
+
+ - 'CPIA'
+
+ - YUV format used by the gspca cpia1 driver.
+
+ - .. _V4L2-PIX-FMT-JPGL:
+
+ - ``V4L2_PIX_FMT_JPGL``
+
+ - 'JPGL'
+
+ - JPEG-Light format (Pegasus Lossless JPEG) used in Divio webcams NW
+ 80x.
+
+ - .. _V4L2-PIX-FMT-SPCA501:
+
+ - ``V4L2_PIX_FMT_SPCA501``
+
+ - 'S501'
+
+ - YUYV per line used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SPCA505:
+
+ - ``V4L2_PIX_FMT_SPCA505``
+
+ - 'S505'
+
+ - YYUV per line used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SPCA508:
+
+ - ``V4L2_PIX_FMT_SPCA508``
+
+ - 'S508'
+
+ - YUVY per line used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SPCA561:
+
+ - ``V4L2_PIX_FMT_SPCA561``
+
+ - 'S561'
+
+ - Compressed GBRG Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-PAC207:
+
+ - ``V4L2_PIX_FMT_PAC207``
+
+ - 'P207'
+
+ - Compressed BGGR Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-MR97310A:
+
+ - ``V4L2_PIX_FMT_MR97310A``
+
+ - 'M310'
+
+ - Compressed BGGR Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-JL2005BCD:
+
+ - ``V4L2_PIX_FMT_JL2005BCD``
+
+ - 'JL20'
+
+ - JPEG compressed RGGB Bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-OV511:
+
+ - ``V4L2_PIX_FMT_OV511``
+
+ - 'O511'
+
+ - OV511 JPEG format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-OV518:
+
+ - ``V4L2_PIX_FMT_OV518``
+
+ - 'O518'
+
+ - OV518 JPEG format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-PJPG:
+
+ - ``V4L2_PIX_FMT_PJPG``
+
+ - 'PJPG'
+
+ - Pixart 73xx JPEG format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-SE401:
+
+ - ``V4L2_PIX_FMT_SE401``
+
+ - 'S401'
+
+ - Compressed RGB format used by the gspca se401 driver
+
+ - .. _V4L2-PIX-FMT-SQ905C:
+
+ - ``V4L2_PIX_FMT_SQ905C``
+
+ - '905C'
+
+ - Compressed RGGB bayer format used by the gspca driver.
+
+ - .. _V4L2-PIX-FMT-MJPEG:
+
+ - ``V4L2_PIX_FMT_MJPEG``
+
+ - 'MJPG'
+
+ - Compressed format used by the Zoran driver
+
+ - .. _V4L2-PIX-FMT-PWC1:
+
+ - ``V4L2_PIX_FMT_PWC1``
+
+ - 'PWC1'
+
+ - Compressed format of the PWC driver.
+
+ - .. _V4L2-PIX-FMT-PWC2:
+
+ - ``V4L2_PIX_FMT_PWC2``
+
+ - 'PWC2'
+
+ - Compressed format of the PWC driver.
+
+ - .. _V4L2-PIX-FMT-SN9C10X:
+
+ - ``V4L2_PIX_FMT_SN9C10X``
+
+ - 'S910'
+
+ - Compressed format of the SN9C102 driver.
+
+ - .. _V4L2-PIX-FMT-SN9C20X-I420:
+
+ - ``V4L2_PIX_FMT_SN9C20X_I420``
+
+ - 'S920'
+
+ - YUV 4:2:0 format of the gspca sn9c20x driver.
+
+ - .. _V4L2-PIX-FMT-SN9C2028:
+
+ - ``V4L2_PIX_FMT_SN9C2028``
+
+ - 'SONX'
+
+ - Compressed GBRG bayer format of the gspca sn9c2028 driver.
+
+ - .. _V4L2-PIX-FMT-STV0680:
+
+ - ``V4L2_PIX_FMT_STV0680``
+
+ - 'S680'
+
+ - Bayer format of the gspca stv0680 driver.
+
+ - .. _V4L2-PIX-FMT-WNVA:
+
+ - ``V4L2_PIX_FMT_WNVA``
+
+ - 'WNVA'
+
+ - Used by the Winnov Videum driver,
+ `http://www.thedirks.org/winnov/ <http://www.thedirks.org/winnov/>`__
+
+ - .. _V4L2-PIX-FMT-TM6000:
+
+ - ``V4L2_PIX_FMT_TM6000``
+
+ - 'TM60'
+
+ - Used by Trident tm6000
+
+ - .. _V4L2-PIX-FMT-CIT-YYVYUY:
+
+ - ``V4L2_PIX_FMT_CIT_YYVYUY``
+
+ - 'CITV'
+
+ - Used by xirlink CIT, found at IBM webcams.
+
+ Uses one line of Y then 1 line of VYUY
+
+ - .. _V4L2-PIX-FMT-KONICA420:
+
+ - ``V4L2_PIX_FMT_KONICA420``
+
+ - 'KONI'
+
+ - Used by Konica webcams.
+
+ YUV420 planar in blocks of 256 pixels.
+
+ - .. _V4L2-PIX-FMT-YYUV:
+
+ - ``V4L2_PIX_FMT_YYUV``
+
+ - 'YYUV'
+
+ - unknown
+
+ - .. _V4L2-PIX-FMT-Y4:
+
+ - ``V4L2_PIX_FMT_Y4``
+
+ - 'Y04 '
+
+ - Old 4-bit greyscale format. Only the most significant 4 bits of
+ each byte are used, the other bits are set to 0.
+
+ - .. _V4L2-PIX-FMT-Y6:
+
+ - ``V4L2_PIX_FMT_Y6``
+
+ - 'Y06 '
+
+ - Old 6-bit greyscale format. Only the most significant 6 bits of
+ each byte are used, the other bits are set to 0.
+
+ - .. _V4L2-PIX-FMT-S5C-UYVY-JPG:
+
+ - ``V4L2_PIX_FMT_S5C_UYVY_JPG``
+
+ - 'S5CI'
+
+ - Two-planar format used by Samsung S5C73MX cameras. The first plane
+ contains interleaved JPEG and UYVY image data, followed by meta
+ data in form of an array of offsets to the UYVY data blocks. The
+ actual pointer array follows immediately the interleaved JPEG/UYVY
+ data, the number of entries in this array equals the height of the
+ UYVY image. Each entry is a 4-byte unsigned integer in big endian
+ order and it's an offset to a single pixel line of the UYVY image.
+ The first plane can start either with JPEG or UYVY data chunk. The
+ size of a single UYVY block equals the UYVY image's width
+ multiplied by 2. The size of a JPEG chunk depends on the image and
+ can vary with each line.
+
+ The second plane, at an offset of 4084 bytes, contains a 4-byte
+ offset to the pointer array in the first plane. This offset is
+ followed by a 4-byte value indicating size of the pointer array.
+ All numbers in the second plane are also in big endian order.
+ Remaining data in the second plane is undefined. The information
+ in the second plane allows to easily find location of the pointer
+ array, which can be different for each frame. The size of the
+ pointer array is constant for given UYVY image height.
+
+ In order to extract UYVY and JPEG frames an application can
+ initially set a data pointer to the start of first plane and then
+ add an offset from the first entry of the pointers table. Such a
+ pointer indicates start of an UYVY image pixel line. Whole UYVY
+ line can be copied to a separate buffer. These steps should be
+ repeated for each line, i.e. the number of entries in the pointer
+ array. Anything what's in between the UYVY lines is JPEG data and
+ should be concatenated to form the JPEG stream.
+
+
+
+.. _format-flags:
+
+.. flat-table:: Format Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_PIX_FMT_FLAG_PREMUL_ALPHA``
+
+ - 0x00000001
+
+ - The color values are premultiplied by the alpha channel value. For
+ example, if a light blue pixel with 50% transparency was described
+ by RGBA values (128, 192, 255, 128), the same pixel described with
+ premultiplied colors would be described by RGBA values (64, 96,
+ 128, 128)
diff --git a/Documentation/media/uapi/v4l/pixfmt-rgb.rst b/Documentation/media/uapi/v4l/pixfmt-rgb.rst
new file mode 100644
index 000000000000..4b3651cc0a96
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-rgb.rst
@@ -0,0 +1,23 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt-rgb:
+
+***********
+RGB Formats
+***********
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-packed-rgb
+ pixfmt-sbggr8
+ pixfmt-sgbrg8
+ pixfmt-sgrbg8
+ pixfmt-srggb8
+ pixfmt-sbggr16
+ pixfmt-srggb10
+ pixfmt-srggb10p
+ pixfmt-srggb10alaw8
+ pixfmt-srggb10dpcm8
+ pixfmt-srggb12
diff --git a/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst
new file mode 100644
index 000000000000..2cfcc97b3c96
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sbggr16.rst
@@ -0,0 +1,113 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR16:
+
+*****************************
+V4L2_PIX_FMT_SBGGR16 ('BYR2')
+*****************************
+
+*man V4L2_PIX_FMT_SBGGR16(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This format is similar to
+:ref:`V4L2_PIX_FMT_SBGGR8 <V4L2-PIX-FMT-SBGGR8>`, except each pixel
+has a depth of 16 bits. The least significant byte is stored at lower
+memory addresses (little-endian). Note the actual sampling precision may
+be lower than 16 bits, for example 10 bits per pixel with values in
+range 0 to 1023.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sbggr8.rst b/Documentation/media/uapi/v4l/pixfmt-sbggr8.rst
new file mode 100644
index 000000000000..db4c523f49a9
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sbggr8.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR8:
+
+****************************
+V4L2_PIX_FMT_SBGGR8 ('BA81')
+****************************
+
+*man V4L2_PIX_FMT_SBGGR8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+blue and green value, the second row of a green and red value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00`
+
+ - G\ :sub:`01`
+
+ - B\ :sub:`02`
+
+ - G\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - G\ :sub:`10`
+
+ - R\ :sub:`11`
+
+ - G\ :sub:`12`
+
+ - R\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - B\ :sub:`20`
+
+ - G\ :sub:`21`
+
+ - B\ :sub:`22`
+
+ - G\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - G\ :sub:`30`
+
+ - R\ :sub:`31`
+
+ - G\ :sub:`32`
+
+ - R\ :sub:`33`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst
new file mode 100644
index 000000000000..2736275d080f
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst
@@ -0,0 +1,43 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-sdr-fmt-cs8:
+
+*************************
+V4L2_SDR_FMT_CS8 ('CS08')
+*************************
+
+*man V4L2_SDR_FMT_CS8(2)*
+
+Complex signed 8-bit IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 8 bit signed number. I value comes first and
+Q value after that.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0`
+
+ - .. row 2
+
+ - start + 1:
+
+ - Q'\ :sub:`0`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst
new file mode 100644
index 000000000000..bfe5804bd84e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst
@@ -0,0 +1,48 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CS14LE:
+
+****************************
+V4L2_SDR_FMT_CS14LE ('CS14')
+****************************
+
+*man V4L2_SDR_FMT_CS14LE(2)*
+
+Complex signed 14-bit little endian IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 14 bit signed little endian number. I value
+comes first and Q value after that. 14 bit value is stored in 16 bit
+space with unused high bits padded with 0.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[13:8]`
+
+ - .. row 2
+
+ - start + 2:
+
+ - Q'\ :sub:`0[7:0]`
+
+ - Q'\ :sub:`0[13:8]`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst
new file mode 100644
index 000000000000..68ad1717f6d7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst
@@ -0,0 +1,43 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-sdr-fmt-cu8:
+
+*************************
+V4L2_SDR_FMT_CU8 ('CU08')
+*************************
+
+*man V4L2_SDR_FMT_CU8(2)*
+
+Complex unsigned 8-bit IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 8 bit unsigned number. I value comes first
+and Q value after that.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0`
+
+ - .. row 2
+
+ - start + 1:
+
+ - Q'\ :sub:`0`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst
new file mode 100644
index 000000000000..2a1c0d4924a1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst
@@ -0,0 +1,47 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-CU16LE:
+
+****************************
+V4L2_SDR_FMT_CU16LE ('CU16')
+****************************
+
+*man V4L2_SDR_FMT_CU16LE(2)*
+
+Complex unsigned 16-bit little endian IQ sample
+
+
+Description
+===========
+
+This format contains sequence of complex number samples. Each complex
+number consist two parts, called In-phase and Quadrature (IQ). Both I
+and Q are represented as a 16 bit unsigned little endian number. I value
+comes first and Q value after that.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[15:8]`
+
+ - .. row 2
+
+ - start + 2:
+
+ - Q'\ :sub:`0[7:0]`
+
+ - Q'\ :sub:`0[15:8]`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst b/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst
new file mode 100644
index 000000000000..378581b27d4a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst
@@ -0,0 +1,38 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-SDR-FMT-RU12LE:
+
+****************************
+V4L2_SDR_FMT_RU12LE ('RU12')
+****************************
+
+*man V4L2_SDR_FMT_RU12LE(2)*
+
+Real unsigned 12-bit little endian sample
+
+
+Description
+===========
+
+This format contains sequence of real number samples. Each sample is
+represented as a 12 bit unsigned little endian number. Sample is stored
+in 16 bit space with unused high bits padded with 0.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - I'\ :sub:`0[7:0]`
+
+ - I'\ :sub:`0[11:8]`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst b/Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst
new file mode 100644
index 000000000000..6345c24d86f3
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SGBRG8:
+
+****************************
+V4L2_PIX_FMT_SGBRG8 ('GBRG')
+****************************
+
+*man V4L2_PIX_FMT_SGBRG8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+green and blue value, the second row of a red and green value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - G\ :sub:`00`
+
+ - B\ :sub:`01`
+
+ - G\ :sub:`02`
+
+ - B\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - R\ :sub:`10`
+
+ - G\ :sub:`11`
+
+ - R\ :sub:`12`
+
+ - G\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - G\ :sub:`20`
+
+ - B\ :sub:`21`
+
+ - G\ :sub:`22`
+
+ - B\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - R\ :sub:`30`
+
+ - G\ :sub:`31`
+
+ - R\ :sub:`32`
+
+ - G\ :sub:`33`
diff --git a/Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst b/Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst
new file mode 100644
index 000000000000..51b7b8ef7519
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SGRBG8:
+
+****************************
+V4L2_PIX_FMT_SGRBG8 ('GRBG')
+****************************
+
+*man V4L2_PIX_FMT_SGRBG8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+green and blue value, the second row of a red and green value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - G\ :sub:`00`
+
+ - R\ :sub:`01`
+
+ - G\ :sub:`02`
+
+ - R\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - B\ :sub:`10`
+
+ - G\ :sub:`11`
+
+ - B\ :sub:`12`
+
+ - G\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - G\ :sub:`20`
+
+ - R\ :sub:`21`
+
+ - G\ :sub:`22`
+
+ - R\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - B\ :sub:`30`
+
+ - G\ :sub:`31`
+
+ - B\ :sub:`32`
+
+ - G\ :sub:`33`
diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10.rst
new file mode 100644
index 000000000000..44a49563917c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-srggb10.rst
@@ -0,0 +1,120 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB10:
+.. _v4l2-pix-fmt-sbggr10:
+.. _v4l2-pix-fmt-sgbrg10:
+.. _v4l2-pix-fmt-sgrbg10:
+
+***************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB10 ('RG10'), V4L2_PIX_FMT_SGRBG10 ('BA10'), V4L2_PIX_FMT_SGBRG10 ('GB10'), V4L2_PIX_FMT_SBGGR10 ('BG10'),
+***************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB10(2)*
+
+V4L2_PIX_FMT_SGRBG10
+V4L2_PIX_FMT_SGBRG10
+V4L2_PIX_FMT_SBGGR10
+10-bit Bayer formats expanded to 16 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+colour. Each colour component is stored in a 16-bit word, with 6 unused
+high bits filled with zeros. Each n-pixel row contains n/2 green samples
+and n/2 blue or red samples, with alternating red and blue rows. Bytes
+are stored in memory in little endian order. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats
+
+**Byte Order.**
+Each cell is one byte, high 6 bits in high bytes are 0.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst
new file mode 100644
index 000000000000..68bae0cb764c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst
@@ -0,0 +1,26 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR10ALAW8:
+.. _v4l2-pix-fmt-sgbrg10alaw8:
+.. _v4l2-pix-fmt-sgrbg10alaw8:
+.. _v4l2-pix-fmt-srggb10alaw8:
+
+***********************************************************************************************************************************************
+V4L2_PIX_FMT_SBGGR10ALAW8 ('aBA8'), V4L2_PIX_FMT_SGBRG10ALAW8 ('aGA8'), V4L2_PIX_FMT_SGRBG10ALAW8 ('agA8'), V4L2_PIX_FMT_SRGGB10ALAW8 ('aRA8'),
+***********************************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SBGGR10ALAW8(2)*
+
+V4L2_PIX_FMT_SGBRG10ALAW8
+V4L2_PIX_FMT_SGRBG10ALAW8
+V4L2_PIX_FMT_SRGGB10ALAW8
+10-bit Bayer formats compressed to 8 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+color compressed to 8 bits each, using the A-LAW algorithm. Each color
+component consumes 8 bits of memory. In other respects this format is
+similar to :ref:`V4L2-PIX-FMT-SRGGB8`.
diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst
new file mode 100644
index 000000000000..5e041d02eff0
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst
@@ -0,0 +1,28 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SBGGR10DPCM8:
+.. _v4l2-pix-fmt-sgbrg10dpcm8:
+.. _v4l2-pix-fmt-sgrbg10dpcm8:
+.. _v4l2-pix-fmt-srggb10dpcm8:
+
+
+***********************************************************************************************************************************************
+V4L2_PIX_FMT_SBGGR10DPCM8 ('bBA8'), V4L2_PIX_FMT_SGBRG10DPCM8 ('bGA8'), V4L2_PIX_FMT_SGRBG10DPCM8 ('BD10'), V4L2_PIX_FMT_SRGGB10DPCM8 ('bRA8'),
+***********************************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SBGGR10DPCM8(2)*
+
+V4L2_PIX_FMT_SGBRG10DPCM8
+V4L2_PIX_FMT_SGRBG10DPCM8
+V4L2_PIX_FMT_SRGGB10DPCM8
+10-bit Bayer formats compressed to 8 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 10 bits per
+colour compressed to 8 bits each, using DPCM compression. DPCM,
+differential pulse-code modulation, is lossy. Each colour component
+consumes 8 bits of memory. In other respects this format is similar to
+:ref:`V4L2-PIX-FMT-SRGGB10`.
diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst
new file mode 100644
index 000000000000..d71368f69087
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-srggb10p.rst
@@ -0,0 +1,103 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB10P:
+.. _v4l2-pix-fmt-sbggr10p:
+.. _v4l2-pix-fmt-sgbrg10p:
+.. _v4l2-pix-fmt-sgrbg10p:
+
+*******************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB10P ('pRAA'), V4L2_PIX_FMT_SGRBG10P ('pgAA'), V4L2_PIX_FMT_SGBRG10P ('pGAA'), V4L2_PIX_FMT_SBGGR10P ('pBAA'),
+*******************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB10P(2)*
+
+V4L2_PIX_FMT_SGRBG10P
+V4L2_PIX_FMT_SGBRG10P
+V4L2_PIX_FMT_SBGGR10P
+10-bit packed Bayer formats
+
+
+Description
+===========
+
+These four pixel formats are packed raw sRGB / Bayer formats with 10
+bits per colour. Every four consecutive colour components are packed
+into 5 bytes. Each of the first 4 bytes contain the 8 high order bits of
+the pixels, and the fifth byte contains the two least significants bits
+of each pixel, in the same order.
+
+Each n-pixel row contains n/2 green samples and n/2 blue or red samples,
+with alternating green-red and green-blue rows. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats:
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03high`
+
+ - B\ :sub:`00low`\ (bits 7--6) G\ :sub:`01low`\ (bits 5--4)
+ B\ :sub:`02low`\ (bits 3--2) G\ :sub:`03low`\ (bits 1--0)
+
+ - .. row 2
+
+ - start + 5:
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13high`
+
+ - G\ :sub:`10low`\ (bits 7--6) R\ :sub:`11low`\ (bits 5--4)
+ G\ :sub:`12low`\ (bits 3--2) R\ :sub:`13low`\ (bits 1--0)
+
+ - .. row 3
+
+ - start + 10:
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23high`
+
+ - B\ :sub:`20low`\ (bits 7--6) G\ :sub:`21low`\ (bits 5--4)
+ B\ :sub:`22low`\ (bits 3--2) G\ :sub:`23low`\ (bits 1--0)
+
+ - .. row 4
+
+ - start + 15:
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33high`
+
+ - G\ :sub:`30low`\ (bits 7--6) R\ :sub:`31low`\ (bits 5--4)
+ G\ :sub:`32low`\ (bits 3--2) R\ :sub:`33low`\ (bits 1--0)
diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb12.rst b/Documentation/media/uapi/v4l/pixfmt-srggb12.rst
new file mode 100644
index 000000000000..f5303ab9e79c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-srggb12.rst
@@ -0,0 +1,121 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB12:
+.. _v4l2-pix-fmt-sbggr12:
+.. _v4l2-pix-fmt-sgbrg12:
+.. _v4l2-pix-fmt-sgrbg12:
+
+
+***************************************************************************************************************************
+V4L2_PIX_FMT_SRGGB12 ('RG12'), V4L2_PIX_FMT_SGRBG12 ('BA12'), V4L2_PIX_FMT_SGBRG12 ('GB12'), V4L2_PIX_FMT_SBGGR12 ('BG12'),
+***************************************************************************************************************************
+
+*man V4L2_PIX_FMT_SRGGB12(2)*
+
+V4L2_PIX_FMT_SGRBG12
+V4L2_PIX_FMT_SGBRG12
+V4L2_PIX_FMT_SBGGR12
+12-bit Bayer formats expanded to 16 bits
+
+
+Description
+===========
+
+These four pixel formats are raw sRGB / Bayer formats with 12 bits per
+colour. Each colour component is stored in a 16-bit word, with 4 unused
+high bits filled with zeros. Each n-pixel row contains n/2 green samples
+and n/2 blue or red samples, with alternating red and blue rows. Bytes
+are stored in memory in little endian order. They are conventionally
+described as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example
+of one of these formats
+
+**Byte Order.**
+Each cell is one byte, high 6 bits in high bytes are 0.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - B\ :sub:`00low`
+
+ - B\ :sub:`00high`
+
+ - G\ :sub:`01low`
+
+ - G\ :sub:`01high`
+
+ - B\ :sub:`02low`
+
+ - B\ :sub:`02high`
+
+ - G\ :sub:`03low`
+
+ - G\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - G\ :sub:`10low`
+
+ - G\ :sub:`10high`
+
+ - R\ :sub:`11low`
+
+ - R\ :sub:`11high`
+
+ - G\ :sub:`12low`
+
+ - G\ :sub:`12high`
+
+ - R\ :sub:`13low`
+
+ - R\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - B\ :sub:`20low`
+
+ - B\ :sub:`20high`
+
+ - G\ :sub:`21low`
+
+ - G\ :sub:`21high`
+
+ - B\ :sub:`22low`
+
+ - B\ :sub:`22high`
+
+ - G\ :sub:`23low`
+
+ - G\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - G\ :sub:`30low`
+
+ - G\ :sub:`30high`
+
+ - R\ :sub:`31low`
+
+ - R\ :sub:`31high`
+
+ - G\ :sub:`32low`
+
+ - G\ :sub:`32high`
+
+ - R\ :sub:`33low`
+
+ - R\ :sub:`33high`
diff --git a/Documentation/media/uapi/v4l/pixfmt-srggb8.rst b/Documentation/media/uapi/v4l/pixfmt-srggb8.rst
new file mode 100644
index 000000000000..e88de4c48d47
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-srggb8.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-SRGGB8:
+
+****************************
+V4L2_PIX_FMT_SRGGB8 ('RGGB')
+****************************
+
+*man V4L2_PIX_FMT_SRGGB8(2)*
+
+Bayer RGB format
+
+
+Description
+===========
+
+This is commonly the native format of digital cameras, reflecting the
+arrangement of sensors on the CCD device. Only one red, green or blue
+value is given for each pixel. Missing components must be interpolated
+from neighbouring pixels. From left to right the first row consists of a
+red and green value, the second row of a green and blue value. This
+scheme repeats to the right and down for every two columns and rows.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - R\ :sub:`00`
+
+ - G\ :sub:`01`
+
+ - R\ :sub:`02`
+
+ - G\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - G\ :sub:`10`
+
+ - B\ :sub:`11`
+
+ - G\ :sub:`12`
+
+ - B\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - R\ :sub:`20`
+
+ - G\ :sub:`21`
+
+ - R\ :sub:`22`
+
+ - G\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - G\ :sub:`30`
+
+ - B\ :sub:`31`
+
+ - G\ :sub:`32`
+
+ - B\ :sub:`33`
diff --git a/Documentation/media/uapi/v4l/pixfmt-uv8.rst b/Documentation/media/uapi/v4l/pixfmt-uv8.rst
new file mode 100644
index 000000000000..fa8f7ee9fee1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-uv8.rst
@@ -0,0 +1,76 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-UV8:
+
+************************
+V4L2_PIX_FMT_UV8 ('UV8')
+************************
+
+*man V4L2_PIX_FMT_UV8(2)*
+
+UV plane interleaved
+
+
+Description
+===========
+
+In this format there is no Y plane, Only CbCr plane. ie (UV interleaved)
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Cb\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - Cr\ :sub:`31`
diff --git a/Documentation/media/uapi/v4l/pixfmt-uyvy.rst b/Documentation/media/uapi/v4l/pixfmt-uyvy.rst
new file mode 100644
index 000000000000..87b0081d44ee
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-uyvy.rst
@@ -0,0 +1,197 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-UYVY:
+
+**************************
+V4L2_PIX_FMT_UYVY ('UYVY')
+**************************
+
+*man V4L2_PIX_FMT_UYVY(2)*
+
+Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
+memory
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-vyuy.rst b/Documentation/media/uapi/v4l/pixfmt-vyuy.rst
new file mode 100644
index 000000000000..5d8f99f173b6
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-vyuy.rst
@@ -0,0 +1,195 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-VYUY:
+
+**************************
+V4L2_PIX_FMT_VYUY ('VYUY')
+**************************
+
+*man V4L2_PIX_FMT_VYUY(2)*
+
+Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
+memory
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`00`
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`10`
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`20`
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`30`
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-y10.rst b/Documentation/media/uapi/v4l/pixfmt-y10.rst
new file mode 100644
index 000000000000..d22f77138289
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y10.rst
@@ -0,0 +1,110 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y10:
+
+*************************
+V4L2_PIX_FMT_Y10 ('Y10 ')
+*************************
+
+*man V4L2_PIX_FMT_Y10(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 10 bits per pixel. Pixels are
+stored in 16-bit words with unused high bits padded with 0. The least
+significant byte is stored at lower memory addresses (little-endian).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`03low`
+
+ - Y'\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`13low`
+
+ - Y'\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`23low`
+
+ - Y'\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`33low`
+
+ - Y'\ :sub:`33high`
diff --git a/Documentation/media/uapi/v4l/pixfmt-y10b.rst b/Documentation/media/uapi/v4l/pixfmt-y10b.rst
new file mode 100644
index 000000000000..5b50cd61e654
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y10b.rst
@@ -0,0 +1,45 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y10BPACK:
+
+******************************
+V4L2_PIX_FMT_Y10BPACK ('Y10B')
+******************************
+
+*man V4L2_PIX_FMT_Y10BPACK(2)*
+
+Grey-scale image as a bit-packed array
+
+
+Description
+===========
+
+This is a packed grey-scale image format with a depth of 10 bits per
+pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel,
+with no padding between them and with the most significant bits coming
+first from the left.
+
+**Bit-packed representation.**
+
+pixels cross the byte boundary and have a ratio of 5 bytes for each 4
+pixels.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - Y'\ :sub:`00[9:2]`
+
+ - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]`
+
+ - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]`
+
+ - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]`
+
+ - Y'\ :sub:`03[7:0]`
diff --git a/Documentation/media/uapi/v4l/pixfmt-y12.rst b/Documentation/media/uapi/v4l/pixfmt-y12.rst
new file mode 100644
index 000000000000..7729bcbf3350
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y12.rst
@@ -0,0 +1,110 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y12:
+
+*************************
+V4L2_PIX_FMT_Y12 ('Y12 ')
+*************************
+
+*man V4L2_PIX_FMT_Y12(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 12 bits per pixel. Pixels are
+stored in 16-bit words with unused high bits padded with 0. The least
+significant byte is stored at lower memory addresses (little-endian).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`03low`
+
+ - Y'\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`13low`
+
+ - Y'\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`23low`
+
+ - Y'\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`33low`
+
+ - Y'\ :sub:`33high`
diff --git a/Documentation/media/uapi/v4l/pixfmt-y12i.rst b/Documentation/media/uapi/v4l/pixfmt-y12i.rst
new file mode 100644
index 000000000000..8967e8c33b47
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y12i.rst
@@ -0,0 +1,44 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y12I:
+
+**************************
+V4L2_PIX_FMT_Y12I ('Y12I')
+**************************
+
+*man V4L2_PIX_FMT_Y12I(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 12 bits per pixel, but with
+pixels from 2 sources interleaved and bit-packed. Each pixel is stored
+in a 24-bit word in the little-endian order. On a little-endian machine
+these pixels can be deinterlaced using
+
+.. code-block:: c
+
+ __u8 *buf;
+ left0 = 0xfff & *(__u16 *)buf;
+ right0 = *(__u16 *)(buf + 1) >> 4;
+
+**Bit-packed representation.**
+pixels cross the byte boundary and have a ratio of 3 bytes for each
+interleaved pixel.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1
+
+
+ - .. row 1
+
+ - Y'\ :sub:`0left[7:0]`
+
+ - Y'\ :sub:`0right[3:0]`\ Y'\ :sub:`0left[11:8]`
+
+ - Y'\ :sub:`0right[11:4]`
diff --git a/Documentation/media/uapi/v4l/pixfmt-y16-be.rst b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst
new file mode 100644
index 000000000000..0c61a10018c2
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y16-be.rst
@@ -0,0 +1,111 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y16-BE:
+
+****************************************
+V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31))
+****************************************
+
+*man V4L2_PIX_FMT_Y16_BE(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 16 bits per pixel. The most
+significant byte is stored at lower memory addresses (big-endian). Note
+the actual sampling precision may be lower than 16 bits, for example 10
+bits per pixel with values in range 0 to 1023.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`03high`
+
+ - Y'\ :sub:`03low`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`13high`
+
+ - Y'\ :sub:`13low`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`23high`
+
+ - Y'\ :sub:`23low`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`33high`
+
+ - Y'\ :sub:`33low`
diff --git a/Documentation/media/uapi/v4l/pixfmt-y16.rst b/Documentation/media/uapi/v4l/pixfmt-y16.rst
new file mode 100644
index 000000000000..a8d4b7192ae3
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y16.rst
@@ -0,0 +1,111 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y16:
+
+*************************
+V4L2_PIX_FMT_Y16 ('Y16 ')
+*************************
+
+*man V4L2_PIX_FMT_Y16(2)*
+
+Grey-scale image
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 16 bits per pixel. The least
+significant byte is stored at lower memory addresses (little-endian).
+Note the actual sampling precision may be lower than 16 bits, for
+example 10 bits per pixel with values in range 0 to 1023.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00low`
+
+ - Y'\ :sub:`00high`
+
+ - Y'\ :sub:`01low`
+
+ - Y'\ :sub:`01high`
+
+ - Y'\ :sub:`02low`
+
+ - Y'\ :sub:`02high`
+
+ - Y'\ :sub:`03low`
+
+ - Y'\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10low`
+
+ - Y'\ :sub:`10high`
+
+ - Y'\ :sub:`11low`
+
+ - Y'\ :sub:`11high`
+
+ - Y'\ :sub:`12low`
+
+ - Y'\ :sub:`12high`
+
+ - Y'\ :sub:`13low`
+
+ - Y'\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20low`
+
+ - Y'\ :sub:`20high`
+
+ - Y'\ :sub:`21low`
+
+ - Y'\ :sub:`21high`
+
+ - Y'\ :sub:`22low`
+
+ - Y'\ :sub:`22high`
+
+ - Y'\ :sub:`23low`
+
+ - Y'\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30low`
+
+ - Y'\ :sub:`30high`
+
+ - Y'\ :sub:`31low`
+
+ - Y'\ :sub:`31high`
+
+ - Y'\ :sub:`32low`
+
+ - Y'\ :sub:`32high`
+
+ - Y'\ :sub:`33low`
+
+ - Y'\ :sub:`33high`
diff --git a/Documentation/media/uapi/v4l/pixfmt-y41p.rst b/Documentation/media/uapi/v4l/pixfmt-y41p.rst
new file mode 100644
index 000000000000..4760174a4668
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y41p.rst
@@ -0,0 +1,274 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y41P:
+
+**************************
+V4L2_PIX_FMT_Y41P ('Y41P')
+**************************
+
+*man V4L2_PIX_FMT_Y41P(2)*
+
+Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1
+
+
+Description
+===========
+
+In this format each 12 bytes is eight pixels. In the twelve bytes are
+two CbCr pairs and eight Y's. The first CbCr pair goes with the first
+four Y's, and the second CbCr pair goes with the other four Y's. The Cb
+and Cr components have one fourth the horizontal resolution of the Y
+component.
+
+Do not confuse this format with
+:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived
+from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1
+*planar*".
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - Y'\ :sub:`04`
+
+ - Y'\ :sub:`05`
+
+ - Y'\ :sub:`06`
+
+ - Y'\ :sub:`07`
+
+ - .. row 2
+
+ - start + 12:
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - Y'\ :sub:`14`
+
+ - Y'\ :sub:`15`
+
+ - Y'\ :sub:`16`
+
+ - Y'\ :sub:`17`
+
+ - .. row 3
+
+ - start + 24:
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - Y'\ :sub:`24`
+
+ - Y'\ :sub:`25`
+
+ - Y'\ :sub:`26`
+
+ - Y'\ :sub:`27`
+
+ - .. row 4
+
+ - start + 36:
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+ - Y'\ :sub:`34`
+
+ - Y'\ :sub:`35`
+
+ - Y'\ :sub:`36`
+
+ - Y'\ :sub:`37`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ - 1
+
+ -
+ - 2
+
+ - 3
+
+ - 4
+
+ - 5
+
+ -
+ - 6
+
+ - 7
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-y8i.rst b/Documentation/media/uapi/v4l/pixfmt-y8i.rst
new file mode 100644
index 000000000000..7fa16ee85ab7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-y8i.rst
@@ -0,0 +1,111 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Y8I:
+
+*************************
+V4L2_PIX_FMT_Y8I ('Y8I ')
+*************************
+
+*man V4L2_PIX_FMT_Y8I(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a grey-scale image with a depth of 8 bits per pixel, but with
+pixels from 2 sources interleaved. Each pixel is stored in a 16-bit
+word. E.g. the R200 RealSense camera stores pixel from the left sensor
+in lower and from the right sensor in the higher 8 bits.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00left`
+
+ - Y'\ :sub:`00right`
+
+ - Y'\ :sub:`01left`
+
+ - Y'\ :sub:`01right`
+
+ - Y'\ :sub:`02left`
+
+ - Y'\ :sub:`02right`
+
+ - Y'\ :sub:`03left`
+
+ - Y'\ :sub:`03right`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10left`
+
+ - Y'\ :sub:`10right`
+
+ - Y'\ :sub:`11left`
+
+ - Y'\ :sub:`11right`
+
+ - Y'\ :sub:`12left`
+
+ - Y'\ :sub:`12right`
+
+ - Y'\ :sub:`13left`
+
+ - Y'\ :sub:`13right`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20left`
+
+ - Y'\ :sub:`20right`
+
+ - Y'\ :sub:`21left`
+
+ - Y'\ :sub:`21right`
+
+ - Y'\ :sub:`22left`
+
+ - Y'\ :sub:`22right`
+
+ - Y'\ :sub:`23left`
+
+ - Y'\ :sub:`23right`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30left`
+
+ - Y'\ :sub:`30right`
+
+ - Y'\ :sub:`31left`
+
+ - Y'\ :sub:`31right`
+
+ - Y'\ :sub:`32left`
+
+ - Y'\ :sub:`32right`
+
+ - Y'\ :sub:`33left`
+
+ - Y'\ :sub:`33right`
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv410.rst b/Documentation/media/uapi/v4l/pixfmt-yuv410.rst
new file mode 100644
index 000000000000..8a5d1a2ee005
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuv410.rst
@@ -0,0 +1,208 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVU410:
+.. _v4l2-pix-fmt-yuv410:
+
+**********************************************************
+V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')
+**********************************************************
+
+*man V4L2_PIX_FMT_YVU410(2)*
+
+V4L2_PIX_FMT_YUV410
+Planar formats with ¼ horizontal and vertical chroma resolution, also
+known as YUV 4:1:0
+
+
+Description
+===========
+
+These are planar formats, as opposed to a packed format. The three
+components are separated into three sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``,
+the Cr plane immediately follows the Y plane in memory. The Cr plane is
+¼ the width and ¼ the height of the Y plane (and of the image). Each Cr
+belongs to 16 pixels, a four-by-four square of the image. Following the
+Cr plane is the Cb plane, just like the Cr plane.
+``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first,
+then the Cr plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have ¼ as many pad bytes after their rows. In other words, four Cx rows
+(including padding) are exactly as long as one Y row (including
+padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cr\ :sub:`00`
+
+ - .. row 6
+
+ - start + 17:
+
+ - Cb\ :sub:`00`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+ -
+ -
+ -
+ - C
+
+ -
+ -
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst b/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst
new file mode 100644
index 000000000000..f85e3f388cbe
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuv411p.rst
@@ -0,0 +1,214 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV411P:
+
+*****************************
+V4L2_PIX_FMT_YUV411P ('411P')
+*****************************
+
+*man V4L2_PIX_FMT_YUV411P(2)*
+
+Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1.
+Planar layout as opposed to ``V4L2_PIX_FMT_Y41P``
+
+
+Description
+===========
+
+This format is not commonly used. This is a planar format similar to the
+4:2:2 planar format except with half as many chroma. The three
+components are separated into three sub-images or planes. The Y plane is
+first. The Y plane has one byte per pixel. The Cb plane immediately
+follows the Y plane in memory. The Cb plane is ¼ the width of the Y
+plane (and of the image). Each Cb belongs to 4 pixels all on the same
+row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
+Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane,
+just like the Cb plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have ¼ as many pad bytes after their rows. In other words, four C x rows
+(including padding) is exactly as long as one Y row (including padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - .. row 6
+
+ - start + 17:
+
+ - Cb\ :sub:`10`
+
+ - .. row 7
+
+ - start + 18:
+
+ - Cb\ :sub:`20`
+
+ - .. row 8
+
+ - start + 19:
+
+ - Cb\ :sub:`30`
+
+ - .. row 9
+
+ - start + 20:
+
+ - Cr\ :sub:`00`
+
+ - .. row 10
+
+ - start + 21:
+
+ - Cr\ :sub:`10`
+
+ - .. row 11
+
+ - start + 22:
+
+ - Cr\ :sub:`20`
+
+ - .. row 12
+
+ - start + 23:
+
+ - Cr\ :sub:`30`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ - 1
+
+ -
+ - 2
+
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv420.rst b/Documentation/media/uapi/v4l/pixfmt-yuv420.rst
new file mode 100644
index 000000000000..b22e64c14f67
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuv420.rst
@@ -0,0 +1,239 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVU420:
+.. _V4L2-PIX-FMT-YUV420:
+
+**********************************************************
+V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')
+**********************************************************
+
+*man V4L2_PIX_FMT_YVU420(2)*
+
+V4L2_PIX_FMT_YUV420
+Planar formats with ½ horizontal and vertical chroma resolution, also
+known as YUV 4:2:0
+
+
+Description
+===========
+
+These are planar formats, as opposed to a packed format. The three
+components are separated into three sub- images or planes. The Y plane
+is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in
+memory. The Cr plane is half the width and half the height of the Y
+plane (and of the image). Each Cr belongs to four pixels, a two-by-two
+square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane
+is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the
+same except the Cb plane comes first, then the Cr plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 6
+
+ - start + 18:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 7
+
+ - start + 20:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 8
+
+ - start + 22:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst
new file mode 100644
index 000000000000..4dab85090d7d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuv420m.rst
@@ -0,0 +1,254 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV420M:
+.. _v4l2-pix-fmt-yvu420m:
+
+************************************************************
+V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV420M(2)*
+
+V4L2_PIX_FMT_YVU420M
+Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with
+planes non contiguous in memory.
+
+
+Description
+===========
+
+This is a multi-planar format, as opposed to a packed format. The three
+components are separated into three sub-images or planes.
+
+The Y plane is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which
+is half the width and half the height of the Y plane (and of the image).
+Each Cb belongs to four pixels, a two-by-two square of the image. For
+example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
+Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane,
+is in the third plane.
+
+``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the
+second plane and the Cb data in the third plane.
+
+If the Y plane has pad bytes after each row, then the Cb and Cr planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 2:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 8
+
+ -
+
+ - .. row 9
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 10
+
+ - start2 + 2:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 3
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 4
+
+ - 1
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - 2
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ - .. row 7
+
+ -
+ -
+ - C
+
+ -
+ -
+ -
+ - C
+
+ -
+
+ - .. row 8
+
+ - 3
+
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
+
+ -
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst
new file mode 100644
index 000000000000..ccb67284133a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuv422m.rst
@@ -0,0 +1,258 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV422M:
+.. _v4l2-pix-fmt-yvu422m:
+
+************************************************************
+V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV422M(2)*
+
+V4L2_PIX_FMT_YVU422M
+Planar formats with ½ horizontal resolution, also known as YUV and YVU
+4:2:2
+
+
+Description
+===========
+
+This is a multi-planar format, as opposed to a packed format. The three
+components are separated into three sub-images or planes.
+
+The Y plane is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which
+is half the width of the Y plane (and of the image). Each Cb belongs to
+two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third
+plane.
+
+``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the
+second plane and the Cb data in the third plane.
+
+If the Y plane has pad bytes after each row, then the Cb and Cr planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 7
+
+ - start1 + 2:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 8
+
+ - start1 + 4:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - .. row 9
+
+ - start1 + 6:
+
+ - Cb\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 12
+
+ - start2 + 2:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 13
+
+ - start2 + 4:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - .. row 14
+
+ - start2 + 6:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst b/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst
new file mode 100644
index 000000000000..9f34762adf18
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuv422p.rst
@@ -0,0 +1,240 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV422P:
+
+*****************************
+V4L2_PIX_FMT_YUV422P ('422P')
+*****************************
+
+*man V4L2_PIX_FMT_YUV422P(2)*
+
+Format with ½ horizontal chroma resolution, also known as YUV 4:2:2.
+Planar layout as opposed to ``V4L2_PIX_FMT_YUYV``
+
+
+Description
+===========
+
+This format is not commonly used. This is a planar version of the YUYV
+format. The three components are separated into three sub-images or
+planes. The Y plane is first. The Y plane has one byte per pixel. The Cb
+plane immediately follows the Y plane in memory. The Cb plane is half
+the width of the Y plane (and of the image). Each Cb belongs to two
+pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
+Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb
+plane.
+
+If the Y plane has pad bytes after each row, then the Cr and Cb planes
+have half as many pad bytes after their rows. In other words, two Cx
+rows (including padding) is exactly as long as one Y row (including
+padding).
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ - start + 16:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - .. row 6
+
+ - start + 18:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - .. row 7
+
+ - start + 20:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - .. row 8
+
+ - start + 22:
+
+ - Cb\ :sub:`30`
+
+ - Cb\ :sub:`31`
+
+ - .. row 9
+
+ - start + 24:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - .. row 10
+
+ - start + 26:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - .. row 11
+
+ - start + 28:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - .. row 12
+
+ - start + 30:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst b/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst
new file mode 100644
index 000000000000..04f34508b934
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuv444m.rst
@@ -0,0 +1,266 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUV444M:
+.. _v4l2-pix-fmt-yvu444m:
+
+************************************************************
+V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42')
+************************************************************
+
+*man V4L2_PIX_FMT_YUV444M(2)*
+
+V4L2_PIX_FMT_YVU444M
+Planar formats with full horizontal resolution, also known as YUV and
+YVU 4:4:4
+
+
+Description
+===========
+
+This is a multi-planar format, as opposed to a packed format. The three
+components are separated into three sub-images or planes.
+
+The Y plane is first. The Y plane has one byte per pixel. For
+``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which
+is the same width and height as the Y plane (and as the image). The Cr
+data, just like the Cb plane, is in the third plane.
+
+``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the
+second plane and the Cb data in the third plane.
+
+If the Y plane has pad bytes after each row, then the Cb and Cr planes
+have the same number of pad bytes after their rows.
+
+``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be
+used only in drivers and applications that support the multi-planar API,
+described in :ref:`planar-apis`.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1
+
+
+ - .. row 1
+
+ - start0 + 0:
+
+ - Y'\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Y'\ :sub:`02`
+
+ - Y'\ :sub:`03`
+
+ - .. row 2
+
+ - start0 + 4:
+
+ - Y'\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Y'\ :sub:`12`
+
+ - Y'\ :sub:`13`
+
+ - .. row 3
+
+ - start0 + 8:
+
+ - Y'\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Y'\ :sub:`22`
+
+ - Y'\ :sub:`23`
+
+ - .. row 4
+
+ - start0 + 12:
+
+ - Y'\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Y'\ :sub:`32`
+
+ - Y'\ :sub:`33`
+
+ - .. row 5
+
+ -
+
+ - .. row 6
+
+ - start1 + 0:
+
+ - Cb\ :sub:`00`
+
+ - Cb\ :sub:`01`
+
+ - Cb\ :sub:`02`
+
+ - Cb\ :sub:`03`
+
+ - .. row 7
+
+ - start1 + 4:
+
+ - Cb\ :sub:`10`
+
+ - Cb\ :sub:`11`
+
+ - Cb\ :sub:`12`
+
+ - Cb\ :sub:`13`
+
+ - .. row 8
+
+ - start1 + 8:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cb\ :sub:`22`
+
+ - Cb\ :sub:`23`
+
+ - .. row 9
+
+ - start1 + 12:
+
+ - Cb\ :sub:`20`
+
+ - Cb\ :sub:`21`
+
+ - Cb\ :sub:`32`
+
+ - Cb\ :sub:`33`
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ - start2 + 0:
+
+ - Cr\ :sub:`00`
+
+ - Cr\ :sub:`01`
+
+ - Cr\ :sub:`02`
+
+ - Cr\ :sub:`03`
+
+ - .. row 12
+
+ - start2 + 4:
+
+ - Cr\ :sub:`10`
+
+ - Cr\ :sub:`11`
+
+ - Cr\ :sub:`12`
+
+ - Cr\ :sub:`13`
+
+ - .. row 13
+
+ - start2 + 8:
+
+ - Cr\ :sub:`20`
+
+ - Cr\ :sub:`21`
+
+ - Cr\ :sub:`22`
+
+ - Cr\ :sub:`23`
+
+ - .. row 14
+
+ - start2 + 12:
+
+ - Cr\ :sub:`30`
+
+ - Cr\ :sub:`31`
+
+ - Cr\ :sub:`32`
+
+ - Cr\ :sub:`33`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ - 1
+
+ - 2
+
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - .. row 3
+
+ - 1
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - .. row 4
+
+ - 2
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - .. row 5
+
+ - 3
+
+ - YC
+
+ - YC
+
+ - YC
+
+ - YC
diff --git a/Documentation/media/uapi/v4l/pixfmt-yuyv.rst b/Documentation/media/uapi/v4l/pixfmt-yuyv.rst
new file mode 100644
index 000000000000..52917dfa9261
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yuyv.rst
@@ -0,0 +1,205 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YUYV:
+
+**************************
+V4L2_PIX_FMT_YUYV ('YUYV')
+**************************
+
+*man V4L2_PIX_FMT_YUYV(2)*
+
+Packed format with ½ horizontal chroma resolution, also known as YUV
+4:2:2
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV``
+is known in the Windows environment as YUY2.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`02`
+
+ - Cb\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - Cr\ :sub:`01`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10`
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`12`
+
+ - Cb\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - Cr\ :sub:`11`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20`
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`22`
+
+ - Cb\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - Cr\ :sub:`21`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30`
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`32`
+
+ - Cb\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+ - Cr\ :sub:`31`
+
+
+**Color Sample Location..**
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ -
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ -
+ - Y
+
+ - C
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-yvyu.rst b/Documentation/media/uapi/v4l/pixfmt-yvyu.rst
new file mode 100644
index 000000000000..e466052b68b2
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-yvyu.rst
@@ -0,0 +1,195 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-YVYU:
+
+**************************
+V4L2_PIX_FMT_YVYU ('YVYU')
+**************************
+
+*man V4L2_PIX_FMT_YVYU(2)*
+
+Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
+memory
+
+
+Description
+===========
+
+In this format each four bytes is two pixels. Each four bytes is two
+Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
+belong to both pixels. As you can see, the Cr and Cb components have
+half the horizontal resolution of the Y component.
+
+**Byte Order.**
+Each cell is one byte.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Y'\ :sub:`00`
+
+ - Cr\ :sub:`00`
+
+ - Y'\ :sub:`01`
+
+ - Cb\ :sub:`00`
+
+ - Y'\ :sub:`02`
+
+ - Cr\ :sub:`01`
+
+ - Y'\ :sub:`03`
+
+ - Cb\ :sub:`01`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Y'\ :sub:`10`
+
+ - Cr\ :sub:`10`
+
+ - Y'\ :sub:`11`
+
+ - Cb\ :sub:`10`
+
+ - Y'\ :sub:`12`
+
+ - Cr\ :sub:`11`
+
+ - Y'\ :sub:`13`
+
+ - Cb\ :sub:`11`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Y'\ :sub:`20`
+
+ - Cr\ :sub:`20`
+
+ - Y'\ :sub:`21`
+
+ - Cb\ :sub:`20`
+
+ - Y'\ :sub:`22`
+
+ - Cr\ :sub:`21`
+
+ - Y'\ :sub:`23`
+
+ - Cb\ :sub:`21`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Y'\ :sub:`30`
+
+ - Cr\ :sub:`30`
+
+ - Y'\ :sub:`31`
+
+ - Cb\ :sub:`30`
+
+ - Y'\ :sub:`32`
+
+ - Cr\ :sub:`31`
+
+ - Y'\ :sub:`33`
+
+ - Cb\ :sub:`31`
+
+
+**Color Sample Location..**
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - 0
+
+ -
+ - 1
+
+ - 2
+
+ -
+ - 3
+
+ - .. row 2
+
+ - 0
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 3
+
+ - 1
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 4
+
+ - 2
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
+
+ - .. row 5
+
+ - 3
+
+ - Y
+
+ - C
+
+ - Y
+
+ - Y
+
+ - C
+
+ - Y
diff --git a/Documentation/media/uapi/v4l/pixfmt-z16.rst b/Documentation/media/uapi/v4l/pixfmt-z16.rst
new file mode 100644
index 000000000000..c5cce2db78b6
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt-z16.rst
@@ -0,0 +1,111 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _V4L2-PIX-FMT-Z16:
+
+*************************
+V4L2_PIX_FMT_Z16 ('Z16 ')
+*************************
+
+*man V4L2_PIX_FMT_Z16(2)*
+
+Interleaved grey-scale image, e.g. from a stereo-pair
+
+
+Description
+===========
+
+This is a 16-bit format, representing depth data. Each pixel is a
+distance to the respective point in the image coordinates. Distance unit
+can vary and has to be negotiated with the device separately. Each pixel
+is stored in a 16-bit word in the little endian byte order.
+
+**Byte Order.**
+Each cell is one byte.
+
+
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 2 1 1 1 1 1 1 1 1
+
+
+ - .. row 1
+
+ - start + 0:
+
+ - Z\ :sub:`00low`
+
+ - Z\ :sub:`00high`
+
+ - Z\ :sub:`01low`
+
+ - Z\ :sub:`01high`
+
+ - Z\ :sub:`02low`
+
+ - Z\ :sub:`02high`
+
+ - Z\ :sub:`03low`
+
+ - Z\ :sub:`03high`
+
+ - .. row 2
+
+ - start + 8:
+
+ - Z\ :sub:`10low`
+
+ - Z\ :sub:`10high`
+
+ - Z\ :sub:`11low`
+
+ - Z\ :sub:`11high`
+
+ - Z\ :sub:`12low`
+
+ - Z\ :sub:`12high`
+
+ - Z\ :sub:`13low`
+
+ - Z\ :sub:`13high`
+
+ - .. row 3
+
+ - start + 16:
+
+ - Z\ :sub:`20low`
+
+ - Z\ :sub:`20high`
+
+ - Z\ :sub:`21low`
+
+ - Z\ :sub:`21high`
+
+ - Z\ :sub:`22low`
+
+ - Z\ :sub:`22high`
+
+ - Z\ :sub:`23low`
+
+ - Z\ :sub:`23high`
+
+ - .. row 4
+
+ - start + 24:
+
+ - Z\ :sub:`30low`
+
+ - Z\ :sub:`30high`
+
+ - Z\ :sub:`31low`
+
+ - Z\ :sub:`31high`
+
+ - Z\ :sub:`32low`
+
+ - Z\ :sub:`32high`
+
+ - Z\ :sub:`33low`
+
+ - Z\ :sub:`33high`
diff --git a/Documentation/media/uapi/v4l/pixfmt.rst b/Documentation/media/uapi/v4l/pixfmt.rst
new file mode 100644
index 000000000000..81222a99f7ce
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pixfmt.rst
@@ -0,0 +1,35 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _pixfmt:
+
+#############
+Image Formats
+#############
+The V4L2 API was primarily designed for devices exchanging image data
+with applications. The :ref:`struct v4l2_pix_format <v4l2-pix-format>` and
+:ref:`struct v4l2_pix_format_mplane <v4l2-pix-format-mplane>` structures define the
+format and layout of an image in memory. The former is used with the
+single-planar API, while the latter is used with the multi-planar
+version (see :ref:`planar-apis`). Image formats are negotiated with
+the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. (The explanations here
+focus on video capturing and output, for overlay frame buffer formats
+see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.)
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-002
+ pixfmt-003
+ pixfmt-004
+ colorspaces
+ pixfmt-006
+ pixfmt-007
+ pixfmt-008
+ pixfmt-indexed
+ pixfmt-rgb
+ yuv-formats
+ depth-formats
+ pixfmt-013
+ sdr-formats
+ pixfmt-reserved
diff --git a/Documentation/media/uapi/v4l/planar-apis.rst b/Documentation/media/uapi/v4l/planar-apis.rst
new file mode 100644
index 000000000000..5fe2e1188230
--- /dev/null
+++ b/Documentation/media/uapi/v4l/planar-apis.rst
@@ -0,0 +1,61 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _planar-apis:
+
+*****************************
+Single- and multi-planar APIs
+*****************************
+
+Some devices require data for each input or output video frame to be
+placed in discontiguous memory buffers. In such cases, one video frame
+has to be addressed using more than one memory address, i.e. one pointer
+per "plane". A plane is a sub-buffer of the current frame. For examples
+of such formats see :ref:`pixfmt`.
+
+Initially, V4L2 API did not support multi-planar buffers and a set of
+extensions has been introduced to handle them. Those extensions
+constitute what is being referred to as the "multi-planar API".
+
+Some of the V4L2 API calls and structures are interpreted differently,
+depending on whether single- or multi-planar API is being used. An
+application can choose whether to use one or the other by passing a
+corresponding buffer type to its ioctl calls. Multi-planar versions of
+buffer types are suffixed with an ``_MPLANE`` string. For a list of
+available multi-planar buffer types see enum
+:ref:`v4l2_buf_type <v4l2-buf-type>`.
+
+
+Multi-planar formats
+====================
+
+Multi-planar API introduces new multi-planar formats. Those formats use
+a separate set of FourCC codes. It is important to distinguish between
+the multi-planar API and a multi-planar format. Multi-planar API calls
+can handle all single-planar formats as well (as long as they are passed
+in multi-planar API structures), while the single-planar API cannot
+handle multi-planar formats.
+
+
+Calls that distinguish between single and multi-planar APIs
+===========================================================
+
+:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
+ Two additional multi-planar capabilities are added. They can be set
+ together with non-multi-planar ones for devices that handle both
+ single- and multi-planar formats.
+
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
+ New structures for describing multi-planar formats are added: struct
+ :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and
+ struct :ref:`v4l2_plane_pix_format <v4l2-plane-pix-format>`.
+ Drivers may define new multi-planar formats, which have distinct
+ FourCC codes from the existing single-planar ones.
+
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
+ A new struct :ref:`v4l2_plane <v4l2-plane>` structure for
+ describing planes is added. Arrays of this structure are passed in
+ the new ``m.planes`` field of struct
+ :ref:`v4l2_buffer <v4l2-buffer>`.
+
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
+ Will allocate multi-planar buffers as requested.
diff --git a/Documentation/media/uapi/v4l/querycap.rst b/Documentation/media/uapi/v4l/querycap.rst
new file mode 100644
index 000000000000..c19cce7a816f
--- /dev/null
+++ b/Documentation/media/uapi/v4l/querycap.rst
@@ -0,0 +1,34 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _querycap:
+
+*********************
+Querying Capabilities
+*********************
+
+Because V4L2 covers a wide variety of devices not all aspects of the API
+are equally applicable to all types of devices. Furthermore devices of
+the same type have different capabilities and this specification permits
+the omission of a few complicated and less important parts of the API.
+
+The :ref:`VIDIOC_QUERYCAP` ioctl is available to
+check if the kernel device is compatible with this specification, and to
+query the :ref:`functions <devices>` and :ref:`I/O methods <io>`
+supported by the device.
+
+Starting with kernel version 3.1, :ref:`VIDIOC_QUERYCAP`
+will return the V4L2 API version used by the driver, with generally
+matches the Kernel version. There's no need of using
+:ref:`VIDIOC_QUERYCAP` to check if a specific ioctl
+is supported, the V4L2 core now returns ``ENOTTY`` if a driver doesn't
+provide support for an ioctl.
+
+Other features can be queried by calling the respective ioctl, for
+example :ref:`VIDIOC_ENUMINPUT` to learn about the
+number, types and names of video connectors on the device. Although
+abstraction is a major objective of this API, the
+:ref:`VIDIOC_QUERYCAP` ioctl also allows driver
+specific applications to reliably identify the driver.
+
+All V4L2 drivers must support :ref:`VIDIOC_QUERYCAP`.
+Applications should always call this ioctl after opening the device.
diff --git a/Documentation/media/uapi/v4l/rw.rst b/Documentation/media/uapi/v4l/rw.rst
new file mode 100644
index 000000000000..66ba54648c45
--- /dev/null
+++ b/Documentation/media/uapi/v4l/rw.rst
@@ -0,0 +1,47 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _rw:
+
+**********
+Read/Write
+**********
+
+Input and output devices support the :ref:`read() <func-read>` and
+:ref:`write() <func-write>` function, respectively, when the
+``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`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):
+
+
+.. code-block:: none
+
+ $ 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 :ref:`read() <func-read>`
+function, to write the :ref:`write() <func-write>` function. Drivers
+must implement one I/O method if they exchange data with applications,
+but it need not be this. [1]_ When reading or writing is supported, the
+driver must also support the :ref:`select() <func-select>` and
+:ref:`poll() <func-poll>` function. [2]_
+
+.. [1]
+ 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.
+
+.. [2]
+ At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
+ the same, and :ref:`select() <func-select>` is too important to be optional.
diff --git a/Documentation/media/uapi/v4l/sdr-formats.rst b/Documentation/media/uapi/v4l/sdr-formats.rst
new file mode 100644
index 000000000000..f863c08f1add
--- /dev/null
+++ b/Documentation/media/uapi/v4l/sdr-formats.rst
@@ -0,0 +1,19 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _sdr-formats:
+
+***********
+SDR Formats
+***********
+
+These formats are used for :ref:`SDR <sdr>` interface only.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-sdr-cu08
+ pixfmt-sdr-cu16le
+ pixfmt-sdr-cs08
+ pixfmt-sdr-cs14le
+ pixfmt-sdr-ru12le
diff --git a/Documentation/media/uapi/v4l/selection-api-002.rst b/Documentation/media/uapi/v4l/selection-api-002.rst
new file mode 100644
index 000000000000..09ca93f91bf7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection-api-002.rst
@@ -0,0 +1,28 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+************
+Introduction
+************
+
+Some video capture devices can sample a subsection of a picture and
+shrink or enlarge it to an image of arbitrary size. Next, the devices
+can insert the image into larger one. Some video output devices can crop
+part of an input image, scale it up or down and insert it at an
+arbitrary scan line and horizontal offset into a video signal. We call
+these abilities cropping, scaling and composing.
+
+On a video *capture* device the source is a video signal, and the
+cropping target determine the area actually sampled. The sink is an
+image stored in a memory buffer. The composing area specifies which part
+of the buffer is actually written to by the hardware.
+
+On a video *output* device the source is an image in a memory buffer,
+and the cropping target is a part of an image to be shown on a display.
+The sink is the display or the graphics screen. The application may
+select the part of display where the image should be displayed. The size
+and position of such a window is controlled by the compose target.
+
+Rectangles for all cropping and composing targets are defined even if
+the device does supports neither cropping nor composing. Their size and
+position will be fixed in such a case. If the device does not support
+scaling then the cropping and composing rectangles have the same size.
diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst
new file mode 100644
index 000000000000..15cb3b79f12c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection-api-003.rst
@@ -0,0 +1,20 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+*****************
+Selection targets
+*****************
+
+
+.. _sel-targets-capture:
+
+.. figure:: selection-api-003_files/selection.*
+ :alt: selection.png
+ :align: center
+
+ Cropping and composing targets
+
+ Targets used by a cropping, composing and scaling process
+
+
+
+See :ref:`v4l2-selection-targets` for more information.
diff --git a/Documentation/media/uapi/v4l/selection-api-003_files/selection.png b/Documentation/media/uapi/v4l/selection-api-003_files/selection.png
new file mode 100644
index 000000000000..bfc523eae570
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection-api-003_files/selection.png
Binary files differ
diff --git a/Documentation/media/uapi/v4l/selection-api-004.rst b/Documentation/media/uapi/v4l/selection-api-004.rst
new file mode 100644
index 000000000000..d782cd5b2117
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection-api-004.rst
@@ -0,0 +1,137 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+*************
+Configuration
+*************
+
+Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
+select an area in a video signal or a buffer, and to query for default
+settings and hardware limits.
+
+Video hardware can have various cropping, composing and scaling
+limitations. It may only scale up or down, support only discrete scaling
+factors, or have different scaling abilities in the horizontal and
+vertical directions. Also it may not support scaling at all. At the same
+time the cropping/composing rectangles may have to be aligned, and both
+the source and the sink may have arbitrary upper and lower size limits.
+Therefore, as usual, drivers are expected to adjust the requested
+parameters and return the actual values selected. An application can
+control the rounding behaviour using
+:ref:`constraint flags <v4l2-selection-flags>`.
+
+
+Configuration of video capture
+==============================
+
+See figure :ref:`sel-targets-capture` for examples of the selection
+targets available for a video capture device. It is recommended to
+configure the cropping targets before to the composing targets.
+
+The range of coordinates of the top left corner, width and height of
+areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
+target. It is recommended for the driver developers to put the top/left
+corner at position ``(0,0)``. The rectangle's coordinates are expressed
+in pixels.
+
+The top left corner, width and height of the source rectangle, that is
+the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
+It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
+active cropping area must lie completely inside the capture boundaries.
+The driver may further adjust the requested size and/or position
+according to hardware limitations.
+
+Each capture device has a default source rectangle, given by the
+``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall over what the
+driver writer considers the complete picture. Drivers shall set the
+active crop rectangle to the default when the driver is first loaded,
+but not later.
+
+The composing targets refer to a memory buffer. The limits of composing
+coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
+coordinates are expressed in pixels. The rectangle's top/left corner
+must be located at position ``(0,0)``. The width and height are equal to
+the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.
+
+The part of a buffer into which the image is inserted by the hardware is
+controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
+coordinates are also expressed in the same coordinate system as the
+bounds rectangle. The composing rectangle must lie completely inside
+bounds rectangle. The driver must adjust the composing rectangle to fit
+to the bounding limits. Moreover, the driver can perform other
+adjustments according to hardware limitations. The application can
+control rounding behaviour using
+:ref:`constraint flags <v4l2-selection-flags>`.
+
+For capture devices the default composing rectangle is queried using
+``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
+rectangle.
+
+The part of a buffer that is modified by the hardware is given by
+``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
+``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
+during insertion process. All pixels outside this rectangle *must not*
+be changed by the hardware. The content of pixels that lie inside the
+padded area but outside active area is undefined. The application can
+use the padded and active rectangles to detect where the rubbish pixels
+are located and remove them if needed.
+
+
+Configuration of video output
+=============================
+
+For output devices targets and ioctls are used similarly to the video
+capture case. The *composing* rectangle refers to the insertion of an
+image into a video signal. The cropping rectangles refer to a memory
+buffer. It is recommended to configure the composing targets before to
+the cropping targets.
+
+The cropping targets refer to the memory buffer that contains an image
+to be inserted into a video signal or graphical screen. The limits of
+cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
+All coordinates are expressed in pixels. The top/left corner is always
+point ``(0,0)``. The width and height is equal to the image size
+specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
+
+The top left corner, width and height of the source rectangle, that is
+the area from which image date are processed by the hardware, is given
+by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in in the
+same coordinate system as the bounds rectangle. The active cropping area
+must lie completely inside the crop boundaries and the driver may
+further adjust the requested size and/or position according to hardware
+limitations.
+
+For output devices the default cropping rectangle is queried using
+``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
+rectangle.
+
+The part of a video signal or graphics display where the image is
+inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
+target. The rectangle's coordinates are expressed in pixels. The
+composing rectangle must lie completely inside the bounds rectangle. The
+driver must adjust the area to fit to the bounding limits. Moreover, the
+driver can perform other adjustments according to hardware limitations.
+
+The device has a default composing rectangle, given by the
+``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
+the driver writer considers the complete picture. It is recommended for
+the driver developers to put the top/left corner at position ``(0,0)``.
+Drivers shall set the active composing rectangle to the default one when
+the driver is first loaded.
+
+The devices may introduce additional content to video signal other than
+an image from memory buffers. It includes borders around an image.
+However, such a padded area is driver-dependent feature not covered by
+this document. Driver developers are encouraged to keep padded rectangle
+equal to active one. The padded target is accessed by the
+``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
+from the ``V4L2_SEL_TGT_COMPOSE`` target.
+
+
+Scaling control
+===============
+
+An application can detect if scaling is performed by comparing the width
+and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
+``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
+scaling is applied. The application can compute the scaling ratios using
+these values.
diff --git a/Documentation/media/uapi/v4l/selection-api-005.rst b/Documentation/media/uapi/v4l/selection-api-005.rst
new file mode 100644
index 000000000000..94731a13efdb
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection-api-005.rst
@@ -0,0 +1,34 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+********************************
+Comparison with old cropping API
+********************************
+
+The selection API was introduced to cope with deficiencies of previous
+:ref:`API <crop>`, that was designed to control simple capture
+devices. Later the cropping API was adopted by video output drivers. The
+ioctls are used to select a part of the display were the video signal is
+inserted. It should be considered as an API abuse because the described
+operation is actually the composing. The selection API makes a clear
+distinction between composing and cropping operations by setting the
+appropriate targets. The V4L2 API lacks any support for composing to and
+cropping from an image inside a memory buffer. The application could
+configure a capture device to fill only a part of an image by abusing
+V4L2 API. Cropping a smaller image from a larger one is achieved by
+setting the field ``bytesperline`` at struct
+:ref:`v4l2_pix_format <v4l2-pix-format>`.
+Introducing an image offsets could be done by modifying field ``m_userptr``
+at struct
+:ref:`v4l2_buffer <v4l2-buffer>` before calling
+:ref:`VIDIOC_QBUF`. Those operations should be avoided because they are not
+portable (endianness), and do not work for macroblock and Bayer formats
+and mmap buffers. The selection API deals with configuration of buffer
+cropping/composing in a clear, intuitive and portable way. Next, with
+the selection API the concepts of the padded target and constraints
+flags are introduced. Finally, struct :ref:`v4l2_crop <v4l2-crop>`
+and struct :ref:`v4l2_cropcap <v4l2-cropcap>` have no reserved
+fields. Therefore there is no way to extend their functionality. The new
+struct :ref:`v4l2_selection <v4l2-selection>` provides a lot of place
+for future extensions. Driver developers are encouraged to implement
+only selection API. The former cropping API would be simulated using the
+new one.
diff --git a/Documentation/media/uapi/v4l/selection-api-006.rst b/Documentation/media/uapi/v4l/selection-api-006.rst
new file mode 100644
index 000000000000..b2ac12f2e3d4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection-api-006.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+********
+Examples
+********
+
+(A video capture device is assumed; change
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
+``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)
+
+
+.. code-block:: c
+ :caption: Example 1.15. Resetting the cropping parameters
+
+ struct v4l2_selection sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
+ .target = V4L2_SEL_TGT_CROP_DEFAULT,
+ };
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+ sel.target = V4L2_SEL_TGT_CROP;
+ ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+
+Setting a composing area on output of size of *at most* half of limit
+placed at a center of a display.
+
+
+.. code-block:: c
+ :caption: Example 1.16. Simple downscaling
+
+ struct v4l2_selection sel = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
+ };
+ struct v4l2_rect r;
+
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+ /* setting smaller compose rectangle */
+ r.width = sel.r.width / 2;
+ r.height = sel.r.height / 2;
+ r.left = sel.r.width / 4;
+ r.top = sel.r.height / 4;
+ sel.r = r;
+ sel.target = V4L2_SEL_TGT_COMPOSE;
+ sel.flags = V4L2_SEL_FLAG_LE;
+ ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
+ if (ret)
+ exit(-1);
+
+A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
+for other devices
+
+
+.. code-block:: c
+ :caption: Example 1.17. Querying for scaling factors
+
+ struct v4l2_selection compose = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_COMPOSE,
+ };
+ struct v4l2_selection crop = {
+ .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
+ .target = V4L2_SEL_TGT_CROP,
+ };
+ double hscale, vscale;
+
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &compose);
+ if (ret)
+ exit(-1);
+ ret = ioctl(fd, VIDIOC_G_SELECTION, &crop);
+ if (ret)
+ exit(-1);
+
+ /* computing scaling factors */
+ hscale = (double)compose.r.width / crop.r.width;
+ vscale = (double)compose.r.height / crop.r.height;
diff --git a/Documentation/media/uapi/v4l/selection-api.rst b/Documentation/media/uapi/v4l/selection-api.rst
new file mode 100644
index 000000000000..81ea52d785b9
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection-api.rst
@@ -0,0 +1,16 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _selection-api:
+
+API for cropping, composing and scaling
+=======================================
+
+
+.. toctree::
+ :maxdepth: 1
+
+ selection-api-002
+ selection-api-003
+ selection-api-004
+ selection-api-005
+ selection-api-006
diff --git a/Documentation/media/uapi/v4l/selections-common.rst b/Documentation/media/uapi/v4l/selections-common.rst
new file mode 100644
index 000000000000..69dbce4e6e47
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selections-common.rst
@@ -0,0 +1,23 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selections-common:
+
+Common selection definitions
+============================
+
+While the :ref:`V4L2 selection API <selection-api>` and
+:ref:`V4L2 subdev selection APIs <v4l2-subdev-selections>` are very
+similar, there's one fundamental difference between the two. On
+sub-device API, the selection rectangle refers to the media bus format,
+and is bound to a sub-device's pad. On the V4L2 interface the selection
+rectangles refer to the in-memory pixel format.
+
+This section defines the common definitions of the selection interfaces
+on the two APIs.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ v4l2-selection-targets
+ v4l2-selection-flags
diff --git a/Documentation/media/uapi/v4l/standard.rst b/Documentation/media/uapi/v4l/standard.rst
new file mode 100644
index 000000000000..538588eef317
--- /dev/null
+++ b/Documentation/media/uapi/v4l/standard.rst
@@ -0,0 +1,179 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _standard:
+
+***************
+Video Standards
+***************
+
+Video devices typically support one or more different video standards or
+variations of standards. Each video input and output may support another
+set of standards. This set is reported by the ``std`` field of struct
+:ref:`v4l2_input <v4l2-input>` and struct
+:ref:`v4l2_output <v4l2-output>` returned by the
+:ref:`VIDIOC_ENUMINPUT` and
+:ref:`VIDIOC_ENUMOUTPUT` ioctls, respectively.
+
+V4L2 defines one bit for each analog video standard currently in use
+worldwide, and sets aside bits for driver defined standards, e. g.
+hybrid standards to watch NTSC video tapes on PAL TVs and vice versa.
+Applications can use the predefined bits to select a particular
+standard, although presenting the user a menu of supported standards is
+preferred. To enumerate and query the attributes of the supported
+standards applications use the :ref:`VIDIOC_ENUMSTD`
+ioctl.
+
+Many of the defined standards are actually just variations of a few
+major standards. The hardware may in fact not distinguish between them,
+or do so internal and switch automatically. Therefore enumerated
+standards also contain sets of one or more standard bits.
+
+Assume a hypothetic tuner capable of demodulating B/PAL, G/PAL and I/PAL
+signals. The first enumerated standard is a set of B and G/PAL, switched
+automatically depending on the selected radio frequency in UHF or VHF
+band. Enumeration gives a "PAL-B/G" or "PAL-I" choice. Similar a
+Composite input may collapse standards, enumerating "PAL-B/G/H/I",
+"NTSC-M" and "SECAM-D/K". [1]_
+
+To query and select the standard used by the current video input or
+output applications call the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and
+:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctl, respectively. The
+*received* standard can be sensed with the
+:ref:`VIDIOC_QUERYSTD` ioctl. Note that the
+parameter of all these ioctls is a pointer to a
+:ref:`v4l2_std_id <v4l2-std-id>` type (a standard set), *not* an
+index into the standard enumeration. Drivers must implement all video
+standard ioctls when the device has one or more video inputs or outputs.
+
+Special rules apply to devices such as USB cameras where the notion of
+video standards makes little sense. More generally for any capture or
+output device which is:
+
+- incapable of capturing fields or frames at the nominal rate of the
+ video standard, or
+
+- that does not support the video standard formats at all.
+
+Here the driver shall set the ``std`` field of struct
+:ref:`v4l2_input <v4l2-input>` and struct
+:ref:`v4l2_output <v4l2-output>` to zero and the :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`,
+:ref:`VIDIOC_S_STD <VIDIOC_G_STD>`, :ref:`VIDIOC_QUERYSTD` and :ref:`VIDIOC_ENUMSTD` ioctls
+shall return the ``ENOTTY`` error code or the ``EINVAL`` error code.
+
+Applications can make use of the :ref:`input-capabilities` and
+:ref:`output-capabilities` flags to determine whether the video
+standard ioctls can be used with the given input or output.
+
+
+.. code-block:: c
+ :caption: Example 1.5. Information about the current video standard
+
+ v4l2_std_id std_id;
+ struct v4l2_standard standard;
+
+ if (-1 == ioctl(fd, VIDIOC_G_STD, &std_id)) {
+ /* Note when VIDIOC_ENUMSTD always returns ENOTTY this
+ is no video device or it falls under the USB exception,
+ and VIDIOC_G_STD returning ENOTTY is no error. */
+
+ perror("VIDIOC_G_STD");
+ exit(EXIT_FAILURE);
+ }
+
+ memset(&standard, 0, sizeof(standard));
+ standard.index = 0;
+
+ while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
+ if (standard.id & std_id) {
+ printf("Current video standard: %s\\n", standard.name);
+ exit(EXIT_SUCCESS);
+ }
+
+ standard.index++;
+ }
+
+ /* EINVAL indicates the end of the enumeration, which cannot be
+ empty unless this device falls under the USB exception. */
+
+ if (errno == EINVAL || standard.index == 0) {
+ perror("VIDIOC_ENUMSTD");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.6. Listing the video standards supported by the current input
+
+ struct v4l2_input input;
+ struct v4l2_standard standard;
+
+ memset(&input, 0, sizeof(input));
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUM_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input %s supports:\\n", input.name);
+
+ memset(&standard, 0, sizeof(standard));
+ standard.index = 0;
+
+ while (0 == ioctl(fd, VIDIOC_ENUMSTD, &standard)) {
+ if (standard.id & input.std)
+ printf("%s\\n", standard.name);
+
+ standard.index++;
+ }
+
+ /* EINVAL indicates the end of the enumeration, which cannot be
+ empty unless this device falls under the USB exception. */
+
+ if (errno != EINVAL || standard.index == 0) {
+ perror("VIDIOC_ENUMSTD");
+ exit(EXIT_FAILURE);
+ }
+
+
+.. code-block:: c
+ :caption: Example 1.7. Selecting a new video standard
+
+ struct v4l2_input input;
+ v4l2_std_id std_id;
+
+ memset(&input, 0, sizeof(input));
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &input.index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUM_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ if (0 == (input.std & V4L2_STD_PAL_BG)) {
+ fprintf(stderr, "Oops. B/G PAL is not supported.\\n");
+ exit(EXIT_FAILURE);
+ }
+
+ /* Note this is also supposed to work when only B
+ or G/PAL is supported. */
+
+ std_id = V4L2_STD_PAL_BG;
+
+ if (-1 == ioctl(fd, VIDIOC_S_STD, &std_id)) {
+ perror("VIDIOC_S_STD");
+ exit(EXIT_FAILURE);
+ }
+
+.. [1]
+ Some users are already confused by technical terms PAL, NTSC and
+ SECAM. There is no point asking them to distinguish between B, G, D,
+ or K when the software or hardware can do that automatically.
diff --git a/Documentation/media/uapi/v4l/streaming-par.rst b/Documentation/media/uapi/v4l/streaming-par.rst
new file mode 100644
index 000000000000..b07b0f0b35d4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/streaming-par.rst
@@ -0,0 +1,33 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _streaming-par:
+
+********************
+Streaming Parameters
+********************
+
+Streaming parameters are intended to optimize the video capture process
+as well as I/O. Presently applications can request a high quality
+capture mode with the :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl.
+
+The current video standard determines a nominal number of frames per
+second. If less than this number of frames is to be captured or output,
+applications can request frame skipping or duplicating on the driver
+side. This is especially useful when using the
+:ref:`read() <func-read>` or :ref:`write() <func-write>`, which are
+not augmented by timestamps or sequence counters, and to avoid
+unnecessary data copying.
+
+Finally these ioctls can be used to determine the number of buffers used
+internally by a driver in read/write mode. For implications see the
+section discussing the :ref:`read() <func-read>` function.
+
+To get and set the streaming parameters applications call the
+:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and
+:ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take
+a pointer to a struct :ref:`v4l2_streamparm <v4l2-streamparm>`, which
+contains a union holding separate parameters for input and output
+devices.
+
+These ioctls are optional, drivers need not implement them. If so, they
+return the ``EINVAL`` error code.
diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
new file mode 100644
index 000000000000..6dbb27b09c34
--- /dev/null
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -0,0 +1,11688 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-mbus-format:
+
+Media Bus Formats
+=================
+
+
+.. _v4l2-mbus-framefmt:
+
+.. flat-table:: struct v4l2_mbus_framefmt
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Image width, in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Image height, in pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - Format code, from enum
+ :ref:`v4l2_mbus_pixelcode <v4l2-mbus-pixelcode>`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``field``
+
+ - Field order, from enum :ref:`v4l2_field <v4l2-field>`. See
+ :ref:`field-order` for details.
+
+ - .. row 5
+
+ - __u32
+
+ - ``colorspace``
+
+ - Image colorspace, from enum
+ :ref:`v4l2_colorspace <v4l2-colorspace>`. See
+ :ref:`colorspaces` for details.
+
+ - .. row 6
+
+ - enum :ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>`
+
+ - ``ycbcr_enc``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 7
+
+ - enum :ref:`v4l2_quantization <v4l2-quantization>`
+
+ - ``quantization``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 8
+
+ - enum :ref:`v4l2_xfer_func <v4l2-xfer-func>`
+
+ - ``xfer_func``
+
+ - This information supplements the ``colorspace`` and must be set by
+ the driver for capture streams and by the application for output
+ streams, see :ref:`colorspaces`.
+
+ - .. row 9
+
+ - __u16
+
+ - ``reserved``\ [11]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-mbus-pixelcode:
+
+Media Bus Pixel Codes
+---------------------
+
+The media bus pixel codes describe image formats as flowing over
+physical busses (both between separate physical components and inside
+SoC devices). This should not be confused with the V4L2 pixel formats
+that describe, using four character codes, image formats as stored in
+memory.
+
+While there is a relationship between image formats on busses and image
+formats in memory (a raw Bayer image won't be magically converted to
+JPEG just by storing it to memory), there is no one-to-one
+correspondance between them.
+
+
+Packed RGB Formats
+^^^^^^^^^^^^^^^^^^
+
+Those formats transfer pixel data as red, green and blue components. The
+format code is made of the following information.
+
+- The red, green and blue components order code, as encoded in a pixel
+ sample. Possible values are RGB and BGR.
+
+- The number of bits per component, for each component. The values can
+ be different for all components. Common values are 555 and 565.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO). A "C" prefix is used for
+ component-wise padding in the most high order bits (CPADHI) or low
+ order bits (CPADLO) of each separate component.
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+For instance, a format where pixels are encoded as 5-bits red, 5-bits
+green and 5-bit blue values padded on the high bit, transferred as 2
+8-bit samples per pixel with the most significant bits (padding, red and
+half of the green value) transferred first will be named
+``MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE``.
+
+The following tables list existing packed RGB formats.
+
+
+.. _v4l2-mbus-pixelcode-rgb:
+
+.. flat-table:: RGB formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 20
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-RGB444-1X12:
+
+ - MEDIA_BUS_FMT_RGB444_1X12
+
+ - 0x1016
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE:
+
+ - MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE
+
+ - 0x1001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. row 5
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE:
+
+ - MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE
+
+ - 0x1002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 7
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE:
+
+ - MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE
+
+ - 0x1003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 9
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE:
+
+ - MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE
+
+ - 0x1004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _MEDIA-BUS-FMT-RGB565-1X16:
+
+ - MEDIA_BUS_FMT_RGB565_1X16
+
+ - 0x1017
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-BGR565-2X8-BE:
+
+ - MEDIA_BUS_FMT_BGR565_2X8_BE
+
+ - 0x1005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 14
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-BGR565-2X8-LE:
+
+ - MEDIA_BUS_FMT_BGR565_2X8_LE
+
+ - 0x1006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _MEDIA-BUS-FMT-RGB565-2X8-BE:
+
+ - MEDIA_BUS_FMT_RGB565_2X8_BE
+
+ - 0x1007
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. row 18
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB565-2X8-LE:
+
+ - MEDIA_BUS_FMT_RGB565_2X8_LE
+
+ - 0x1008
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - .. _MEDIA-BUS-FMT-RGB666-1X18:
+
+ - MEDIA_BUS_FMT_RGB666_1X18
+
+ - 0x1009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RBG888-1X24:
+
+ - MEDIA_BUS_FMT_RBG888_1X24
+
+ - 0x100e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB666-1X24_CPADHI:
+
+ - MEDIA_BUS_FMT_RGB666_1X24_CPADHI
+
+ - 0x1015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-BGR888-1X24:
+
+ - MEDIA_BUS_FMT_BGR888_1X24
+
+ - 0x1013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-GBR888-1X24:
+
+ - MEDIA_BUS_FMT_GBR888_1X24
+
+ - 0x1014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X24:
+
+ - MEDIA_BUS_FMT_RGB888_1X24
+
+ - 0x100a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-2X12-BE:
+
+ - MEDIA_BUS_FMT_RGB888_2X12_BE
+
+ - 0x100b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - .. row 28
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-2X12-LE:
+
+ - MEDIA_BUS_FMT_RGB888_2X12_LE
+
+ - 0x100c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 30
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - .. _MEDIA-BUS-FMT-ARGB888-1X32:
+
+ - MEDIA_BUS_FMT_ARGB888_1X32
+
+ - 0x100d
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X32-PADHI:
+
+ - MEDIA_BUS_FMT_RGB888_1X32_PADHI
+
+ - 0x100f
+
+ -
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+
+On LVDS buses, usually each sample is transferred serialized in seven
+time slots per pixel clock, on three (18-bit) or four (24-bit)
+differential data pairs at the same time. The remaining bits are used
+for control signals as defined by SPWG/PSWG/VESA or JEIDA standards. The
+24-bit RGB format serialized in seven time slots on four lanes using
+JEIDA defined bit mapping will be named
+``MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA``, for example.
+
+
+.. _v4l2-mbus-pixelcode-rgb-lvds:
+
+.. flat-table:: LVDS RGB formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ -
+ - :cspan:`3` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Timeslot
+
+ - Lane
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-RGB666-1X7X3-SPWG:
+
+ - MEDIA_BUS_FMT_RGB666_1X7X3_SPWG
+
+ - 0x1010
+
+ - 0
+
+ -
+ - -
+
+ - d
+
+ - b\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. row 4
+
+ -
+ -
+ - 1
+
+ -
+ - -
+
+ - d
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - .. row 5
+
+ -
+ -
+ - 2
+
+ -
+ - -
+
+ - d
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 6
+
+ -
+ -
+ - 3
+
+ -
+ - -
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 7
+
+ -
+ -
+ - 4
+
+ -
+ - -
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - .. row 8
+
+ -
+ -
+ - 5
+
+ -
+ - -
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - .. row 9
+
+ -
+ -
+ - 6
+
+ -
+ - -
+
+ - b\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X7X4-SPWG:
+
+ - MEDIA_BUS_FMT_RGB888_1X7X4_SPWG
+
+ - 0x1011
+
+ - 0
+
+ -
+ - d
+
+ - d
+
+ - b\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ - 1
+
+ -
+ - b\ :sub:`7`
+
+ - d
+
+ - b\ :sub:`0`
+
+ - r\ :sub:`5`
+
+ - .. row 12
+
+ -
+ -
+ - 2
+
+ -
+ - b\ :sub:`6`
+
+ - d
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 13
+
+ -
+ -
+ - 3
+
+ -
+ - g\ :sub:`7`
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 14
+
+ -
+ -
+ - 4
+
+ -
+ - g\ :sub:`6`
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - .. row 15
+
+ -
+ -
+ - 5
+
+ -
+ - r\ :sub:`7`
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - .. row 16
+
+ -
+ -
+ - 6
+
+ -
+ - r\ :sub:`6`
+
+ - b\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-RGB888-1X7X4-JEIDA:
+
+ - MEDIA_BUS_FMT_RGB888_1X7X4_JEIDA
+
+ - 0x1012
+
+ - 0
+
+ -
+ - d
+
+ - d
+
+ - b\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - .. row 18
+
+ -
+ -
+ - 1
+
+ -
+ - b\ :sub:`1`
+
+ - d
+
+ - b\ :sub:`2`
+
+ - r\ :sub:`7`
+
+ - .. row 19
+
+ -
+ -
+ - 2
+
+ -
+ - b\ :sub:`0`
+
+ - d
+
+ - g\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - .. row 20
+
+ -
+ -
+ - 3
+
+ -
+ - g\ :sub:`1`
+
+ - b\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - .. row 21
+
+ -
+ -
+ - 4
+
+ -
+ - g\ :sub:`0`
+
+ - b\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - .. row 22
+
+ -
+ -
+ - 5
+
+ -
+ - r\ :sub:`1`
+
+ - b\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - .. row 23
+
+ -
+ -
+ - 6
+
+ -
+ - r\ :sub:`0`
+
+ - b\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - r\ :sub:`2`
+
+
+
+Bayer Formats
+^^^^^^^^^^^^^
+
+Those formats transfer pixel data as red, green and blue components. The
+format code is made of the following information.
+
+- The red, green and blue components order code, as encoded in a pixel
+ sample. The possible values are shown in :ref:`bayer-patterns`.
+
+- The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and
+ 12.
+
+- The compression (optional). If the pixel components are ALAW- or
+ DPCM-compressed, a mention of the compression scheme and the number
+ of bits per compressed pixel component.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1 and 2.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+For instance, a format with uncompressed 10-bit Bayer components
+arranged in a red, green, green, blue pattern transferred as 2 8-bit
+samples per pixel with the least significant bits transferred first will
+be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
+
+
+.. _bayer-patterns:
+
+.. figure:: subdev-formats_files/bayer.*
+ :alt: bayer.png
+ :align: center
+
+ **Figure 4.8 Bayer Patterns**
+
+
+
+The following table lists existing packed Bayer formats. The data
+organization is given as an example for the first pixel only.
+
+
+.. _v4l2-mbus-pixelcode-bayer:
+
+.. flat-table:: Bayer Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`11` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-SBGGR8-1X8:
+
+ - MEDIA_BUS_FMT_SBGGR8_1X8
+
+ - 0x3001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG8-1X8:
+
+ - MEDIA_BUS_FMT_SGBRG8_1X8
+
+ - 0x3013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG8-1X8:
+
+ - MEDIA_BUS_FMT_SGRBG8_1X8
+
+ - 0x3002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB8-1X8:
+
+ - MEDIA_BUS_FMT_SRGGB8_1X8
+
+ - 0x3014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8
+
+ - 0x3015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8
+
+ - 0x3016
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8
+
+ - 0x3017
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8:
+
+ - MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8
+
+ - 0x3018
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8
+
+ - 0x300b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8
+
+ - 0x300c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8
+
+ - 0x3009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8:
+
+ - MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8
+
+ - 0x300d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE
+
+ - 0x3003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE
+
+ - 0x3004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. row 18
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE
+
+ - 0x3005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE:
+
+ - MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE
+
+ - 0x3006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - .. row 22
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - .. _MEDIA-BUS-FMT-SBGGR10-1X10:
+
+ - MEDIA_BUS_FMT_SBGGR10_1X10
+
+ - 0x3007
+
+ -
+ - -
+
+ - -
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG10-1X10:
+
+ - MEDIA_BUS_FMT_SGBRG10_1X10
+
+ - 0x300e
+
+ -
+ - -
+
+ - -
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG10-1X10:
+
+ - MEDIA_BUS_FMT_SGRBG10_1X10
+
+ - 0x300a
+
+ -
+ - -
+
+ - -
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB10-1X10:
+
+ - MEDIA_BUS_FMT_SRGGB10_1X10
+
+ - 0x300f
+
+ -
+ - -
+
+ - -
+
+ - r\ :sub:`9`
+
+ - r\ :sub:`8`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SBGGR12-1X12:
+
+ - MEDIA_BUS_FMT_SBGGR12_1X12
+
+ - 0x3008
+
+ -
+ - b\ :sub:`11`
+
+ - b\ :sub:`10`
+
+ - b\ :sub:`9`
+
+ - b\ :sub:`8`
+
+ - b\ :sub:`7`
+
+ - b\ :sub:`6`
+
+ - b\ :sub:`5`
+
+ - b\ :sub:`4`
+
+ - b\ :sub:`3`
+
+ - b\ :sub:`2`
+
+ - b\ :sub:`1`
+
+ - b\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGBRG12-1X12:
+
+ - MEDIA_BUS_FMT_SGBRG12_1X12
+
+ - 0x3010
+
+ -
+ - g\ :sub:`11`
+
+ - g\ :sub:`10`
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SGRBG12-1X12:
+
+ - MEDIA_BUS_FMT_SGRBG12_1X12
+
+ - 0x3011
+
+ -
+ - g\ :sub:`11`
+
+ - g\ :sub:`10`
+
+ - g\ :sub:`9`
+
+ - g\ :sub:`8`
+
+ - g\ :sub:`7`
+
+ - g\ :sub:`6`
+
+ - g\ :sub:`5`
+
+ - g\ :sub:`4`
+
+ - g\ :sub:`3`
+
+ - g\ :sub:`2`
+
+ - g\ :sub:`1`
+
+ - g\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-SRGGB12-1X12:
+
+ - MEDIA_BUS_FMT_SRGGB12_1X12
+
+ - 0x3012
+
+ -
+ - r\ :sub:`11`
+
+ - r\ :sub:`10`
+
+ - r\ :sub:`9`
+
+ - r\ :sub:`8`
+
+ - r\ :sub:`7`
+
+ - r\ :sub:`6`
+
+ - r\ :sub:`5`
+
+ - r\ :sub:`4`
+
+ - r\ :sub:`3`
+
+ - r\ :sub:`2`
+
+ - r\ :sub:`1`
+
+ - r\ :sub:`0`
+
+
+
+Packed YUV Formats
+^^^^^^^^^^^^^^^^^^
+
+Those data formats transfer pixel data as (possibly downsampled) Y, U
+and V components. Some formats include dummy bits in some of their
+samples and are collectively referred to as "YDYC" (Y-Dummy-Y-Chroma)
+formats. One cannot rely on the values of these dummy bits as those are
+undefined.
+
+The format code is made of the following information.
+
+- The Y, U and V components order code, as transferred on the bus.
+ Possible values are YUYV, UYVY, YVYU and VYUY for formats with no
+ dummy bit, and YDYUYDYV, YDYVYDYU, YUYDYVYD and YVYDYUYD for YDYC
+ formats.
+
+- The number of bits per pixel component. All components are
+ transferred on the same number of bits. Common values are 8, 10 and
+ 12.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. Common values are
+ 1, 1.5 (encoded as 1_5) and 2.
+
+- The bus width. When the bus width is larger than the number of bits
+ per pixel component, several components are packed in a single bus
+ sample. The components are ordered as specified by the order code,
+ with components on the left of the code transferred in the high order
+ bits. Common values are 8 and 16.
+
+For instance, a format where pixels are encoded as 8-bit YUV values
+downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in
+the U, Y, V, Y order will be named ``MEDIA_BUS_FMT_UYVY8_2X8``.
+
+:ref:`v4l2-mbus-pixelcode-yuv8` lists existing packed YUV formats and
+describes the organization of each pixel data in each sample. When a
+format pattern is split across multiple samples each of the samples in
+the pattern is described.
+
+The role of each bit transferred over the bus is identified by one of
+the following codes.
+
+- y\ :sub:`x` for luma component bit number x
+
+- u\ :sub:`x` for blue chroma component bit number x
+
+- v\ :sub:`x` for red chroma component bit number x
+
+- a\ :sub:`x` for alpha component bit number x
+
+- - for non-available bits (for positions higher than the bus width)
+
+- d for dummy bits
+
+
+.. _v4l2-mbus-pixelcode-yuv8:
+
+.. flat-table:: YUV Formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 10
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-Y8-1X8:
+
+ - MEDIA_BUS_FMT_Y8_1X8
+
+ - 0x2001
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UV8-1X8:
+
+ - MEDIA_BUS_FMT_UV8_1X8
+
+ - 0x2015
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 5
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY8-1_5X8:
+
+ - MEDIA_BUS_FMT_UYVY8_1_5X8
+
+ - 0x2002
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 7
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 8
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 9
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 10
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 11
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY8-1_5X8:
+
+ - MEDIA_BUS_FMT_VYUY8_1_5X8
+
+ - 0x2003
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 13
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 14
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 15
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 16
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 17
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV8-1_5X8:
+
+ - MEDIA_BUS_FMT_YUYV8_1_5X8
+
+ - 0x2004
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 19
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 20
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 21
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 22
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 23
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU8-1_5X8:
+
+ - MEDIA_BUS_FMT_YVYU8_1_5X8
+
+ - 0x2005
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 25
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 26
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 27
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 28
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 29
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY8-2X8:
+
+ - MEDIA_BUS_FMT_UYVY8_2X8
+
+ - 0x2006
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 31
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 32
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 33
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY8-2X8:
+
+ - MEDIA_BUS_FMT_VYUY8_2X8
+
+ - 0x2007
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 35
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 36
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 37
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV8-2X8:
+
+ - MEDIA_BUS_FMT_YUYV8_2X8
+
+ - 0x2008
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 39
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 40
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 41
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU8-2X8:
+
+ - MEDIA_BUS_FMT_YVYU8_2X8
+
+ - 0x2009
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 43
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 44
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 45
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-Y10-1X10:
+
+ - MEDIA_BUS_FMT_Y10_1X10
+
+ - 0x200a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY10-2X10:
+
+ - MEDIA_BUS_FMT_UYVY10_2X10
+
+ - 0x2018
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 48
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 49
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 50
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY10-2X10:
+
+ - MEDIA_BUS_FMT_VYUY10_2X10
+
+ - 0x2019
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 52
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 53
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 54
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV10-2X10:
+
+ - MEDIA_BUS_FMT_YUYV10_2X10
+
+ - 0x200b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 56
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 57
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 58
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU10-2X10:
+
+ - MEDIA_BUS_FMT_YVYU10_2X10
+
+ - 0x200c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 60
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 61
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 62
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-Y12-1X12:
+
+ - MEDIA_BUS_FMT_Y12_1X12
+
+ - 0x2013
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY12-2X12:
+
+ - MEDIA_BUS_FMT_UYVY12_2X12
+
+ - 0x201c
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 65
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 66
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 67
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY12-2X12:
+
+ - MEDIA_BUS_FMT_VYUY12_2X12
+
+ - 0x201d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 69
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 70
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 71
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV12-2X12:
+
+ - MEDIA_BUS_FMT_YUYV12_2X12
+
+ - 0x201e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 73
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 74
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 75
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU12-2X12:
+
+ - MEDIA_BUS_FMT_YVYU12_2X12
+
+ - 0x201f
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 77
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 78
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 79
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY8-1X16:
+
+ - MEDIA_BUS_FMT_UYVY8_1X16
+
+ - 0x200f
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 81
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY8-1X16:
+
+ - MEDIA_BUS_FMT_VYUY8_1X16
+
+ - 0x2010
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 83
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV8-1X16:
+
+ - MEDIA_BUS_FMT_YUYV8_1X16
+
+ - 0x2011
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 85
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU8-1X16:
+
+ - MEDIA_BUS_FMT_YVYU8_1X16
+
+ - 0x2012
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 87
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YDYUYDYV8-1X16:
+
+ - MEDIA_BUS_FMT_YDYUYDYV8_1X16
+
+ - 0x2014
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - .. row 89
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 90
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - d
+
+ - .. row 91
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY10-1X20:
+
+ - MEDIA_BUS_FMT_UYVY10_1X20
+
+ - 0x201a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 93
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY10-1X20:
+
+ - MEDIA_BUS_FMT_VYUY10_1X20
+
+ - 0x201b
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 95
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV10-1X20:
+
+ - MEDIA_BUS_FMT_YUYV10_1X20
+
+ - 0x200d
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 97
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU10-1X20:
+
+ - MEDIA_BUS_FMT_YVYU10_1X20
+
+ - 0x200e
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 99
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VUY8-1X24:
+
+ - MEDIA_BUS_FMT_VUY8_1X24
+
+ - 0x201a
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUV8-1X24:
+
+ - MEDIA_BUS_FMT_YUV8_1X24
+
+ - 0x2025
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-UYVY12-1X24:
+
+ - MEDIA_BUS_FMT_UYVY12_1X24
+
+ - 0x2020
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 103
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-VYUY12-1X24:
+
+ - MEDIA_BUS_FMT_VYUY12_1X24
+
+ - 0x2021
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. row 105
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUYV12-1X24:
+
+ - MEDIA_BUS_FMT_YUYV12_1X24
+
+ - 0x2022
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. row 107
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YVYU12-1X24:
+
+ - MEDIA_BUS_FMT_YVYU12_1X24
+
+ - 0x2023
+
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - v\ :sub:`11`
+
+ - v\ :sub:`10`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. row 109
+
+ -
+ -
+ -
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - -
+
+ - y\ :sub:`11`
+
+ - y\ :sub:`10`
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`11`
+
+ - u\ :sub:`10`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-YUV10-1X30:
+
+ - MEDIA_BUS_FMT_YUV10_1X30
+
+ - 0x2016
+
+ -
+ - -
+
+ - -
+
+ - y\ :sub:`9`
+
+ - y\ :sub:`8`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`9`
+
+ - u\ :sub:`8`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`9`
+
+ - v\ :sub:`8`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+ - .. _MEDIA-BUS-FMT-AYUV8-1X32:
+
+ - MEDIA_BUS_FMT_AYUV8_1X32
+
+ - 0x2017
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - y\ :sub:`7`
+
+ - y\ :sub:`6`
+
+ - y\ :sub:`5`
+
+ - y\ :sub:`4`
+
+ - y\ :sub:`3`
+
+ - y\ :sub:`2`
+
+ - y\ :sub:`1`
+
+ - y\ :sub:`0`
+
+ - u\ :sub:`7`
+
+ - u\ :sub:`6`
+
+ - u\ :sub:`5`
+
+ - u\ :sub:`4`
+
+ - u\ :sub:`3`
+
+ - u\ :sub:`2`
+
+ - u\ :sub:`1`
+
+ - u\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+
+
+HSV/HSL Formats
+^^^^^^^^^^^^^^^
+
+Those formats transfer pixel data as RGB values in a
+cylindrical-coordinate system using Hue-Saturation-Value or
+Hue-Saturation-Lightness components. The format code is made of the
+following information.
+
+- The hue, saturation, value or lightness and optional alpha components
+ order code, as encoded in a pixel sample. The only currently
+ supported value is AHSV.
+
+- The number of bits per component, for each component. The values can
+ be different for all components. The only currently supported value
+ is 8888.
+
+- The number of bus samples per pixel. Pixels that are wider than the
+ bus width must be transferred in multiple samples. The only currently
+ supported value is 1.
+
+- The bus width.
+
+- For formats where the total number of bits per pixel is smaller than
+ the number of bus samples per pixel times the bus width, a padding
+ value stating if the bytes are padded in their most high order bits
+ (PADHI) or low order bits (PADLO).
+
+- For formats where the number of bus samples per pixel is larger than
+ 1, an endianness value stating if the pixel is transferred MSB first
+ (BE) or LSB first (LE).
+
+The following table lists existing HSV/HSL formats.
+
+
+.. _v4l2-mbus-pixelcode-hsv:
+
+.. flat-table:: HSV/HSL formats
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ -
+ - :cspan:`31` Data organization
+
+ - .. row 2
+
+ -
+ -
+ - Bit
+
+ - 31
+
+ - 30
+
+ - 29
+
+ - 28
+
+ - 27
+
+ - 26
+
+ - 25
+
+ - 24
+
+ - 23
+
+ - 22
+
+ - 21
+
+ - 20
+
+ - 19
+
+ - 18
+
+ - 17
+
+ - 16
+
+ - 15
+
+ - 14
+
+ - 13
+
+ - 12
+
+ - 11
+
+ - 10
+
+ - 9
+
+ - 8
+
+ - 7
+
+ - 6
+
+ - 5
+
+ - 4
+
+ - 3
+
+ - 2
+
+ - 1
+
+ - 0
+
+ - .. _MEDIA-BUS-FMT-AHSV8888-1X32:
+
+ - MEDIA_BUS_FMT_AHSV8888_1X32
+
+ - 0x6001
+
+ -
+ - a\ :sub:`7`
+
+ - a\ :sub:`6`
+
+ - a\ :sub:`5`
+
+ - a\ :sub:`4`
+
+ - a\ :sub:`3`
+
+ - a\ :sub:`2`
+
+ - a\ :sub:`1`
+
+ - a\ :sub:`0`
+
+ - h\ :sub:`7`
+
+ - h\ :sub:`6`
+
+ - h\ :sub:`5`
+
+ - h\ :sub:`4`
+
+ - h\ :sub:`3`
+
+ - h\ :sub:`2`
+
+ - h\ :sub:`1`
+
+ - h\ :sub:`0`
+
+ - s\ :sub:`7`
+
+ - s\ :sub:`6`
+
+ - s\ :sub:`5`
+
+ - s\ :sub:`4`
+
+ - s\ :sub:`3`
+
+ - s\ :sub:`2`
+
+ - s\ :sub:`1`
+
+ - s\ :sub:`0`
+
+ - v\ :sub:`7`
+
+ - v\ :sub:`6`
+
+ - v\ :sub:`5`
+
+ - v\ :sub:`4`
+
+ - v\ :sub:`3`
+
+ - v\ :sub:`2`
+
+ - v\ :sub:`1`
+
+ - v\ :sub:`0`
+
+
+
+JPEG Compressed Formats
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Those data formats consist of an ordered sequence of 8-bit bytes
+obtained from JPEG compression process. Additionally to the ``_JPEG``
+postfix the format code is made of the following information.
+
+- The number of bus samples per entropy encoded byte.
+
+- The bus width.
+
+For instance, for a JPEG baseline process and an 8-bit bus width the
+format will be named ``MEDIA_BUS_FMT_JPEG_1X8``.
+
+The following table lists existing JPEG compressed formats.
+
+
+.. _v4l2-mbus-pixelcode-jpeg:
+
+.. flat-table:: JPEG Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Remarks
+
+ - .. _MEDIA-BUS-FMT-JPEG-1X8:
+
+ - MEDIA_BUS_FMT_JPEG_1X8
+
+ - 0x4001
+
+ - Besides of its usage for the parallel bus this format is
+ recommended for transmission of JPEG data over MIPI CSI bus using
+ the User Defined 8-bit Data types.
+
+
+
+.. _v4l2-mbus-vendor-spec-fmts:
+
+Vendor and Device Specific Formats
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section lists complex data formats that are either vendor or device
+specific.
+
+The following table lists the existing vendor and device specific
+formats.
+
+
+.. _v4l2-mbus-pixelcode-vendor-specific:
+
+.. flat-table:: Vendor and device specific formats
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Identifier
+
+ - Code
+
+ - Comments
+
+ - .. _MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8:
+
+ - MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8
+
+ - 0x5001
+
+ - Interleaved raw UYVY and JPEG image format with embedded meta-data
+ used by Samsung S3C73MX camera sensors.
diff --git a/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png b/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png
new file mode 100644
index 000000000000..9b15fb22e817
--- /dev/null
+++ b/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png
Binary files differ
diff --git a/Documentation/media/uapi/v4l/tuner.rst b/Documentation/media/uapi/v4l/tuner.rst
new file mode 100644
index 000000000000..23d0e00aefdd
--- /dev/null
+++ b/Documentation/media/uapi/v4l/tuner.rst
@@ -0,0 +1,82 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _tuner:
+
+*********************
+Tuners and Modulators
+*********************
+
+
+Tuners
+======
+
+Video input devices can have one or more tuners demodulating a RF
+signal. Each tuner is associated with one or more video inputs,
+depending on the number of RF connectors on the tuner. The ``type``
+field of the respective struct :ref:`v4l2_input <v4l2-input>`
+returned by the :ref:`VIDIOC_ENUMINPUT` ioctl is
+set to ``V4L2_INPUT_TYPE_TUNER`` and its ``tuner`` field contains the
+index number of the tuner.
+
+Radio input devices have exactly one tuner with index zero, no video
+inputs.
+
+To query and change tuner properties applications use the
+:ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>` and
+:ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>` ioctls, respectively. The
+struct :ref:`v4l2_tuner <v4l2-tuner>` returned by :ref:`VIDIOC_G_TUNER <VIDIOC_G_TUNER>`
+also contains signal status information applicable when the tuner of the
+current video or radio input is queried. Note that :ref:`VIDIOC_S_TUNER <VIDIOC_G_TUNER>`
+does not switch the current tuner, when there is more than one at all.
+The tuner is solely determined by the current video input. Drivers must
+support both ioctls and set the ``V4L2_CAP_TUNER`` flag in the struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl when the device has
+one or more tuners.
+
+
+Modulators
+==========
+
+Video output devices can have one or more modulators, uh, modulating a
+video signal for radiation or connection to the antenna input of a TV
+set or video recorder. Each modulator is associated with one or more
+video outputs, depending on the number of RF connectors on the
+modulator. The ``type`` field of the respective struct
+:ref:`v4l2_output <v4l2-output>` returned by the
+:ref:`VIDIOC_ENUMOUTPUT` ioctl is set to
+``V4L2_OUTPUT_TYPE_MODULATOR`` and its ``modulator`` field contains the
+index number of the modulator.
+
+Radio output devices have exactly one modulator with index zero, no
+video outputs.
+
+A video or radio device cannot support both a tuner and a modulator. Two
+separate device nodes will have to be used for such hardware, one that
+supports the tuner functionality and one that supports the modulator
+functionality. The reason is a limitation with the
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl where you
+cannot specify whether the frequency is for a tuner or a modulator.
+
+To query and change modulator properties applications use the
+:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` and
+:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Note that
+:ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` does not switch the current modulator, when there
+is more than one at all. The modulator is solely determined by the
+current video output. Drivers must support both ioctls and set the
+``V4L2_CAP_MODULATOR`` flag in the struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl when the device has
+one or more modulators.
+
+
+Radio Frequency
+===============
+
+To get and set the tuner or modulator radio frequency applications use
+the :ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` and
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl which both take
+a pointer to a struct :ref:`v4l2_frequency <v4l2-frequency>`. These
+ioctls are used for TV and radio devices alike. Drivers must support
+both ioctls when the tuner or modulator ioctls are supported, or when
+the device is a radio device.
diff --git a/Documentation/media/uapi/v4l/user-func.rst b/Documentation/media/uapi/v4l/user-func.rst
new file mode 100644
index 000000000000..3e0413b83a33
--- /dev/null
+++ b/Documentation/media/uapi/v4l/user-func.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _user-func:
+
+******************
+Function Reference
+******************
+
+
+.. toctree::
+ :maxdepth: 1
+
+ func-close
+ func-ioctl
+ vidioc-create-bufs
+ vidioc-cropcap
+ vidioc-dbg-g-chip-info
+ vidioc-dbg-g-register
+ vidioc-decoder-cmd
+ vidioc-dqevent
+ vidioc-dv-timings-cap
+ vidioc-encoder-cmd
+ vidioc-enumaudio
+ vidioc-enumaudioout
+ vidioc-enum-dv-timings
+ vidioc-enum-fmt
+ vidioc-enum-framesizes
+ vidioc-enum-frameintervals
+ vidioc-enum-freq-bands
+ vidioc-enuminput
+ vidioc-enumoutput
+ vidioc-enumstd
+ vidioc-expbuf
+ vidioc-g-audio
+ vidioc-g-audioout
+ vidioc-g-crop
+ vidioc-g-ctrl
+ vidioc-g-dv-timings
+ vidioc-g-edid
+ vidioc-g-enc-index
+ vidioc-g-ext-ctrls
+ vidioc-g-fbuf
+ vidioc-g-fmt
+ vidioc-g-frequency
+ vidioc-g-input
+ vidioc-g-jpegcomp
+ vidioc-g-modulator
+ vidioc-g-output
+ vidioc-g-parm
+ vidioc-g-priority
+ vidioc-g-selection
+ vidioc-g-sliced-vbi-cap
+ vidioc-g-std
+ vidioc-g-tuner
+ vidioc-log-status
+ vidioc-overlay
+ vidioc-prepare-buf
+ vidioc-qbuf
+ vidioc-querybuf
+ vidioc-querycap
+ vidioc-queryctrl
+ vidioc-query-dv-timings
+ vidioc-querystd
+ vidioc-reqbufs
+ vidioc-s-hw-freq-seek
+ vidioc-streamon
+ vidioc-subdev-enum-frame-interval
+ vidioc-subdev-enum-frame-size
+ vidioc-subdev-enum-mbus-code
+ vidioc-subdev-g-crop
+ vidioc-subdev-g-fmt
+ vidioc-subdev-g-frame-interval
+ vidioc-subdev-g-selection
+ vidioc-subscribe-event
+ func-mmap
+ func-munmap
+ func-open
+ func-poll
+ func-read
+ func-select
+ func-write
diff --git a/Documentation/media/uapi/v4l/userp.rst b/Documentation/media/uapi/v4l/userp.rst
new file mode 100644
index 000000000000..0ecf7a13a7af
--- /dev/null
+++ b/Documentation/media/uapi/v4l/userp.rst
@@ -0,0 +1,117 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _userp:
+
+*****************************
+Streaming I/O (User Pointers)
+*****************************
+
+Input and output devices support this I/O method when the
+``V4L2_CAP_STREAMING`` flag in the ``capabilities`` field of struct
+:ref:`v4l2_capability <v4l2-capability>` returned by the
+:ref:`VIDIOC_QUERYCAP` ioctl is set. If the
+particular user pointer method (not only memory mapping) is supported
+must be determined by calling the
+:ref:`VIDIOC_REQBUFS` ioctl.
+
+This I/O method combines advantages of the read/write and memory mapping
+methods. Buffers (planes) are allocated by the application itself, and
+can reside for example in virtual or shared memory. Only pointers to
+data are exchanged, these pointers and meta-information are passed in
+struct :ref:`v4l2_buffer <v4l2-buffer>` (or in struct
+:ref:`v4l2_plane <v4l2-plane>` in the multi-planar API case). The
+driver must be switched into user pointer I/O mode by calling the
+:ref:`VIDIOC_REQBUFS` with the desired buffer type.
+No buffers (planes) are allocated beforehand, consequently they are not
+indexed and cannot be queried like mapped buffers with the
+:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>` ioctl.
+
+
+.. code-block:: c
+ :caption: Example 3.3. Initiating streaming I/O with user pointers
+
+ struct v4l2_requestbuffers reqbuf;
+
+ memset (&reqbuf, 0, sizeof (reqbuf));
+ reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ reqbuf.memory = V4L2_MEMORY_USERPTR;
+
+ if (ioctl (fd, VIDIOC_REQBUFS, &reqbuf) == -1) {
+ if (errno == EINVAL)
+ printf ("Video capturing or user pointer streaming is not supported\\n");
+ else
+ perror ("VIDIOC_REQBUFS");
+
+ exit (EXIT_FAILURE);
+ }
+
+Buffer (plane) addresses and sizes are passed on the fly with the
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` ioctl. Although buffers are commonly
+cycled, applications can pass different addresses and sizes at each
+:ref:`VIDIOC_QBUF <VIDIOC_QBUF>` call. If required by the hardware the
+driver swaps memory pages within physical memory to create a continuous
+area of memory. This happens transparently to the application in the
+virtual memory subsystem of the kernel. When buffer pages have been
+swapped out to disk they are brought back and finally locked in physical
+memory for DMA. [1]_
+
+Filled or displayed buffers are dequeued with the
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. The driver can unlock the
+memory pages at any time between the completion of the DMA and this
+ioctl. The memory is also unlocked when
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` is called,
+:ref:`VIDIOC_REQBUFS`, or when the device is closed.
+Applications must take care not to free buffers without dequeuing. For
+once, the buffers remain locked until further, wasting physical memory.
+Second the driver will not be notified when the memory is returned to
+the application's free list and subsequently reused for other purposes,
+possibly completing the requested DMA and overwriting valuable data.
+
+For capturing applications it is customary to enqueue a number of empty
+buffers, to start capturing and enter the read loop. Here the
+application waits until a filled buffer can be dequeued, and re-enqueues
+the buffer when the data is no longer needed. Output applications fill
+and enqueue buffers, when enough buffers are stacked up output is
+started. In the write loop, when the application runs out of free
+buffers it must wait until an empty buffer can be dequeued and reused.
+Two methods exist to suspend execution of the application until one or
+more buffers can be dequeued. By default :ref:`VIDIOC_DQBUF
+<VIDIOC_QBUF>` blocks when no buffer is in the outgoing queue. When the
+``O_NONBLOCK`` flag was given to the :ref:`open() <func-open>` function,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` returns immediately with an ``EAGAIN``
+error code when no buffer is available. The :ref:`select()
+<func-select>` or :ref:`poll() <func-poll>` function are always
+available.
+
+To start and stop capturing or output applications call the
+:ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` and
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctl. Note
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` removes all buffers from both
+queues and unlocks all buffers as a side effect. Since there is no
+notion of doing anything "now" on a multitasking system, if an
+application needs to synchronize with another event it should examine
+the struct :ref:`v4l2_buffer <v4l2-buffer>` ``timestamp`` of captured or
+outputted buffers.
+
+Drivers implementing user pointer I/O must support the
+:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`,
+:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+and :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` ioctls, the
+:ref:`select() <func-select>` and :ref:`poll() <func-poll>` function. [2]_
+
+.. [1]
+ We expect that frequently used buffers are typically not swapped out.
+ Anyway, the process of swapping, locking or generating scatter-gather
+ lists may be time consuming. The delay can be masked by the depth of
+ the incoming buffer queue, and perhaps by maintaining caches assuming
+ a buffer will be soon enqueued again. On the other hand, to optimize
+ memory usage drivers can limit the number of buffers locked in
+ advance and recycle the most recently used buffers first. Of course,
+ the pages of empty buffers in the incoming queue need not be saved to
+ disk. Output buffers must be saved on the incoming and outgoing queue
+ because an application may share them with other processes.
+
+.. [2]
+ At the driver level :ref:`select() <func-select>` and :ref:`poll() <func-poll>` are
+ the same, and :ref:`select() <func-select>` is too important to be optional.
+ The rest should be evident.
diff --git a/Documentation/media/uapi/v4l/v4l2-selection-flags.rst b/Documentation/media/uapi/v4l/v4l2-selection-flags.rst
new file mode 100644
index 000000000000..3ce3731faf5f
--- /dev/null
+++ b/Documentation/media/uapi/v4l/v4l2-selection-flags.rst
@@ -0,0 +1,71 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selection-flags:
+
+***************
+Selection flags
+***************
+
+
+.. _v4l2-selection-flags-table:
+
+.. flat-table:: Selection flag definitions
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag name
+
+ - id
+
+ - Definition
+
+ - Valid for V4L2
+
+ - Valid for V4L2 subdev
+
+ - .. row 2
+
+ - ``V4L2_SEL_FLAG_GE``
+
+ - (1 << 0)
+
+ - Suggest the driver it should choose greater or equal rectangle (in
+ size) than was requested. Albeit the driver may choose a lesser
+ size, it will only do so due to hardware limitations. Without this
+ flag (and ``V4L2_SEL_FLAG_LE``) the behaviour is to choose the
+ closest possible rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 3
+
+ - ``V4L2_SEL_FLAG_LE``
+
+ - (1 << 1)
+
+ - Suggest the driver it should choose lesser or equal rectangle (in
+ size) than was requested. Albeit the driver may choose a greater
+ size, it will only do so due to hardware limitations.
+
+ - Yes
+
+ - Yes
+
+ - .. row 4
+
+ - ``V4L2_SEL_FLAG_KEEP_CONFIG``
+
+ - (1 << 2)
+
+ - The configuration must not be propagated to any further processing
+ steps. If this flag is not given, the configuration is propagated
+ inside the subdevice to all further processing steps.
+
+ - No
+
+ - Yes
diff --git a/Documentation/media/uapi/v4l/v4l2-selection-targets.rst b/Documentation/media/uapi/v4l/v4l2-selection-targets.rst
new file mode 100644
index 000000000000..7519099a50cd
--- /dev/null
+++ b/Documentation/media/uapi/v4l/v4l2-selection-targets.rst
@@ -0,0 +1,135 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2-selection-targets:
+
+*****************
+Selection targets
+*****************
+
+The precise meaning of the selection targets may be dependent on which
+of the two interfaces they are used.
+
+
+.. _v4l2-selection-targets-table:
+
+.. flat-table:: Selection target definitions
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Target name
+
+ - id
+
+ - Definition
+
+ - Valid for V4L2
+
+ - Valid for V4L2 subdev
+
+ - .. row 2
+
+ - ``V4L2_SEL_TGT_CROP``
+
+ - 0x0000
+
+ - Crop rectangle. Defines the cropped area.
+
+ - Yes
+
+ - Yes
+
+ - .. row 3
+
+ - ``V4L2_SEL_TGT_CROP_DEFAULT``
+
+ - 0x0001
+
+ - Suggested cropping rectangle that covers the "whole picture".
+
+ - Yes
+
+ - No
+
+ - .. row 4
+
+ - ``V4L2_SEL_TGT_CROP_BOUNDS``
+
+ - 0x0002
+
+ - Bounds of the crop rectangle. All valid crop rectangles fit inside
+ the crop bounds rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 5
+
+ - ``V4L2_SEL_TGT_NATIVE_SIZE``
+
+ - 0x0003
+
+ - The native size of the device, e.g. a sensor's pixel array.
+ ``left`` and ``top`` fields are zero for this target. Setting the
+ native size will generally only make sense for memory to memory
+ devices where the software can create a canvas of a given size in
+ which for example a video frame can be composed. In that case
+ V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size of
+ that canvas.
+
+ - Yes
+
+ - Yes
+
+ - .. row 6
+
+ - ``V4L2_SEL_TGT_COMPOSE``
+
+ - 0x0100
+
+ - Compose rectangle. Used to configure scaling and composition.
+
+ - Yes
+
+ - Yes
+
+ - .. row 7
+
+ - ``V4L2_SEL_TGT_COMPOSE_DEFAULT``
+
+ - 0x0101
+
+ - Suggested composition rectangle that covers the "whole picture".
+
+ - Yes
+
+ - No
+
+ - .. row 8
+
+ - ``V4L2_SEL_TGT_COMPOSE_BOUNDS``
+
+ - 0x0102
+
+ - Bounds of the compose rectangle. All valid compose rectangles fit
+ inside the compose bounds rectangle.
+
+ - Yes
+
+ - Yes
+
+ - .. row 9
+
+ - ``V4L2_SEL_TGT_COMPOSE_PADDED``
+
+ - 0x0103
+
+ - The active area and all padding pixels that are inserted or
+ modified by hardware.
+
+ - Yes
+
+ - No
diff --git a/Documentation/media/uapi/v4l/v4l2.rst b/Documentation/media/uapi/v4l/v4l2.rst
new file mode 100644
index 000000000000..301f95b5bdc6
--- /dev/null
+++ b/Documentation/media/uapi/v4l/v4l2.rst
@@ -0,0 +1,395 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. include:: <isonum.txt>
+.. _v4l2spec:
+
+###################
+Video for Linux API
+###################
+
+This part describes the Video for Linux API version 2 (V4L2 API) specification.
+
+**Revision 4.5**
+
+.. toctree::
+ :numbered:
+ :maxdepth: 1
+ :caption: Table of Contents
+
+ common
+ pixfmt
+ io
+ devices
+ driver
+ libv4l
+ compat
+ user-func
+ common-defs
+ videodev
+ capture-example
+ v4l2grab-example
+ biblio
+
+
+**********************
+Revision and Copyright
+**********************
+
+Authors, in alphabetical order:
+
+- Ailus, Sakari <sakari.ailus@iki.fi>
+
+ - Subdev selections API.
+
+- Carvalho Chehab, Mauro <m.chehab@kernel.org>
+
+ - Documented libv4l, designed and added v4l2grab example, Remote Controller chapter.
+
+- Dirks, Bill
+
+ - Original author of the V4L2 API and documentation.
+
+- H Schimek, Michael <mschimek@gmx.at>
+
+ - Original author of the V4L2 API and documentation.
+
+- Karicheri, Muralidharan <m-karicheri2@ti.com>
+
+ - Documented the Digital Video timings API.
+
+- Osciak, Pawel <pawel@osciak.com>
+
+ - Designed and documented the multi-planar API.
+
+- Palosaari, Antti <crope@iki.fi>
+
+ - SDR API.
+
+- Rubli, Martin
+
+ - Designed and documented the VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS ioctls.
+
+- Walls, Andy <awalls@md.metrocast.net>
+
+ - Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV MPEG stream embedded, sliced VBI data format in this specification.
+
+- Verkuil, Hans <hverkuil@xs4all.nl>
+
+ - 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.
+
+**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.
+
+Except when explicitly stated as GPL, programming examples within this
+part can be used and distributed without restrictions.
+
+****************
+Revision History
+****************
+
+:revision: 4.5 / 2015-10-29 (*rr*)
+
+Extend VIDIOC_G_EXT_CTRLS;. Replace ctrl_class with a new union with
+ctrl_class and which. Which is used to select the current value of the
+control or the default value.
+
+
+:revision: 4.4 / 2015-05-26 (*ap*)
+
+Renamed V4L2_TUNER_ADC to V4L2_TUNER_SDR. Added
+V4L2_CID_RF_TUNER_RF_GAIN control. Added transmitter support for
+Software Defined Radio (SDR) Interface.
+
+
+:revision: 4.1 / 2015-02-13 (*mcc*)
+
+Fix documentation for media controller device nodes and add support for
+DVB device nodes. Add support for Tuner sub-device.
+
+
+:revision: 3.19 / 2014-12-05 (*hv*)
+
+Rewrote Colorspace chapter, added new enum
+:ref:`v4l2_ycbcr_encoding <v4l2-ycbcr-encoding>` and enum
+:ref:`v4l2_quantization <v4l2-quantization>` fields to struct
+:ref:`v4l2_pix_format <v4l2-pix-format>`, struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` and struct
+:ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`.
+
+
+:revision: 3.17 / 2014-08-04 (*lp, hv*)
+
+Extended struct :ref:`v4l2_pix_format <v4l2-pix-format>`. Added
+format flags. Added compound control types and VIDIOC_QUERY_EXT_CTRL.
+
+
+:revision: 3.15 / 2014-02-03 (*hv, ap*)
+
+Update several sections of "Common API Elements": "Opening and Closing
+Devices" "Querying Capabilities", "Application Priority", "Video Inputs
+and Outputs", "Audio Inputs and Outputs" "Tuners and Modulators", "Video
+Standards" and "Digital Video (DV) Timings". Added SDR API.
+
+
+:revision: 3.14 / 2013-11-25 (*rr*)
+
+Set width and height as unsigned on v4l2_rect.
+
+
+:revision: 3.11 / 2013-05-26 (*hv*)
+
+Remove obsolete VIDIOC_DBG_G_CHIP_IDENT ioctl.
+
+
+:revision: 3.10 / 2013-03-25 (*hv*)
+
+Remove obsolete and unused DV_PRESET ioctls: VIDIOC_G_DV_PRESET,
+VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and
+VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output
+capability flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS.
+Added VIDIOC_DBG_G_CHIP_INFO.
+
+
+:revision: 3.9 / 2012-12-03 (*sa, sn*)
+
+Added timestamp types to v4l2_buffer. Added
+V4L2_EVENT_CTRL_CH_RANGE control event changes flag.
+
+
+:revision: 3.6 / 2012-07-02 (*hv*)
+
+Added VIDIOC_ENUM_FREQ_BANDS.
+
+
+:revision: 3.5 / 2012-05-07 (*sa, sn, hv*)
+
+Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API.
+Improved the description of V4L2_CID_COLORFX control, added
+V4L2_CID_COLORFX_CBCR control. Added camera controls
+V4L2_CID_AUTO_EXPOSURE_BIAS,
+V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE,
+V4L2_CID_IMAGE_STABILIZATION, V4L2_CID_ISO_SENSITIVITY,
+V4L2_CID_ISO_SENSITIVITY_AUTO, V4L2_CID_EXPOSURE_METERING,
+V4L2_CID_SCENE_MODE, V4L2_CID_3A_LOCK,
+V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP,
+V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. Added
+VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
+VIDIOC_DV_TIMINGS_CAP.
+
+
+:revision: 3.4 / 2012-01-25 (*sn*)
+
+Added :ref:`JPEG compression control class. <jpeg-controls>`
+
+
+:revision: 3.3 / 2012-01-11 (*hv*)
+
+Added device_caps field to struct v4l2_capabilities.
+
+
+:revision: 3.2 / 2011-08-26 (*hv*)
+
+Added V4L2_CTRL_FLAG_VOLATILE.
+
+
+:revision: 3.1 / 2011-06-27 (*mcc, po, hv*)
+
+Documented that VIDIOC_QUERYCAP now returns a per-subsystem version
+instead of a per-driver one. Standardize an error code for invalid
+ioctl. Added V4L2_CTRL_TYPE_BITMASK.
+
+
+:revision: 2.6.39 / 2011-03-01 (*mcc, po*)
+
+Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect
+latest changes. Added the :ref:`multi-planar API <planar-apis>`.
+
+
+:revision: 2.6.37 / 2010-08-06 (*hv*)
+
+Removed obsolete vtx (videotext) API.
+
+
+:revision: 2.6.33 / 2009-12-03 (*mk*)
+
+Added documentation for the Digital Video timings API.
+
+
+:revision: 2.6.32 / 2009-08-31 (*mcc*)
+
+Now, revisions will match the kernel version where the V4L2 API changes
+will be used by the Linux Kernel. Also added Remote Controller chapter.
+
+
+:revision: 0.29 / 2009-08-26 (*ev*)
+
+Added documentation for string controls and for FM Transmitter controls.
+
+
+:revision: 0.28 / 2009-08-26 (*gl*)
+
+Added V4L2_CID_BAND_STOP_FILTER documentation.
+
+
+:revision: 0.27 / 2009-08-15 (*mcc*)
+
+Added libv4l and Remote Controller documentation; added v4l2grab and
+keytable application examples.
+
+
+:revision: 0.26 / 2009-07-23 (*hv*)
+
+Finalized the RDS capture API. Added modulator and RDS encoder
+capabilities. Added support for string controls.
+
+
+:revision: 0.25 / 2009-01-18 (*hv*)
+
+Added pixel formats VYUY, NV16 and NV61, and changed the debug ioctls
+VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT. Added camera
+controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
+V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.
+
+
+:revision: 0.24 / 2008-03-04 (*mhs*)
+
+Added pixel formats Y16 and SBGGR16, new controls and a camera controls
+class. Removed VIDIOC_G/S_MPEGCOMP.
+
+
+:revision: 0.23 / 2007-08-30 (*mhs*)
+
+Fixed a typo in VIDIOC_DBG_G/S_REGISTER. Clarified the byte order of
+packed pixel formats.
+
+
+:revision: 0.22 / 2007-08-29 (*mhs*)
+
+Added the Video Output Overlay interface, new MPEG controls,
+V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
+VIDIOC_DBG_G/S_REGISTER, VIDIOC\_(TRY\_)ENCODER_CMD,
+VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
+Clarifications in the cropping chapter, about RGB pixel formats, the
+mmap(), poll(), select(), read() and write() functions. Typographical
+fixes.
+
+
+:revision: 0.21 / 2006-12-19 (*mhs*)
+
+Fixed a link in the VIDIOC_G_EXT_CTRLS section.
+
+
+:revision: 0.20 / 2006-11-24 (*mhs*)
+
+Clarified the purpose of the audioset field in struct v4l2_input and
+v4l2_output.
+
+
+:revision: 0.19 / 2006-10-19 (*mhs*)
+
+Documented V4L2_PIX_FMT_RGB444.
+
+
+:revision: 0.18 / 2006-10-18 (*mhs*)
+
+Added the description of extended controls by Hans Verkuil. Linked
+V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.
+
+
+:revision: 0.17 / 2006-10-12 (*mhs*)
+
+Corrected V4L2_PIX_FMT_HM12 description.
+
+
+:revision: 0.16 / 2006-10-08 (*mhs*)
+
+VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS are now part
+of the API.
+
+
+:revision: 0.15 / 2006-09-23 (*mhs*)
+
+Cleaned up the bibliography, added BT.653 and BT.1119.
+capture.c/start_capturing() for user pointer I/O did not initialize the
+buffer index. Documented the V4L MPEG and MJPEG VID_TYPEs and
+V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel formats. See
+the history chapter for API changes.
+
+
+:revision: 0.14 / 2006-09-14 (*mr*)
+
+Added VIDIOC_ENUM_FRAMESIZES and VIDIOC_ENUM_FRAMEINTERVALS proposal
+for frame format enumeration of digital devices.
+
+
+:revision: 0.13 / 2006-04-07 (*mhs*)
+
+Corrected the description of struct v4l2_window clips. New V4L2_STD\_
+and V4L2_TUNER_MODE_LANG1_LANG2 defines.
+
+
+:revision: 0.12 / 2006-02-03 (*mhs*)
+
+Corrected the description of struct v4l2_captureparm and
+v4l2_outputparm.
+
+
+:revision: 0.11 / 2006-01-27 (*mhs*)
+
+Improved the description of struct v4l2_tuner.
+
+
+:revision: 0.10 / 2006-01-10 (*mhs*)
+
+VIDIOC_G_INPUT and VIDIOC_S_PARM clarifications.
+
+
+:revision: 0.9 / 2005-11-27 (*mhs*)
+
+Improved the 525 line numbering diagram. Hans Verkuil and I rewrote the
+sliced VBI section. He also contributed a VIDIOC_LOG_STATUS page.
+Fixed VIDIOC_S_STD call in the video standard selection example.
+Various updates.
+
+
+:revision: 0.8 / 2004-10-04 (*mhs*)
+
+Somehow a piece of junk slipped into the capture example, removed.
+
+
+:revision: 0.7 / 2004-09-19 (*mhs*)
+
+Fixed video standard selection, control enumeration, downscaling and
+aspect example. Added read and user pointer i/o to video capture
+example.
+
+
+:revision: 0.6 / 2004-08-01 (*mhs*)
+
+v4l2_buffer changes, added video capture example, various corrections.
+
+
+:revision: 0.5 / 2003-11-05 (*mhs*)
+
+Pixel format erratum.
+
+
+:revision: 0.4 / 2003-09-17 (*mhs*)
+
+Corrected source and Makefile to generate a PDF. SGML fixes. Added
+latest API changes. Closed gaps in the history chapter.
+
+
+:revision: 0.3 / 2003-02-05 (*mhs*)
+
+Another draft, more corrections.
+
+
+:revision: 0.2 / 2003-01-15 (*mhs*)
+
+Second draft, with corrections pointed out by Gerd Knorr.
+
+
+:revision: 0.1 / 2002-12-01 (*mhs*)
+
+First draft, based on documentation by Bill Dirks and discussions on the
+V4L mailing list.
diff --git a/Documentation/media/uapi/v4l/v4l2grab-example.rst b/Documentation/media/uapi/v4l/v4l2grab-example.rst
new file mode 100644
index 000000000000..c240f0513bee
--- /dev/null
+++ b/Documentation/media/uapi/v4l/v4l2grab-example.rst
@@ -0,0 +1,17 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _v4l2grab-example:
+
+**********************************
+Video Grabber example using libv4l
+**********************************
+
+This program demonstrates how to grab V4L2 images in ppm format by using
+libv4l handlers. The advantage is that this grabber can potentially work
+with any V4L2 driver.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ v4l2grab.c
diff --git a/Documentation/media/uapi/v4l/v4l2grab.c.rst b/Documentation/media/uapi/v4l/v4l2grab.c.rst
new file mode 100644
index 000000000000..5aabd0b7b089
--- /dev/null
+++ b/Documentation/media/uapi/v4l/v4l2grab.c.rst
@@ -0,0 +1,169 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+file: media/v4l/v4l2grab.c
+==========================
+
+.. code-block:: c
+
+ /* V4L2 video picture grabber
+ Copyright (C) 2009 Mauro Carvalho Chehab <mchehab@infradead.org>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation version 2 of the License.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+ */
+
+ #include <stdio.h>
+ #include <stdlib.h>
+ #include <string.h>
+ #include <fcntl.h>
+ #include <errno.h>
+ #include <sys/ioctl.h>
+ #include <sys/types.h>
+ #include <sys/time.h>
+ #include <sys/mman.h>
+ #include <linux/videodev2.h>
+ #include "../libv4l/include/libv4l2.h"
+
+ #define CLEAR(x) memset(&(x), 0, sizeof(x))
+
+ struct buffer {
+ void *start;
+ size_t length;
+ };
+
+ static void xioctl(int fh, int request, void *arg)
+ {
+ int r;
+
+ do {
+ r = v4l2_ioctl(fh, request, arg);
+ } while (r == -1 && ((errno == EINTR) || (errno == EAGAIN)));
+
+ if (r == -1) {
+ fprintf(stderr, "error %d, %s\\n", errno, strerror(errno));
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ int main(int argc, char **argv)
+ {
+ struct v4l2_format fmt;
+ struct v4l2_buffer buf;
+ struct v4l2_requestbuffers req;
+ enum v4l2_buf_type type;
+ fd_set fds;
+ struct timeval tv;
+ int r, fd = -1;
+ unsigned int i, n_buffers;
+ char *dev_name = "/dev/video0";
+ char out_name[256];
+ FILE *fout;
+ struct buffer *buffers;
+
+ fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0);
+ if (fd < 0) {
+ perror("Cannot open device");
+ exit(EXIT_FAILURE);
+ }
+
+ CLEAR(fmt);
+ fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ fmt.fmt.pix.width = 640;
+ fmt.fmt.pix.height = 480;
+ fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24;
+ fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
+ xioctl(fd, VIDIOC_S_FMT, &fmt);
+ if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) {
+ printf("Libv4l didn't accept RGB24 format. Can't proceed.\\n");
+ exit(EXIT_FAILURE);
+ }
+ if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480))
+ printf("Warning: driver is sending image at %dx%d\\n",
+ fmt.fmt.pix.width, fmt.fmt.pix.height);
+
+ CLEAR(req);
+ req.count = 2;
+ req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ req.memory = V4L2_MEMORY_MMAP;
+ xioctl(fd, VIDIOC_REQBUFS, &req);
+
+ buffers = calloc(req.count, sizeof(*buffers));
+ for (n_buffers = 0; n_buffers < req.count; ++n_buffers) {
+ CLEAR(buf);
+
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = n_buffers;
+
+ xioctl(fd, VIDIOC_QUERYBUF, &buf);
+
+ buffers[n_buffers].length = buf.length;
+ buffers[n_buffers].start = v4l2_mmap(NULL, buf.length,
+ PROT_READ | PROT_WRITE, MAP_SHARED,
+ fd, buf.m.offset);
+
+ if (MAP_FAILED == buffers[n_buffers].start) {
+ perror("mmap");
+ exit(EXIT_FAILURE);
+ }
+ }
+
+ for (i = 0; i < n_buffers; ++i) {
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ buf.index = i;
+ xioctl(fd, VIDIOC_QBUF, &buf);
+ }
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+
+ xioctl(fd, VIDIOC_STREAMON, &type);
+ for (i = 0; i < 20; i++) {
+ do {
+ FD_ZERO(&fds);
+ FD_SET(fd, &fds);
+
+ /* Timeout. */
+ tv.tv_sec = 2;
+ tv.tv_usec = 0;
+
+ r = select(fd + 1, &fds, NULL, NULL, &tv);
+ } while ((r == -1 && (errno = EINTR)));
+ if (r == -1) {
+ perror("select");
+ return errno;
+ }
+
+ CLEAR(buf);
+ buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ buf.memory = V4L2_MEMORY_MMAP;
+ xioctl(fd, VIDIOC_DQBUF, &buf);
+
+ sprintf(out_name, "out%03d.ppm", i);
+ fout = fopen(out_name, "w");
+ if (!fout) {
+ perror("Cannot open image");
+ exit(EXIT_FAILURE);
+ }
+ fprintf(fout, "P6\\n%d %d 255\\n",
+ fmt.fmt.pix.width, fmt.fmt.pix.height);
+ fwrite(buffers[buf.index].start, buf.bytesused, 1, fout);
+ fclose(fout);
+
+ xioctl(fd, VIDIOC_QBUF, &buf);
+ }
+
+ type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ xioctl(fd, VIDIOC_STREAMOFF, &type);
+ for (i = 0; i < n_buffers; ++i)
+ v4l2_munmap(buffers[i].start, buffers[i].length);
+ v4l2_close(fd);
+
+ return 0;
+ }
diff --git a/Documentation/media/uapi/v4l/video.rst b/Documentation/media/uapi/v4l/video.rst
new file mode 100644
index 000000000000..e38ebe192614
--- /dev/null
+++ b/Documentation/media/uapi/v4l/video.rst
@@ -0,0 +1,63 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _video:
+
+************************
+Video Inputs and Outputs
+************************
+
+Video inputs and outputs are physical connectors of a device. These can
+be for example RF connectors (antenna/cable), CVBS a.k.a. Composite
+Video, S-Video or RGB connectors. Video and VBI capture devices have
+inputs. Video and VBI output devices have outputs, at least one each.
+Radio devices have no video inputs or outputs.
+
+To learn about the number and attributes of the available inputs and
+outputs applications can enumerate them with the
+:ref:`VIDIOC_ENUMINPUT` and
+:ref:`VIDIOC_ENUMOUTPUT` ioctl, respectively. The
+struct :ref:`v4l2_input <v4l2-input>` returned by the
+:ref:`VIDIOC_ENUMINPUT` ioctl also contains signal
+:status information applicable when the current video input is queried.
+
+The :ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctls return the index of
+the current video input or output. To select a different input or output
+applications call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` and
+:ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctls. Drivers must
+implement all the input ioctls when the device has one or more inputs,
+all the output ioctls when the device has one or more outputs.
+
+.. code-block:: c
+ :caption: Example 1.1. Information about the current video input
+
+ struct v4l2_input input;
+ int index;
+
+ if (-1 == ioctl(fd, VIDIOC_G_INPUT, &index)) {
+ perror("VIDIOC_G_INPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ memset(&input, 0, sizeof(input));
+ input.index = index;
+
+ if (-1 == ioctl(fd, VIDIOC_ENUMINPUT, &input)) {
+ perror("VIDIOC_ENUMINPUT");
+ exit(EXIT_FAILURE);
+ }
+
+ printf("Current input: %s\\n", input.name);
+
+
+.. code-block:: c
+ :caption: Example 1.2. Switching to the first video input
+
+ int index;
+
+ index = 0;
+
+ if (-1 == ioctl(fd, VIDIOC_S_INPUT, &index)) {
+ perror("VIDIOC_S_INPUT");
+ exit(EXIT_FAILURE);
+ }
diff --git a/Documentation/media/uapi/v4l/videodev.rst b/Documentation/media/uapi/v4l/videodev.rst
new file mode 100644
index 000000000000..b9ee4672d639
--- /dev/null
+++ b/Documentation/media/uapi/v4l/videodev.rst
@@ -0,0 +1,9 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _videodev:
+
+*******************************
+Video For Linux Two Header File
+*******************************
+
+.. kernel-include:: $BUILDDIR/videodev2.h.rst
diff --git a/Documentation/media/uapi/v4l/vidioc-create-bufs.rst b/Documentation/media/uapi/v4l/vidioc-create-bufs.rst
new file mode 100644
index 000000000000..abdc0b4d83d5
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-create-bufs.rst
@@ -0,0 +1,146 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_CREATE_BUFS:
+
+************************
+ioctl VIDIOC_CREATE_BUFS
+************************
+
+Name
+====
+
+VIDIOC_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_create_buffers *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_CREATE_BUFS
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is used to create buffers for :ref:`memory mapped <mmap>`
+or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. It
+can be used as an alternative or in addition to the
+:ref:`VIDIOC_REQBUFS` ioctl, when a tighter control
+over buffers is required. This ioctl can be called multiple times to
+create buffers of different sizes.
+
+To allocate the device buffers applications must initialize the relevant
+fields of the :ref:`struct v4l2_create_buffers <v4l2-create-buffers>` structure. The
+``count`` field must be set to the number of requested buffers, the
+``memory`` field specifies the requested I/O method and the ``reserved``
+array must be zeroed.
+
+The ``format`` field specifies the image format that the buffers must be
+able to handle. The application has to fill in this struct
+:ref:`v4l2_format <v4l2-format>`. Usually this will be done using the
+:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` or
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctls to ensure that the
+requested format is supported by the driver. Based on the format's
+``type`` field the requested buffer size (for single-planar) or plane
+sizes (for multi-planar formats) will be used for the allocated buffers.
+The driver may return an error if the size(s) are not supported by the
+hardware (usually because they are too small).
+
+The buffers created by this ioctl will have as minimum size the size
+defined by the ``format.pix.sizeimage`` field (or the corresponding
+fields for other format types). Usually if the ``format.pix.sizeimage``
+field is less than the minimum required for the given format, then an
+error will be returned since drivers will typically not allow this. If
+it is larger, then the value will be used as-is. In other words, the
+driver may reject the requested size, but if it is accepted the driver
+will use it unchanged.
+
+When the ioctl is called with a pointer to this structure the driver
+will attempt to allocate up to the requested number of buffers and store
+the actual number allocated and the starting index in the ``count`` and
+the ``index`` fields respectively. On return ``count`` can be smaller
+than the number requested.
+
+
+.. _v4l2-create-buffers:
+
+.. flat-table:: struct v4l2_create_buffers
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - The starting buffer index, returned by the driver.
+
+ - .. row 2
+
+ - __u32
+
+ - ``count``
+
+ - The number of buffers requested or granted. If count == 0, then
+ :ref:`VIDIOC_CREATE_BUFS` will set ``index`` to the current number of
+ created buffers, and it will check the validity of ``memory`` and
+ ``format.type``. If those are invalid -1 is returned and errno is
+ set to ``EINVAL`` error code, otherwise :ref:`VIDIOC_CREATE_BUFS` returns
+ 0. It will never set errno to ``EBUSY`` error code in this particular
+ case.
+
+ - .. row 3
+
+ - __u32
+
+ - ``memory``
+
+ - Applications set this field to ``V4L2_MEMORY_MMAP``,
+ ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
+ :ref:`v4l2-memory`
+
+ - .. row 4
+
+ - struct :ref:`v4l2_format <v4l2-format>`
+
+ - ``format``
+
+ - Filled in by the application, preserved by the driver.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - A place holder for future extensions. Drivers and applications
+ must set the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+ENOMEM
+ No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O.
+
+EINVAL
+ The buffer type (``format.type`` field), requested I/O method
+ (``memory``) or format (``format`` field) is not valid.
diff --git a/Documentation/media/uapi/v4l/vidioc-cropcap.rst b/Documentation/media/uapi/v4l/vidioc-cropcap.rst
new file mode 100644
index 000000000000..8dcbe6d26219
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-cropcap.rst
@@ -0,0 +1,167 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_CROPCAP:
+
+********************
+ioctl VIDIOC_CROPCAP
+********************
+
+Name
+====
+
+VIDIOC_CROPCAP - Information about the video cropping and scaling abilities
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_cropcap *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_CROPCAP
+
+``argp``
+
+
+Description
+===========
+
+Applications use this function to query the cropping limits, the pixel
+aspect of images and to calculate scale factors. They set the ``type``
+field of a v4l2_cropcap structure to the respective buffer (stream)
+type and call the :ref:`VIDIOC_CROPCAP` ioctl with a pointer to this
+structure. Drivers fill the rest of the structure. The results are
+constant except when switching the video standard. Remember this switch
+can occur implicit when switching the video input or output.
+
+Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
+
+This ioctl must be implemented for video capture or output devices that
+support cropping and/or scaling and/or have non-square pixels, and for
+overlay devices.
+
+
+.. _v4l2-cropcap:
+
+.. flat-table:: struct v4l2_cropcap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_rect <v4l2-rect-crop>`
+
+ - ``bounds``
+
+ - Defines the window within capturing or output is possible, this
+ may exclude for example the horizontal and vertical blanking
+ areas. The cropping rectangle cannot exceed these limits. Width
+ and height are defined in pixels, the driver writer is free to
+ choose origin and units of the coordinate system in the analog
+ domain.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_rect <v4l2-rect-crop>`
+
+ - ``defrect``
+
+ - Default cropping rectangle, it shall cover the "whole picture".
+ Assuming pixel aspect 1/1 this could be for example a 640 × 480
+ rectangle for NTSC, a 768 × 576 rectangle for PAL and SECAM
+ centered over the active picture area. The same co-ordinate system
+ as for ``bounds`` is used.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``pixelaspect``
+
+ - This is the pixel aspect (y / x) when no scaling is applied, the
+ ratio of the actual sampling frequency and the frequency required
+ to get square pixels.
+
+ When cropping coordinates refer to square pixels, the driver sets
+ ``pixelaspect`` to 1/1. Other common values are 54/59 for PAL and
+ SECAM, 11/10 for NTSC sampled according to [:ref:`itu601`].
+
+
+
+.. _v4l2-rect-crop:
+
+.. flat-table:: struct v4l2_rect
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __s32
+
+ - ``left``
+
+ - Horizontal offset of the top, left corner of the rectangle, in
+ pixels.
+
+ - .. row 2
+
+ - __s32
+
+ - ``top``
+
+ - Vertical offset of the top, left corner of the rectangle, in
+ pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``width``
+
+ - Width of the rectangle, in pixels.
+
+ - .. row 4
+
+ - __u32
+
+ - ``height``
+
+ - Height of the rectangle, in pixels.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_cropcap <v4l2-cropcap>` ``type`` is
+ invalid.
diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst
new file mode 100644
index 000000000000..efa911c0fb19
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst
@@ -0,0 +1,204 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DBG_G_CHIP_INFO:
+
+****************************
+ioctl VIDIOC_DBG_G_CHIP_INFO
+****************************
+
+Name
+====
+
+VIDIOC_DBG_G_CHIP_INFO - Identify the chips on a TV card
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_chip_info *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DBG_G_CHIP_INFO
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`experimental` interface and may
+ change in the future.
+
+For driver debugging purposes this ioctl allows test applications to
+query the driver about the chips present on the TV card. Regular
+applications must not use it. When you found a chip specific bug, please
+contact the linux-media mailing list
+(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+so it can be fixed.
+
+Additionally the Linux kernel must be compiled with the
+``CONFIG_VIDEO_ADV_DEBUG`` option to enable this ioctl.
+
+To query the driver applications must initialize the ``match.type`` and
+``match.addr`` or ``match.name`` fields of a struct
+:ref:`v4l2_dbg_chip_info <v4l2-dbg-chip-info>` and call
+:ref:`VIDIOC_DBG_G_CHIP_INFO` with a pointer to this structure. On success
+the driver stores information about the selected chip in the ``name``
+and ``flags`` fields.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
+selects the nth bridge 'chip' on the TV card. You can enumerate all
+chips by starting at zero and incrementing ``match.addr`` by one until
+:ref:`VIDIOC_DBG_G_CHIP_INFO` fails with an ``EINVAL`` error code. The number
+zero always selects the bridge chip itself, e. g. the chip connected to
+the PCI or USB bus. Non-zero numbers identify specific parts of the
+bridge chip such as an AC97 register block.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
+selects the nth sub-device. This allows you to enumerate over all
+sub-devices.
+
+On success, the ``name`` field will contain a chip name and the
+``flags`` field will contain ``V4L2_CHIP_FL_READABLE`` if the driver
+supports reading registers from the device or ``V4L2_CHIP_FL_WRITABLE``
+if the driver supports writing registers to the device.
+
+We recommended the v4l2-dbg utility over calling this ioctl directly. It
+is available from the LinuxTV v4l-dvb repository; see
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
+
+
+.. _name-v4l2-dbg-match:
+
+.. flat-table:: struct v4l2_dbg_match
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - See :ref:`name-chip-match-types` for a list of possible types.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``addr``
+
+ - Match a chip by this number, interpreted according to the ``type``
+ field.
+
+ - .. row 4
+
+ -
+ - char
+
+ - ``name[32]``
+
+ - Match a chip by this name, interpreted according to the ``type``
+ field. Currently unused.
+
+
+
+.. _v4l2-dbg-chip-info:
+
+.. flat-table:: struct v4l2_dbg_chip_info
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct v4l2_dbg_match
+
+ - ``match``
+
+ - How to match the chip, see :ref:`name-v4l2-dbg-match`.
+
+ - .. row 2
+
+ - char
+
+ - ``name[32]``
+
+ - The name of the chip.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Set by the driver. If ``V4L2_CHIP_FL_READABLE`` is set, then the
+ driver supports reading registers from the device. If
+ ``V4L2_CHIP_FL_WRITABLE`` is set, then it supports writing
+ registers.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved[8]``
+
+ - Reserved fields, both application and driver must set these to 0.
+
+
+
+.. _name-chip-match-types:
+
+.. flat-table:: Chip Match Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CHIP_MATCH_BRIDGE``
+
+ - 0
+
+ - Match the nth chip on the card, zero for the bridge chip. Does not
+ match sub-devices.
+
+ - .. row 2
+
+ - ``V4L2_CHIP_MATCH_SUBDEV``
+
+ - 4
+
+ - Match the nth sub-device.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``match_type`` is invalid or no device could be matched.
diff --git a/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst
new file mode 100644
index 000000000000..345aa321f380
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst
@@ -0,0 +1,209 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DBG_G_REGISTER:
+
+**************************************************
+ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
+**************************************************
+
+Name
+====
+
+VIDIOC_DBG_G_REGISTER - VIDIOC_DBG_S_REGISTER - Read or write hardware registers
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dbg_register *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_dbg_register *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`experimental` interface and may
+ change in the future.
+
+For driver debugging purposes these ioctls allow test applications to
+access hardware registers directly. Regular applications must not use
+them.
+
+Since writing or even reading registers can jeopardize the system
+security, its stability and damage the hardware, both ioctls require
+superuser privileges. Additionally the Linux kernel must be compiled
+with the ``CONFIG_VIDEO_ADV_DEBUG`` option to enable these ioctls.
+
+To write a register applications must initialize all fields of a struct
+:ref:`v4l2_dbg_register <v4l2-dbg-register>` except for ``size`` and
+call ``VIDIOC_DBG_S_REGISTER`` with a pointer to this structure. The
+``match.type`` and ``match.addr`` or ``match.name`` fields select a chip
+on the TV card, the ``reg`` field specifies a register number and the
+``val`` field the value to be written into the register.
+
+To read a register applications must initialize the ``match.type``,
+``match.addr`` or ``match.name`` and ``reg`` fields, and call
+``VIDIOC_DBG_G_REGISTER`` with a pointer to this structure. On success
+the driver stores the register value in the ``val`` field and the size
+(in bytes) of the value in ``size``.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_BRIDGE``, ``match.addr``
+selects the nth non-sub-device chip on the TV card. The number zero
+always selects the host chip, e. g. the chip connected to the PCI or USB
+bus. You can find out which chips are present with the
+:ref:`VIDIOC_DBG_G_CHIP_INFO` ioctl.
+
+When ``match.type`` is ``V4L2_CHIP_MATCH_SUBDEV``, ``match.addr``
+selects the nth sub-device.
+
+These ioctls are optional, not all drivers may support them. However
+when a driver supports these ioctls it must also support
+:ref:`VIDIOC_DBG_G_CHIP_INFO`. Conversely
+it may support ``VIDIOC_DBG_G_CHIP_INFO`` but not these ioctls.
+
+``VIDIOC_DBG_G_REGISTER`` and ``VIDIOC_DBG_S_REGISTER`` were introduced
+in Linux 2.6.21, but their API was changed to the one described here in
+kernel 2.6.29.
+
+We recommended the v4l2-dbg utility over calling these ioctls directly.
+It is available from the LinuxTV v4l-dvb repository; see
+`https://linuxtv.org/repo/ <https://linuxtv.org/repo/>`__ for access
+instructions.
+
+
+.. _v4l2-dbg-match:
+
+.. flat-table:: struct v4l2_dbg_match
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - See :ref:`chip-match-types` for a list of possible types.
+
+ - .. row 2
+
+ - union
+
+ - (anonymous)
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``addr``
+
+ - Match a chip by this number, interpreted according to the ``type``
+ field.
+
+ - .. row 4
+
+ -
+ - char
+
+ - ``name[32]``
+
+ - Match a chip by this name, interpreted according to the ``type``
+ field. Currently unused.
+
+
+
+.. _v4l2-dbg-register:
+
+.. flat-table:: struct v4l2_dbg_register
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - struct v4l2_dbg_match
+
+ - ``match``
+
+ - How to match the chip, see :ref:`v4l2-dbg-match`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``size``
+
+ - The register size in bytes.
+
+ - .. row 3
+
+ - __u64
+
+ - ``reg``
+
+ - A register number.
+
+ - .. row 4
+
+ - __u64
+
+ - ``val``
+
+ - The value read from, or to be written into the register.
+
+
+
+.. _chip-match-types:
+
+.. flat-table:: Chip Match Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CHIP_MATCH_BRIDGE``
+
+ - 0
+
+ - Match the nth chip on the card, zero for the bridge chip. Does not
+ match sub-devices.
+
+ - .. row 2
+
+ - ``V4L2_CHIP_MATCH_SUBDEV``
+
+ - 4
+
+ - Match the nth sub-device.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EPERM
+ Insufficient permissions. Root privileges are required to execute
+ these ioctls.
diff --git a/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
new file mode 100644
index 000000000000..2a36e91b57b9
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst
@@ -0,0 +1,271 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DECODER_CMD:
+
+************************************************
+ioctl VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
+************************************************
+
+Name
+====
+
+VIDIOC_DECODER_CMD - VIDIOC_TRY_DECODER_CMD - Execute an decoder command
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_decoder_cmd *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DECODER_CMD, VIDIOC_TRY_DECODER_CMD
+
+``argp``
+
+
+Description
+===========
+
+These ioctls control an audio/video (usually MPEG-) decoder.
+``VIDIOC_DECODER_CMD`` sends a command to the decoder,
+``VIDIOC_TRY_DECODER_CMD`` can be used to try a command without actually
+executing it. To send a command applications must initialize all fields
+of a struct :ref:`v4l2_decoder_cmd <v4l2-decoder-cmd>` and call
+``VIDIOC_DECODER_CMD`` or ``VIDIOC_TRY_DECODER_CMD`` with a pointer to
+this structure.
+
+The ``cmd`` field must contain the command code. Some commands use the
+``flags`` field for additional information.
+
+A :ref:`write() <func-write>` or :ref:`VIDIOC_STREAMON`
+call sends an implicit START command to the decoder if it has not been
+started yet.
+
+A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+call of a streaming file descriptor sends an implicit immediate STOP
+command to the decoder, and all buffered data is discarded.
+
+These ioctls are optional, not all drivers may support them. They were
+introduced in Linux 3.3.
+
+
+.. _v4l2-decoder-cmd:
+
+.. flat-table:: struct v4l2_decoder_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``cmd``
+
+ -
+ -
+ - The decoder command, see :ref:`decoder-cmds`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ -
+ -
+ - Flags to go with the command. If no flags are defined for this
+ command, drivers and applications must set this field to zero.
+
+ - .. row 3
+
+ - union
+
+ - (anonymous)
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - struct
+
+ - ``start``
+
+ -
+ - Structure containing additional data for the
+ ``V4L2_DEC_CMD_START`` command.
+
+ - .. row 5
+
+ -
+ -
+ - __s32
+
+ - ``speed``
+
+ - Playback speed and direction. The playback speed is defined as
+ ``speed``/1000 of the normal speed. So 1000 is normal playback.
+ Negative numbers denote reverse playback, so -1000 does reverse
+ playback at normal speed. Speeds -1, 0 and 1 have special
+ meanings: speed 0 is shorthand for 1000 (normal playback). A speed
+ of 1 steps just one frame forward, a speed of -1 steps just one
+ frame back.
+
+ - .. row 6
+
+ -
+ -
+ - __u32
+
+ - ``format``
+
+ - Format restrictions. This field is set by the driver, not the
+ application. Possible values are ``V4L2_DEC_START_FMT_NONE`` if
+ there are no format restrictions or ``V4L2_DEC_START_FMT_GOP`` if
+ the decoder operates on full GOPs (*Group Of Pictures*). This is
+ usually the case for reverse playback: the decoder needs full
+ GOPs, which it can then play in reverse order. So to implement
+ reverse playback the application must feed the decoder the last
+ GOP in the video file, then the GOP before that, etc. etc.
+
+ - .. row 7
+
+ -
+ - struct
+
+ - ``stop``
+
+ -
+ - Structure containing additional data for the ``V4L2_DEC_CMD_STOP``
+ command.
+
+ - .. row 8
+
+ -
+ -
+ - __u64
+
+ - ``pts``
+
+ - Stop playback at this ``pts`` or immediately if the playback is
+ already past that timestamp. Leave to 0 if you want to stop after
+ the last frame was decoded.
+
+ - .. row 9
+
+ -
+ - struct
+
+ - ``raw``
+
+ -
+ -
+
+ - .. row 10
+
+ -
+ -
+ - __u32
+
+ - ``data``\ [16]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _decoder-cmds:
+
+.. flat-table:: Decoder Commands
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_DEC_CMD_START``
+
+ - 0
+
+ - Start the decoder. When the decoder is already running or paused,
+ this command will just change the playback speed. That means that
+ calling ``V4L2_DEC_CMD_START`` when the decoder was paused will
+ *not* resume the decoder. You have to explicitly call
+ ``V4L2_DEC_CMD_RESUME`` for that. This command has one flag:
+ ``V4L2_DEC_CMD_START_MUTE_AUDIO``. If set, then audio will be
+ muted when playing back at a non-standard speed.
+
+ - .. row 2
+
+ - ``V4L2_DEC_CMD_STOP``
+
+ - 1
+
+ - Stop the decoder. When the decoder is already stopped, this
+ command does nothing. This command has two flags: if
+ ``V4L2_DEC_CMD_STOP_TO_BLACK`` is set, then the decoder will set
+ the picture to black after it stopped decoding. Otherwise the last
+ image will repeat. mem2mem decoders will stop producing new frames
+ altogether. They will send a ``V4L2_EVENT_EOS`` event when the
+ last frame has been decoded and all frames are ready to be
+ dequeued and will set the ``V4L2_BUF_FLAG_LAST`` buffer flag on
+ the last buffer of the capture queue to indicate there will be no
+ new buffers produced to dequeue. This buffer may be empty,
+ indicated by the driver setting the ``bytesused`` field to 0. Once
+ the ``V4L2_BUF_FLAG_LAST`` flag was set, the
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
+ but return an ``EPIPE`` error code. If
+ ``V4L2_DEC_CMD_STOP_IMMEDIATELY`` is set, then the decoder stops
+ immediately (ignoring the ``pts`` value), otherwise it will keep
+ decoding until timestamp >= pts or until the last of the pending
+ data from its internal buffers was decoded.
+
+ - .. row 3
+
+ - ``V4L2_DEC_CMD_PAUSE``
+
+ - 2
+
+ - Pause the decoder. When the decoder has not been started yet, the
+ driver will return an ``EPERM`` error code. When the decoder is
+ already paused, this command does nothing. This command has one
+ flag: if ``V4L2_DEC_CMD_PAUSE_TO_BLACK`` is set, then set the
+ decoder output to black when paused.
+
+ - .. row 4
+
+ - ``V4L2_DEC_CMD_RESUME``
+
+ - 3
+
+ - Resume decoding after a PAUSE command. When the decoder has not
+ been started yet, the driver will return an ``EPERM`` error code. When
+ the decoder is already running, this command does nothing. No
+ flags are defined for this command.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``cmd`` field is invalid.
+
+EPERM
+ The application sent a PAUSE or RESUME command when the decoder was
+ not running.
diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst
new file mode 100644
index 000000000000..73c0d5be62ee
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst
@@ -0,0 +1,573 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DQEVENT:
+
+********************
+ioctl VIDIOC_DQEVENT
+********************
+
+Name
+====
+
+VIDIOC_DQEVENT - Dequeue event
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DQEVENT
+
+``argp``
+
+
+Description
+===========
+
+Dequeue an event from a video device. No input is required for this
+ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>`
+structure are filled by the driver. The file handle will also receive
+exceptions which the application may get by e.g. using the select system
+call.
+
+
+.. _v4l2-event:
+
+.. flat-table:: struct v4l2_event
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the event, see :ref:`event-type`.
+
+ - .. row 2
+
+ - union
+
+ - ``u``
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>`
+
+ - ``vsync``
+
+ - Event data for event ``V4L2_EVENT_VSYNC``.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>`
+
+ - ``ctrl``
+
+ - Event data for event ``V4L2_EVENT_CTRL``.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
+
+ - ``frame_sync``
+
+ - Event data for event ``V4L2_EVENT_FRAME_SYNC``.
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
+
+ - ``motion_det``
+
+ - Event data for event V4L2_EVENT_MOTION_DET.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_event_src_change <v4l2-event-src-change>`
+
+ - ``src_change``
+
+ - Event data for event V4L2_EVENT_SOURCE_CHANGE.
+
+ - .. row 8
+
+ -
+ - __u8
+
+ - ``data``\ [64]
+
+ - Event data. Defined by the event type. The union should be used to
+ define easily accessible type for events.
+
+ - .. row 9
+
+ - __u32
+
+ - ``pending``
+
+ -
+ - Number of pending events excluding this one.
+
+ - .. row 10
+
+ - __u32
+
+ - ``sequence``
+
+ -
+ - Event sequence number. The sequence number is incremented for
+ every subscribed event that takes place. If sequence numbers are
+ not contiguous it means that events have been lost.
+
+ - .. row 11
+
+ - struct timespec
+
+ - ``timestamp``
+
+ -
+ - Event timestamp. The timestamp has been taken from the
+ ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2,
+ use :c:func:`clock_gettime(2)`.
+
+ - .. row 12
+
+ - u32
+
+ - ``id``
+
+ -
+ - The ID associated with the event source. If the event does not
+ have an associated ID (this depends on the event type), then this
+ is 0.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ -
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _event-type:
+
+.. flat-table:: Event Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_ALL``
+
+ - 0
+
+ - All events. V4L2_EVENT_ALL is valid only for
+ VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_VSYNC``
+
+ - 1
+
+ - This event is triggered on the vertical sync. This event has a
+ struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated
+ with it.
+
+ - .. row 3
+
+ - ``V4L2_EVENT_EOS``
+
+ - 2
+
+ - This event is triggered when the end of a stream is reached. This
+ is typically used with MPEG decoders to report to the application
+ when the last of the MPEG stream has been decoded.
+
+ - .. row 4
+
+ - ``V4L2_EVENT_CTRL``
+
+ - 3
+
+ - This event requires that the ``id`` matches the control ID from
+ which you want to receive events. This event is triggered if the
+ control's value changes, if a button control is pressed or if the
+ control's flags change. This event has a struct
+ :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it.
+ This struct contains much of the same information as struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct
+ :ref:`v4l2_control <v4l2-control>`.
+
+ If the event is generated due to a call to
+ :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the
+ event will *not* be sent to the file handle that called the ioctl
+ function. This prevents nasty feedback loops. If you *do* want to
+ get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
+ flag.
+
+ This event type will ensure that no information is lost when more
+ events are raised than there is room internally. In that case the
+ struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the
+ second-oldest event is kept, but the ``changes`` field of the
+ second-oldest event is ORed with the ``changes`` field of the
+ oldest event.
+
+ - .. row 5
+
+ - ``V4L2_EVENT_FRAME_SYNC``
+
+ - 4
+
+ - Triggered immediately when the reception of a frame has begun.
+ This event has a struct
+ :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>`
+ associated with it.
+
+ If the hardware needs to be stopped in the case of a buffer
+ underrun it might not be able to generate this event. In such
+ cases the ``frame_sequence`` field in struct
+ :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not
+ be incremented. This causes two consecutive frame sequence numbers
+ to have n times frame interval in between them.
+
+ - .. row 6
+
+ - ``V4L2_EVENT_SOURCE_CHANGE``
+
+ - 5
+
+ - This event is triggered when a source parameter change is detected
+ during runtime by the video device. It can be a runtime resolution
+ change triggered by a video decoder or the format change happening
+ on an input connector. This event requires that the ``id`` matches
+ the input index (when used with a video device node) or the pad
+ index (when used with a subdevice node) from which you want to
+ receive events.
+
+ This event has a struct
+ :ref:`v4l2_event_src_change <v4l2-event-src-change>`
+ associated with it. The ``changes`` bitfield denotes what has
+ changed for the subscribed pad. If multiple events occurred before
+ application could dequeue them, then the changes will have the
+ ORed value of all the events generated.
+
+ - .. row 7
+
+ - ``V4L2_EVENT_MOTION_DET``
+
+ - 6
+
+ - Triggered whenever the motion detection state for one or more of
+ the regions changes. This event has a struct
+ :ref:`v4l2_event_motion_det <v4l2-event-motion-det>`
+ associated with it.
+
+ - .. row 8
+
+ - ``V4L2_EVENT_PRIVATE_START``
+
+ - 0x08000000
+
+ - Base event number for driver-private events.
+
+
+
+.. _v4l2-event-vsync:
+
+.. flat-table:: struct v4l2_event_vsync
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``field``
+
+ - The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`.
+
+
+
+.. _v4l2-event-ctrl:
+
+.. flat-table:: struct v4l2_event_ctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``changes``
+
+ -
+ - A bitmask that tells what has changed. See
+ :ref:`ctrl-changes-flags`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ -
+ - The type of the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`.
+
+ - .. row 3
+
+ - union (anonymous)
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __s32
+
+ - ``value``
+
+ - The 32-bit value of the control for 32-bit control types. This is
+ 0 for string controls since the value of a string cannot be passed
+ using :ref:`VIDIOC_DQEVENT`.
+
+ - .. row 5
+
+ -
+ - __s64
+
+ - ``value64``
+
+ - The 64-bit value of the control for 64-bit control types.
+
+ - .. row 6
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - The control flags. See :ref:`control-flags`.
+
+ - .. row 7
+
+ - __s32
+
+ - ``minimum``
+
+ -
+ - The minimum value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 8
+
+ - __s32
+
+ - ``maximum``
+
+ -
+ - The maximum value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 9
+
+ - __s32
+
+ - ``step``
+
+ -
+ - The step value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+ - .. row 10
+
+ - __s32
+
+ - ``default_value``
+
+ -
+ - The default value value of the control. See struct
+ :ref:`v4l2_queryctrl <v4l2-queryctrl>`.
+
+
+
+.. _v4l2-event-frame-sync:
+
+.. flat-table:: struct v4l2_event_frame_sync
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``frame_sequence``
+
+ - The sequence number of the frame being received.
+
+
+
+.. _v4l2-event-src-change:
+
+.. flat-table:: struct v4l2_event_src_change
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``changes``
+
+ - A bitmask that tells what has changed. See
+ :ref:`src-changes-flags`.
+
+
+
+.. _v4l2-event-motion-det:
+
+.. flat-table:: struct v4l2_event_motion_det
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``flags``
+
+ - Currently only one flag is available: if
+ ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the
+ ``frame_sequence`` field is valid, otherwise that field should be
+ ignored.
+
+ - .. row 2
+
+ - __u32
+
+ - ``frame_sequence``
+
+ - The sequence number of the frame being received. Only valid if the
+ ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set.
+
+ - .. row 3
+
+ - __u32
+
+ - ``region_mask``
+
+ - The bitmask of the regions that reported motion. There is at least
+ one region. If this field is 0, then no motion was detected at
+ all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control
+ (see :ref:`detect-controls`) to assign a different region to
+ each cell in the motion detection grid, then that all cells are
+ automatically assigned to the default region 0.
+
+
+
+.. _ctrl-changes-flags:
+
+.. flat-table:: Control Changes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_CTRL_CH_VALUE``
+
+ - 0x0001
+
+ - This control event was triggered because the value of the control
+ changed. Special cases: Volatile controls do no generate this
+ event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
+ flag set, then this event is sent as well, regardless its value.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_CTRL_CH_FLAGS``
+
+ - 0x0002
+
+ - This control event was triggered because the control flags
+ changed.
+
+ - .. row 3
+
+ - ``V4L2_EVENT_CTRL_CH_RANGE``
+
+ - 0x0004
+
+ - This control event was triggered because the minimum, maximum,
+ step or the default value of the control changed.
+
+
+
+.. _src-changes-flags:
+
+.. flat-table:: Source Changes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_SRC_CH_RESOLUTION``
+
+ - 0x0001
+
+ - This event gets triggered when a resolution change is detected at
+ an input. This can come from an input connector or from a video
+ decoder.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst
new file mode 100644
index 000000000000..5a35bb254b4b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst
@@ -0,0 +1,250 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_DV_TIMINGS_CAP:
+
+*********************************************************
+ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
+*********************************************************
+
+Name
+====
+
+VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings_cap *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
+
+``argp``
+
+
+Description
+===========
+
+To query the capabilities of the DV receiver/transmitter applications
+initialize the ``pad`` field to 0, zero the reserved array of struct
+:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` and call the
+``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill
+in the structure. Note that drivers may return different values after
+switching the video input or output.
+
+When implemented by the driver DV capabilities of subdevices can be
+queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly
+on a subdevice node. The capabilities are specific to inputs (for DV
+receivers) or outputs (for DV transmitters), applications must specify
+the desired pad number in the struct
+:ref:`v4l2_dv_timings_cap <v4l2-dv-timings-cap>` ``pad`` field and
+zero the ``reserved`` array. Attempts to query capabilities on a pad
+that doesn't support them will return an ``EINVAL`` error code.
+
+
+.. _v4l2-bt-timings-cap:
+
+.. flat-table:: struct v4l2_bt_timings_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum width of the active video in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum width of the active video in pixels.
+
+ - .. row 3
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum height of the active video in lines.
+
+ - .. row 4
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum height of the active video in lines.
+
+ - .. row 5
+
+ - __u64
+
+ - ``min_pixelclock``
+
+ - Minimum pixelclock frequency in Hz.
+
+ - .. row 6
+
+ - __u64
+
+ - ``max_pixelclock``
+
+ - Maximum pixelclock frequency in Hz.
+
+ - .. row 7
+
+ - __u32
+
+ - ``standards``
+
+ - The video standard(s) supported by the hardware. See
+ :ref:`dv-bt-standards` for a list of standards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``capabilities``
+
+ - Several flags giving more information about the capabilities. See
+ :ref:`dv-bt-cap-capabilities` for a description of the flags.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [16]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-dv-timings-cap:
+
+.. flat-table:: struct v4l2_dv_timings_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of DV timings as listed in :ref:`dv-timing-types`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API. This field is
+ only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - union
+
+ -
+ -
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_bt_timings_cap <v4l2-bt-timings-cap>`
+
+ - ``bt``
+
+ - BT.656/1120 timings capabilities of the hardware.
+
+ - .. row 6
+
+ -
+ - __u32
+
+ - ``raw_data``\ [32]
+
+ -
+
+
+
+.. _dv-bt-cap-capabilities:
+
+.. flat-table:: DV BT Timing capabilities
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_BT_CAP_INTERLACED``
+
+ - Interlaced formats are supported.
+
+ - .. row 4
+
+ - ``V4L2_DV_BT_CAP_PROGRESSIVE``
+
+ - Progressive formats are supported.
+
+ - .. row 5
+
+ - ``V4L2_DV_BT_CAP_REDUCED_BLANKING``
+
+ - CVT/GTF specific: the timings can make use of reduced blanking
+ (CVT) or the 'Secondary GTF' curve (GTF).
+
+ - .. row 6
+
+ - ``V4L2_DV_BT_CAP_CUSTOM``
+
+ - Can support non-standard timings, i.e. timings not belonging to
+ the standards set in the ``standards`` field.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
new file mode 100644
index 000000000000..69bd9b4e0e56
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst
@@ -0,0 +1,195 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENCODER_CMD:
+
+************************************************
+ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+************************************************
+
+Name
+====
+
+VIDIOC_ENCODER_CMD - VIDIOC_TRY_ENCODER_CMD - Execute an encoder command
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_encoder_cmd *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD
+
+``argp``
+
+
+Description
+===========
+
+These ioctls control an audio/video (usually MPEG-) encoder.
+``VIDIOC_ENCODER_CMD`` sends a command to the encoder,
+``VIDIOC_TRY_ENCODER_CMD`` can be used to try a command without actually
+executing it.
+
+To send a command applications must initialize all fields of a struct
+:ref:`v4l2_encoder_cmd <v4l2-encoder-cmd>` and call
+``VIDIOC_ENCODER_CMD`` or ``VIDIOC_TRY_ENCODER_CMD`` with a pointer to
+this structure.
+
+The ``cmd`` field must contain the command code. The ``flags`` field is
+currently only used by the STOP command and contains one bit: If the
+``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag is set, encoding will continue
+until the end of the current *Group Of Pictures*, otherwise it will stop
+immediately.
+
+A :ref:`read() <func-read>` or :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>`
+call sends an implicit START command to the encoder if it has not been
+started yet. After a STOP command, :ref:`read() <func-read>` calls will read
+the remaining data buffered by the driver. When the buffer is empty,
+:ref:`read() <func-read>` will return zero and the next :ref:`read() <func-read>`
+call will restart the encoder.
+
+A :ref:`close() <func-close>` or :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`
+call of a streaming file descriptor sends an implicit immediate STOP to
+the encoder, and all buffered data is discarded.
+
+These ioctls are optional, not all drivers may support them. They were
+introduced in Linux 2.6.21.
+
+
+.. _v4l2-encoder-cmd:
+
+.. flat-table:: struct v4l2_encoder_cmd
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``cmd``
+
+ - The encoder command, see :ref:`encoder-cmds`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ - Flags to go with the command, see :ref:`encoder-flags`. If no
+ flags are defined for this command, drivers and applications must
+ set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``data``\ [8]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _encoder-cmds:
+
+.. flat-table:: Encoder Commands
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_CMD_START``
+
+ - 0
+
+ - Start the encoder. When the encoder is already running or paused,
+ this command does nothing. No flags are defined for this command.
+
+ - .. row 2
+
+ - ``V4L2_ENC_CMD_STOP``
+
+ - 1
+
+ - Stop the encoder. When the ``V4L2_ENC_CMD_STOP_AT_GOP_END`` flag
+ is set, encoding will continue until the end of the current *Group
+ Of Pictures*, otherwise encoding will stop immediately. When the
+ encoder is already stopped, this command does nothing. mem2mem
+ encoders will send a ``V4L2_EVENT_EOS`` event when the last frame
+ has been encoded and all frames are ready to be dequeued and will
+ set the ``V4L2_BUF_FLAG_LAST`` buffer flag on the last buffer of
+ the capture queue to indicate there will be no new buffers
+ produced to dequeue. This buffer may be empty, indicated by the
+ driver setting the ``bytesused`` field to 0. Once the
+ ``V4L2_BUF_FLAG_LAST`` flag was set, the
+ :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will not block anymore,
+ but return an ``EPIPE`` error code.
+
+ - .. row 3
+
+ - ``V4L2_ENC_CMD_PAUSE``
+
+ - 2
+
+ - Pause the encoder. When the encoder has not been started yet, the
+ driver will return an ``EPERM`` error code. When the encoder is
+ already paused, this command does nothing. No flags are defined
+ for this command.
+
+ - .. row 4
+
+ - ``V4L2_ENC_CMD_RESUME``
+
+ - 3
+
+ - Resume encoding after a PAUSE command. When the encoder has not
+ been started yet, the driver will return an ``EPERM`` error code. When
+ the encoder is already running, this command does nothing. No
+ flags are defined for this command.
+
+
+
+.. _encoder-flags:
+
+.. flat-table:: Encoder Command Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_CMD_STOP_AT_GOP_END``
+
+ - 0x0001
+
+ - Stop encoding at the end of the current *Group Of Pictures*,
+ rather than immediately.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``cmd`` field is invalid.
+
+EPERM
+ The application sent a PAUSE or RESUME command when the encoder was
+ not running.
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst
new file mode 100644
index 000000000000..f0dd0c4ca7d0
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst
@@ -0,0 +1,119 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_DV_TIMINGS:
+
+***********************************************************
+ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+***********************************************************
+
+Name
+====
+
+VIDIOC_ENUM_DV_TIMINGS - VIDIOC_SUBDEV_ENUM_DV_TIMINGS - Enumerate supported Digital Video timings
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enum_dv_timings *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+While some DV receivers or transmitters support a wide range of timings,
+others support only a limited number of timings. With this ioctl
+applications can enumerate a list of known supported timings. Call
+:ref:`VIDIOC_DV_TIMINGS_CAP` to check if it
+also supports other standards or even custom timings that are not in
+this list.
+
+To query the available timings, applications initialize the ``index``
+field, set the ``pad`` field to 0, zero the reserved array of struct
+:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` and call the
+``VIDIOC_ENUM_DV_TIMINGS`` ioctl on a video node with a pointer to this
+structure. Drivers fill the rest of the structure or return an ``EINVAL``
+error code when the index is out of bounds. To enumerate all supported
+DV timings, applications shall begin at index zero, incrementing by one
+until the driver returns ``EINVAL``. Note that drivers may enumerate a
+different set of DV timings after switching the video input or output.
+
+When implemented by the driver DV timings of subdevices can be queried
+by calling the ``VIDIOC_SUBDEV_ENUM_DV_TIMINGS`` ioctl directly on a
+subdevice node. The DV timings are specific to inputs (for DV receivers)
+or outputs (for DV transmitters), applications must specify the desired
+pad number in the struct
+:ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>` ``pad`` field.
+Attempts to enumerate timings on a pad that doesn't support them will
+return an ``EINVAL`` error code.
+
+
+.. _v4l2-enum-dv-timings:
+
+.. flat-table:: struct v4l2_enum_dv_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the DV timings, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API. This field is
+ only used when operating on a subdevice node. When operating on a
+ video node applications must set this field to zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
+
+ - ``timings``
+
+ - The timings.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_enum_dv_timings <v4l2-enum-dv-timings>`
+ ``index`` is out of bounds or the ``pad`` number is invalid.
+
+ENODATA
+ Digital video presets are not supported for this input or output.
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
new file mode 100644
index 000000000000..257c624e27be
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enum-fmt.rst
@@ -0,0 +1,164 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FMT:
+
+*********************
+ioctl VIDIOC_ENUM_FMT
+*********************
+
+Name
+====
+
+VIDIOC_ENUM_FMT - Enumerate image formats
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_fmtdesc *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FMT
+
+``argp``
+
+
+Description
+===========
+
+To enumerate image formats applications initialize the ``type`` and
+``index`` field of struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` and call
+the :ref:`VIDIOC_ENUM_FMT` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an ``EINVAL`` error code. All
+formats are enumerable by beginning at index zero and incrementing by
+one until ``EINVAL`` is returned.
+
+Note that after switching input or output the list of enumerated image
+formats may be different.
+
+
+.. _v4l2-fmtdesc:
+
+.. flat-table:: struct v4l2_fmtdesc
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+ This is in no way related to the ``pixelformat`` field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - See :ref:`fmtdesc-flags`
+
+ - .. row 4
+
+ - __u8
+
+ - ``description``\ [32]
+
+ - Description of the format, a NUL-terminated ASCII string. This
+ information is intended for the user, for example: "YUV 4:2:2".
+
+ - .. row 5
+
+ - __u32
+
+ - ``pixelformat``
+
+ - The image format identifier. This is a four character code as
+ computed by the v4l2_fourcc() macro:
+
+ - .. row 6
+
+ - :cspan:`2`
+
+
+ .. _v4l2-fourcc:
+ .. code-block:: c
+
+ #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
+
+ Several image formats are already defined by this specification in
+ :ref:`pixfmt`. Note these codes are not the same as those used
+ in the Windows world.
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _fmtdesc-flags:
+
+.. flat-table:: Image Format Description Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FMT_FLAG_COMPRESSED``
+
+ - 0x0001
+
+ - This is a compressed format.
+
+ - .. row 2
+
+ - ``V4L2_FMT_FLAG_EMULATED``
+
+ - 0x0002
+
+ - This format is not native to the device but emulated through
+ software (usually libv4l2), where possible try to use a native
+ format instead for better performance.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_fmtdesc <v4l2-fmtdesc>` ``type`` is not
+ supported or the ``index`` is out of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst
new file mode 100644
index 000000000000..5d5de535a0fe
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst
@@ -0,0 +1,274 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FRAMEINTERVALS:
+
+********************************
+ioctl VIDIOC_ENUM_FRAMEINTERVALS
+********************************
+
+Name
+====
+
+VIDIOC_ENUM_FRAMEINTERVALS - Enumerate frame intervals
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmivalenum *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FRAMEINTERVALS
+
+``argp``
+ Pointer to a struct :ref:`v4l2_frmivalenum <v4l2-frmivalenum>`
+ structure that contains a pixel format and size and receives a frame
+ interval.
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame intervals that the
+device supports for the given pixel format and frame size.
+
+The supported pixel formats and frame sizes can be obtained by using the
+:ref:`VIDIOC_ENUM_FMT` and
+:ref:`VIDIOC_ENUM_FRAMESIZES` functions.
+
+The return value and the content of the ``v4l2_frmivalenum.type`` field
+depend on the type of frame intervals the device supports. Here are the
+semantics of the function for the different cases:
+
+- **Discrete:** The function returns success if the given index value
+ (zero-based) is valid. The application should increase the index by
+ one for each call until ``EINVAL`` is returned. The
+ `v4l2_frmivalenum.type` field is set to
+ `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the union only
+ the `discrete` member is valid.
+
+- **Step-wise:** The function returns success if the given index value
+ is zero and ``EINVAL`` for any other index value. The
+ ``v4l2_frmivalenum.type`` field is set to
+ ``V4L2_FRMIVAL_TYPE_STEPWISE`` by the driver. Of the union only the
+ ``stepwise`` member is valid.
+
+- **Continuous:** This is a special case of the step-wise type above.
+ The function returns success if the given index value is zero and
+ ``EINVAL`` for any other index value. The ``v4l2_frmivalenum.type``
+ field is set to ``V4L2_FRMIVAL_TYPE_CONTINUOUS`` by the driver. Of
+ the union only the ``stepwise`` member is valid and the ``step``
+ value is set to 1.
+
+When the application calls the function with index zero, it must check
+the ``type`` field to determine the type of frame interval enumeration
+the device supports. Only for the ``V4L2_FRMIVAL_TYPE_DISCRETE`` type
+does it make sense to increase the index value to receive more frame
+intervals.
+
+Note that the order in which the frame intervals are returned has no
+special meaning. In particular does it not say anything about potential
+default frame intervals.
+
+Applications can assume that the enumeration data does not change
+without any interaction from the application itself. This means that the
+enumeration data is consistent if the application does not perform any
+other ioctl calls while it runs the frame interval enumeration.
+
+
+Notes
+=====
+
+- **Frame intervals and frame rates:** The V4L2 API uses frame
+ intervals instead of frame rates. Given the frame interval the frame
+ rate can be computed as follows:
+
+
+
+ ::
+
+ frame_rate = 1 / frame_interval
+
+
+Structs
+=======
+
+In the structs below, *IN* denotes a value that has to be filled in by
+the application, *OUT* denotes values that the driver fills in. The
+application should zero out all members except for the *IN* fields.
+
+
+.. _v4l2-frmival-stepwise:
+
+.. flat-table:: struct v4l2_frmival_stepwise
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``min``
+
+ - Minimum frame interval [s].
+
+ - .. row 2
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``max``
+
+ - Maximum frame interval [s].
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``step``
+
+ - Frame interval step size [s].
+
+
+
+.. _v4l2-frmivalenum:
+
+.. flat-table:: struct v4l2_frmivalenum
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - IN: Index of the given frame interval in the enumeration.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pixel_format``
+
+ -
+ - IN: Pixel format for which the frame intervals are enumerated.
+
+ - .. row 3
+
+ - __u32
+
+ - ``width``
+
+ -
+ - IN: Frame width for which the frame intervals are enumerated.
+
+ - .. row 4
+
+ - __u32
+
+ - ``height``
+
+ -
+ - IN: Frame height for which the frame intervals are enumerated.
+
+ - .. row 5
+
+ - __u32
+
+ - ``type``
+
+ -
+ - OUT: Frame interval type the device supports.
+
+ - .. row 6
+
+ - union
+
+ -
+ -
+ - OUT: Frame interval with the given index.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``discrete``
+
+ - Frame interval [s].
+
+ - .. row 8
+
+ -
+ - struct :ref:`v4l2_frmival_stepwise <v4l2-frmival-stepwise>`
+
+ - ``stepwise``
+
+ -
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved[2]``
+
+ -
+ - Reserved space for future use. Must be zeroed by drivers and
+ applications.
+
+
+
+Enums
+=====
+
+
+.. _v4l2-frmivaltypes:
+
+.. flat-table:: enum v4l2_frmivaltypes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FRMIVAL_TYPE_DISCRETE``
+
+ - 1
+
+ - Discrete frame interval.
+
+ - .. row 2
+
+ - ``V4L2_FRMIVAL_TYPE_CONTINUOUS``
+
+ - 2
+
+ - Continuous frame interval.
+
+ - .. row 3
+
+ - ``V4L2_FRMIVAL_TYPE_STEPWISE``
+
+ - 3
+
+ - Step-wise defined frame interval.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst
new file mode 100644
index 000000000000..d3b2e97df6c9
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst
@@ -0,0 +1,291 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FRAMESIZES:
+
+****************************
+ioctl VIDIOC_ENUM_FRAMESIZES
+****************************
+
+Name
+====
+
+VIDIOC_ENUM_FRAMESIZES - Enumerate frame sizes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frmsizeenum *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FRAMESIZES
+
+``argp``
+ Pointer to a struct :ref:`v4l2_frmsizeenum <v4l2-frmsizeenum>`
+ that contains an index and pixel format and receives a frame width
+ and height.
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame sizes (i. e. width
+and height in pixels) that the device supports for the given pixel
+format.
+
+The supported pixel formats can be obtained by using the
+:ref:`VIDIOC_ENUM_FMT` function.
+
+The return value and the content of the ``v4l2_frmsizeenum.type`` field
+depend on the type of frame sizes the device supports. Here are the
+semantics of the function for the different cases:
+
+- **Discrete:** The function returns success if the given index value
+ (zero-based) is valid. The application should increase the index by
+ one for each call until ``EINVAL`` is returned. The
+ ``v4l2_frmsizeenum.type`` field is set to
+ ``V4L2_FRMSIZE_TYPE_DISCRETE`` by the driver. Of the union only the
+ ``discrete`` member is valid.
+
+- **Step-wise:** The function returns success if the given index value
+ is zero and ``EINVAL`` for any other index value. The
+ ``v4l2_frmsizeenum.type`` field is set to
+ ``V4L2_FRMSIZE_TYPE_STEPWISE`` by the driver. Of the union only the
+ ``stepwise`` member is valid.
+
+- **Continuous:** This is a special case of the step-wise type above.
+ The function returns success if the given index value is zero and
+ ``EINVAL`` for any other index value. The ``v4l2_frmsizeenum.type``
+ field is set to ``V4L2_FRMSIZE_TYPE_CONTINUOUS`` by the driver. Of
+ the union only the ``stepwise`` member is valid and the
+ ``step_width`` and ``step_height`` values are set to 1.
+
+When the application calls the function with index zero, it must check
+the ``type`` field to determine the type of frame size enumeration the
+device supports. Only for the ``V4L2_FRMSIZE_TYPE_DISCRETE`` type does
+it make sense to increase the index value to receive more frame sizes.
+
+Note that the order in which the frame sizes are returned has no special
+meaning. In particular does it not say anything about potential default
+format sizes.
+
+Applications can assume that the enumeration data does not change
+without any interaction from the application itself. This means that the
+enumeration data is consistent if the application does not perform any
+other ioctl calls while it runs the frame size enumeration.
+
+
+Structs
+=======
+
+In the structs below, *IN* denotes a value that has to be filled in by
+the application, *OUT* denotes values that the driver fills in. The
+application should zero out all members except for the *IN* fields.
+
+
+.. _v4l2-frmsize-discrete:
+
+.. flat-table:: struct v4l2_frmsize_discrete
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Width of the frame [pixel].
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Height of the frame [pixel].
+
+
+
+.. _v4l2-frmsize-stepwise:
+
+.. flat-table:: struct v4l2_frmsize_stepwise
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum frame width [pixel].
+
+ - .. row 2
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum frame width [pixel].
+
+ - .. row 3
+
+ - __u32
+
+ - ``step_width``
+
+ - Frame width step size [pixel].
+
+ - .. row 4
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum frame height [pixel].
+
+ - .. row 5
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum frame height [pixel].
+
+ - .. row 6
+
+ - __u32
+
+ - ``step_height``
+
+ - Frame height step size [pixel].
+
+
+
+.. _v4l2-frmsizeenum:
+
+.. flat-table:: struct v4l2_frmsizeenum
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ -
+ - IN: Index of the given frame size in the enumeration.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pixel_format``
+
+ -
+ - IN: Pixel format for which the frame sizes are enumerated.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ -
+ - OUT: Frame size type the device supports.
+
+ - .. row 4
+
+ - union
+
+ -
+ -
+ - OUT: Frame size with the given index.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_frmsize_discrete <v4l2-frmsize-discrete>`
+
+ - ``discrete``
+
+ -
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_frmsize_stepwise <v4l2-frmsize-stepwise>`
+
+ - ``stepwise``
+
+ -
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved[2]``
+
+ -
+ - Reserved space for future use. Must be zeroed by drivers and
+ applications.
+
+
+
+Enums
+=====
+
+
+.. _v4l2-frmsizetypes:
+
+.. flat-table:: enum v4l2_frmsizetypes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FRMSIZE_TYPE_DISCRETE``
+
+ - 1
+
+ - Discrete frame size.
+
+ - .. row 2
+
+ - ``V4L2_FRMSIZE_TYPE_CONTINUOUS``
+
+ - 2
+
+ - Continuous frame size.
+
+ - .. row 3
+
+ - ``V4L2_FRMSIZE_TYPE_STEPWISE``
+
+ - 3
+
+ - Step-wise defined frame size.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst
new file mode 100644
index 000000000000..ea754f4f5532
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst
@@ -0,0 +1,190 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUM_FREQ_BANDS:
+
+****************************
+ioctl VIDIOC_ENUM_FREQ_BANDS
+****************************
+
+Name
+====
+
+VIDIOC_ENUM_FREQ_BANDS - Enumerate supported frequency bands
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency_band *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUM_FREQ_BANDS
+
+``argp``
+
+
+Description
+===========
+
+Enumerates the frequency bands that a tuner or modulator supports. To do
+this applications initialize the ``tuner``, ``type`` and ``index``
+fields, and zero out the ``reserved`` array of a struct
+:ref:`v4l2_frequency_band <v4l2-frequency-band>` and call the
+:ref:`VIDIOC_ENUM_FREQ_BANDS` ioctl with a pointer to this structure.
+
+This ioctl is supported if the ``V4L2_TUNER_CAP_FREQ_BANDS`` capability
+of the corresponding tuner/modulator is set.
+
+
+.. _v4l2-frequency-band:
+
+.. flat-table:: struct v4l2_frequency_band
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner or modulator index number. This is the same value as in
+ the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
+ the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
+ the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
+ and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
+ field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
+ set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
+ to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
+ ``V4L2_TUNER_RADIO`` for modulators (currently only radio
+ modulators are supported). See :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the frequency band, set by the application.
+
+ - .. row 4
+
+ - __u32
+
+ - ``capability``
+
+ - :cspan:`2` The tuner/modulator capability flags for this
+ frequency band, see :ref:`tuner-capability`. The
+ ``V4L2_TUNER_CAP_LOW`` or ``V4L2_TUNER_CAP_1HZ`` capability must
+ be the same for all frequency bands of the selected
+ tuner/modulator. So either all bands have that capability set, or
+ none of them have that capability.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangelow``
+
+ - :cspan:`2` The lowest tunable frequency in units of 62.5 kHz, or
+ if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
+ of 62.5 Hz, for this frequency band. A 1 Hz unit is used when the
+ ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangehigh``
+
+ - :cspan:`2` The highest tunable frequency in units of 62.5 kHz,
+ or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
+ units of 62.5 Hz, for this frequency band. A 1 Hz unit is used
+ when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 7
+
+ - __u32
+
+ - ``modulation``
+
+ - :cspan:`2` The supported modulation systems of this frequency
+ band. See :ref:`band-modulation`. Note that currently only one
+ modulation system per frequency band is supported. More work will
+ need to be done if multiple modulation systems are possible.
+ Contact the linux-media mailing list
+ (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+ if you need that functionality.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _band-modulation:
+
+.. flat-table:: Band Modulation Systems
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_BAND_MODULATION_VSB``
+
+ - 0x02
+
+ - Vestigial Sideband modulation, used for analog TV.
+
+ - .. row 2
+
+ - ``V4L2_BAND_MODULATION_FM``
+
+ - 0x04
+
+ - Frequency Modulation, commonly used for analog radio.
+
+ - .. row 3
+
+ - ``V4L2_BAND_MODULATION_AM``
+
+ - 0x08
+
+ - Amplitude Modulation, commonly used for analog radio.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``tuner`` or ``index`` is out of bounds or the ``type`` field is
+ wrong.
diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudio.rst b/Documentation/media/uapi/v4l/vidioc-enumaudio.rst
new file mode 100644
index 000000000000..bfdc3533240d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enumaudio.rst
@@ -0,0 +1,56 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMAUDIO:
+
+**********************
+ioctl VIDIOC_ENUMAUDIO
+**********************
+
+Name
+====
+
+VIDIOC_ENUMAUDIO - Enumerate audio inputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMAUDIO
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an audio input applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_audio <v4l2-audio>` and call the :ref:`VIDIOC_ENUMAUDIO`
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an ``EINVAL`` error code when the index is out of
+bounds. To enumerate all audio inputs applications shall begin at index
+zero, incrementing by one until the driver returns ``EINVAL``.
+
+See :ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` for a description of struct
+:ref:`v4l2_audio <v4l2-audio>`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the audio input is out of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst
new file mode 100644
index 000000000000..15bc5a40f4a6
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enumaudioout.rst
@@ -0,0 +1,59 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMAUDOUT:
+
+***********************
+ioctl VIDIOC_ENUMAUDOUT
+***********************
+
+Name
+====
+
+VIDIOC_ENUMAUDOUT - Enumerate audio outputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMAUDOUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of an audio output applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_audioout <v4l2-audioout>` and call the ``VIDIOC_G_AUDOUT``
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an ``EINVAL`` error code when the index is out of
+bounds. To enumerate all audio outputs applications shall begin at index
+zero, incrementing by one until the driver returns ``EINVAL``.
+
+Note connectors on a TV card to loop back the received audio signal to a
+sound card are not audio outputs in this sense.
+
+See :ref:`VIDIOC_G_AUDIOout <VIDIOC_G_AUDOUT>` for a description of struct
+:ref:`v4l2_audioout <v4l2-audioout>`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the audio output is out of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-enuminput.rst b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
new file mode 100644
index 000000000000..c1fc2e1f1d98
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enuminput.rst
@@ -0,0 +1,367 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMINPUT:
+
+**********************
+ioctl VIDIOC_ENUMINPUT
+**********************
+
+Name
+====
+
+VIDIOC_ENUMINPUT - Enumerate video inputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_input *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMINPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video input applications initialize the
+``index`` field of struct :ref:`v4l2_input <v4l2-input>` and call the
+:ref:`VIDIOC_ENUMINPUT` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an ``EINVAL`` error code when the
+index is out of bounds. To enumerate all inputs applications shall begin
+at index zero, incrementing by one until the driver returns ``EINVAL``.
+
+
+.. _v4l2-input:
+
+.. flat-table:: struct v4l2_input
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the input, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the video input, a NUL-terminated ASCII string, for
+ example: "Vin (Composite 2)". This information is intended for the
+ user, preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - Type of the input, see :ref:`input-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``audioset``
+
+ - Drivers can enumerate up to 32 video and audio inputs. This field
+ shows which audio inputs were selectable as audio source if this
+ was the currently selected video input. It is a bit mask. The LSB
+ corresponds to audio input 0, the MSB to input 31. Any number of
+ bits can be set, or none.
+
+ When the driver does not enumerate audio inputs no bits must be
+ set. Applications shall not interpret this as lack of audio
+ support. Some drivers automatically select audio sources and do
+ not enumerate them since there is no choice anyway.
+
+ For details on audio inputs and how to select the current input
+ see :ref:`audio`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``tuner``
+
+ - Capture devices can have zero or more tuners (RF demodulators).
+ When the ``type`` is set to ``V4L2_INPUT_TYPE_TUNER`` this is an
+ RF connector and this field identifies the tuner. It corresponds
+ to struct :ref:`v4l2_tuner <v4l2-tuner>` field ``index``. For
+ details on tuners see :ref:`tuner`.
+
+ - .. row 6
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``std``
+
+ - Every video input supports one or more different video standards.
+ This field is a set of all supported standards. For details on
+ video standards and how to switch see :ref:`standard`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``status``
+
+ - This field provides status information about the input. See
+ :ref:`input-status` for flags. With the exception of the sensor
+ orientation bits ``status`` is only valid when this is the current
+ input.
+
+ - .. row 8
+
+ - __u32
+
+ - ``capabilities``
+
+ - This field provides capabilities for the input. See
+ :ref:`input-capabilities` for flags.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _input-type:
+
+.. flat-table:: Input Types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_INPUT_TYPE_TUNER``
+
+ - 1
+
+ - This input uses a tuner (RF demodulator).
+
+ - .. row 2
+
+ - ``V4L2_INPUT_TYPE_CAMERA``
+
+ - 2
+
+ - Analog baseband input, for example CVBS / Composite Video,
+ S-Video, RGB.
+
+
+
+.. _input-status:
+
+.. flat-table:: Input Status Flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - :cspan:`2` General
+
+ - .. row 2
+
+ - ``V4L2_IN_ST_NO_POWER``
+
+ - 0x00000001
+
+ - Attached device is off.
+
+ - .. row 3
+
+ - ``V4L2_IN_ST_NO_SIGNAL``
+
+ - 0x00000002
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_IN_ST_NO_COLOR``
+
+ - 0x00000004
+
+ - The hardware supports color decoding, but does not detect color
+ modulation in the signal.
+
+ - .. row 5
+
+ - :cspan:`2` Sensor Orientation
+
+ - .. row 6
+
+ - ``V4L2_IN_ST_HFLIP``
+
+ - 0x00000010
+
+ - The input is connected to a device that produces a signal that is
+ flipped horizontally and does not correct this before passing the
+ signal to userspace.
+
+ - .. row 7
+
+ - ``V4L2_IN_ST_VFLIP``
+
+ - 0x00000020
+
+ - The input is connected to a device that produces a signal that is
+ flipped vertically and does not correct this before passing the
+ signal to userspace. Note that a 180 degree rotation is the same
+ as HFLIP | VFLIP
+
+ - .. row 8
+
+ - :cspan:`2` Analog Video
+
+ - .. row 9
+
+ - ``V4L2_IN_ST_NO_H_LOCK``
+
+ - 0x00000100
+
+ - No horizontal sync lock.
+
+ - .. row 10
+
+ - ``V4L2_IN_ST_COLOR_KILL``
+
+ - 0x00000200
+
+ - A color killer circuit automatically disables color decoding when
+ it detects no color modulation. When this flag is set the color
+ killer is enabled *and* has shut off color decoding.
+
+ - .. row 11
+
+ - :cspan:`2` Digital Video
+
+ - .. row 12
+
+ - ``V4L2_IN_ST_NO_SYNC``
+
+ - 0x00010000
+
+ - No synchronization lock.
+
+ - .. row 13
+
+ - ``V4L2_IN_ST_NO_EQU``
+
+ - 0x00020000
+
+ - No equalizer lock.
+
+ - .. row 14
+
+ - ``V4L2_IN_ST_NO_CARRIER``
+
+ - 0x00040000
+
+ - Carrier recovery failed.
+
+ - .. row 15
+
+ - :cspan:`2` VCR and Set-Top Box
+
+ - .. row 16
+
+ - ``V4L2_IN_ST_MACROVISION``
+
+ - 0x01000000
+
+ - Macrovision is an analog copy prevention system mangling the video
+ signal to confuse video recorders. When this flag is set
+ Macrovision has been detected.
+
+ - .. row 17
+
+ - ``V4L2_IN_ST_NO_ACCESS``
+
+ - 0x02000000
+
+ - Conditional access denied.
+
+ - .. row 18
+
+ - ``V4L2_IN_ST_VTR``
+
+ - 0x04000000
+
+ - VTR time constant. [?]
+
+
+
+.. _input-capabilities:
+
+.. flat-table:: Input capabilities
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_IN_CAP_DV_TIMINGS``
+
+ - 0x00000002
+
+ - This input supports setting video timings by using
+ VIDIOC_S_DV_TIMINGS.
+
+ - .. row 2
+
+ - ``V4L2_IN_CAP_STD``
+
+ - 0x00000004
+
+ - This input supports setting the TV standard by using
+ VIDIOC_S_STD.
+
+ - .. row 3
+
+ - ``V4L2_IN_CAP_NATIVE_SIZE``
+
+ - 0x00000008
+
+ - This input supports setting the native size using the
+ ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
+ :ref:`v4l2-selections-common`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_input <v4l2-input>` ``index`` is out of
+ bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-enumoutput.rst b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
new file mode 100644
index 000000000000..82fc9d3b237f
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enumoutput.rst
@@ -0,0 +1,222 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMOUTPUT:
+
+***********************
+ioctl VIDIOC_ENUMOUTPUT
+***********************
+
+Name
+====
+
+VIDIOC_ENUMOUTPUT - Enumerate video outputs
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_output *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMOUTPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video outputs applications initialize the
+``index`` field of struct :ref:`v4l2_output <v4l2-output>` and call
+the :ref:`VIDIOC_ENUMOUTPUT` ioctl with a pointer to this structure.
+Drivers fill the rest of the structure or return an ``EINVAL`` error code
+when the index is out of bounds. To enumerate all outputs applications
+shall begin at index zero, incrementing by one until the driver returns
+EINVAL.
+
+
+.. _v4l2-output:
+
+.. flat-table:: struct v4l2_output
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the output, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the video output, a NUL-terminated ASCII string, for
+ example: "Vout". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - Type of the output, see :ref:`output-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``audioset``
+
+ - Drivers can enumerate up to 32 video and audio outputs. This field
+ shows which audio outputs were selectable as the current output if
+ this was the currently selected video output. It is a bit mask.
+ The LSB corresponds to audio output 0, the MSB to output 31. Any
+ number of bits can be set, or none.
+
+ When the driver does not enumerate audio outputs no bits must be
+ set. Applications shall not interpret this as lack of audio
+ support. Drivers may automatically select audio outputs without
+ enumerating them.
+
+ For details on audio outputs and how to select the current output
+ see :ref:`audio`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``modulator``
+
+ - Output devices can have zero or more RF modulators. When the
+ ``type`` is ``V4L2_OUTPUT_TYPE_MODULATOR`` this is an RF connector
+ and this field identifies the modulator. It corresponds to struct
+ :ref:`v4l2_modulator <v4l2-modulator>` field ``index``. For
+ details on modulators see :ref:`tuner`.
+
+ - .. row 6
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``std``
+
+ - Every video output supports one or more different video standards.
+ This field is a set of all supported standards. For details on
+ video standards and how to switch see :ref:`standard`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``capabilities``
+
+ - This field provides capabilities for the output. See
+ :ref:`output-capabilities` for flags.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _output-type:
+
+.. flat-table:: Output Type
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_OUTPUT_TYPE_MODULATOR``
+
+ - 1
+
+ - This output is an analog TV modulator.
+
+ - .. row 2
+
+ - ``V4L2_OUTPUT_TYPE_ANALOG``
+
+ - 2
+
+ - Analog baseband output, for example Composite / CVBS, S-Video,
+ RGB.
+
+ - .. row 3
+
+ - ``V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY``
+
+ - 3
+
+ - [?]
+
+
+
+.. _output-capabilities:
+
+.. flat-table:: Output capabilities
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_OUT_CAP_DV_TIMINGS``
+
+ - 0x00000002
+
+ - This output supports setting video timings by using
+ VIDIOC_S_DV_TIMINGS.
+
+ - .. row 2
+
+ - ``V4L2_OUT_CAP_STD``
+
+ - 0x00000004
+
+ - This output supports setting the TV standard by using
+ VIDIOC_S_STD.
+
+ - .. row 3
+
+ - ``V4L2_OUT_CAP_NATIVE_SIZE``
+
+ - 0x00000008
+
+ - This output supports setting the native size using the
+ ``V4L2_SEL_TGT_NATIVE_SIZE`` selection target, see
+ :ref:`v4l2-selections-common`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_output <v4l2-output>` ``index`` is out of
+ bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-enumstd.rst b/Documentation/media/uapi/v4l/vidioc-enumstd.rst
new file mode 100644
index 000000000000..ce911c81bd3d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-enumstd.rst
@@ -0,0 +1,442 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_ENUMSTD:
+
+********************
+ioctl VIDIOC_ENUMSTD
+********************
+
+Name
+====
+
+VIDIOC_ENUMSTD - Enumerate supported video standards
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_standard *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_ENUMSTD
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a video standard, especially a custom (driver
+defined) one, applications initialize the ``index`` field of struct
+:ref:`v4l2_standard <v4l2-standard>` and call the :ref:`VIDIOC_ENUMSTD`
+ioctl with a pointer to this structure. Drivers fill the rest of the
+structure or return an ``EINVAL`` error code when the index is out of
+bounds. To enumerate all standards applications shall begin at index
+zero, incrementing by one until the driver returns ``EINVAL``. Drivers may
+enumerate a different set of standards after switching the video input
+or output. [1]_
+
+
+.. _v4l2-standard:
+
+.. flat-table:: struct v4l2_standard
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the video standard, set by the application.
+
+ - .. row 2
+
+ - :ref:`v4l2_std_id <v4l2-std-id>`
+
+ - ``id``
+
+ - The bits in this field identify the standard as one of the common
+ standards listed in :ref:`v4l2-std-id`, or if bits 32 to 63 are
+ set as custom standards. Multiple bits can be set if the hardware
+ does not distinguish between these standards, however separate
+ indices do not indicate the opposite. The ``id`` must be unique.
+ No other enumerated :ref:`struct v4l2_standard <v4l2-standard>` structure,
+ for this input or output anyway, can contain the same set of bits.
+
+ - .. row 3
+
+ - __u8
+
+ - ``name``\ [24]
+
+ - Name of the standard, a NUL-terminated ASCII string, for example:
+ "PAL-B/G", "NTSC Japan". This information is intended for the
+ user.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``frameperiod``
+
+ - The frame period (not field period) is numerator / denominator.
+ For example M/NTSC has a frame period of 1001 / 30000 seconds.
+
+ - .. row 5
+
+ - __u32
+
+ - ``framelines``
+
+ - Total lines per frame including blanking, e. g. 625 for B/PAL.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-fract:
+
+.. flat-table:: struct v4l2_fract
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``numerator``
+
+ -
+
+ - .. row 2
+
+ - __u32
+
+ - ``denominator``
+
+ -
+
+
+
+.. _v4l2-std-id:
+
+.. flat-table:: typedef v4l2_std_id
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``v4l2_std_id``
+
+ - This type is a set, each bit representing another video standard
+ as listed below and in :ref:`video-standards`. The 32 most
+ significant bits are reserved for custom (driver defined) video
+ standards.
+
+
+
+.. code-block:: c
+
+ #define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
+ #define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
+ #define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
+ #define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
+ #define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
+ #define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
+ #define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
+ #define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
+
+ #define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
+ #define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
+ #define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
+ #define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
+
+``V4L2_STD_PAL_60`` is a hybrid standard with 525 lines, 60 Hz refresh
+rate, and PAL color modulation with a 4.43 MHz color subcarrier. Some
+PAL video recorders can play back NTSC tapes in this mode for display on
+a 50/60 Hz agnostic PAL TV.
+
+
+.. code-block:: c
+
+ #define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
+ #define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
+ #define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
+
+``V4L2_STD_NTSC_443`` is a hybrid standard with 525 lines, 60 Hz refresh
+rate, and NTSC color modulation with a 4.43 MHz color subcarrier.
+
+
+.. code-block:: c
+
+ #define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
+
+ #define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
+ #define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
+ #define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
+ #define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
+ #define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
+ #define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
+ #define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
+ #define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
+
+ /* ATSC/HDTV */
+ #define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
+ #define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
+
+``V4L2_STD_ATSC_8_VSB`` and ``V4L2_STD_ATSC_16_VSB`` are U.S.
+terrestrial digital TV standards. Presently the V4L2 API does not
+support digital TV. See also the Linux DVB API at
+`https://linuxtv.org <https://linuxtv.org>`__.
+
+
+.. code-block:: c
+
+ #define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_PAL_G)
+ #define V4L2_STD_B (V4L2_STD_PAL_B |
+ V4L2_STD_PAL_B1 |
+ V4L2_STD_SECAM_B)
+ #define V4L2_STD_GH (V4L2_STD_PAL_G |
+ V4L2_STD_PAL_H |
+ V4L2_STD_SECAM_G |
+ V4L2_STD_SECAM_H)
+ #define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |
+ V4L2_STD_PAL_D1 |
+ V4L2_STD_PAL_K)
+ #define V4L2_STD_PAL (V4L2_STD_PAL_BG |
+ V4L2_STD_PAL_DK |
+ V4L2_STD_PAL_H |
+ V4L2_STD_PAL_I)
+ #define V4L2_STD_NTSC (V4L2_STD_NTSC_M |
+ V4L2_STD_NTSC_M_JP |
+ V4L2_STD_NTSC_M_KR)
+ #define V4L2_STD_MN (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_NTSC)
+ #define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |
+ V4L2_STD_SECAM_K |
+ V4L2_STD_SECAM_K1)
+ #define V4L2_STD_DK (V4L2_STD_PAL_DK |
+ V4L2_STD_SECAM_DK)
+
+ #define V4L2_STD_SECAM (V4L2_STD_SECAM_B |
+ V4L2_STD_SECAM_G |
+ V4L2_STD_SECAM_H |
+ V4L2_STD_SECAM_DK |
+ V4L2_STD_SECAM_L |
+ V4L2_STD_SECAM_LC)
+
+ #define V4L2_STD_525_60 (V4L2_STD_PAL_M |
+ V4L2_STD_PAL_60 |
+ V4L2_STD_NTSC |
+ V4L2_STD_NTSC_443)
+ #define V4L2_STD_625_50 (V4L2_STD_PAL |
+ V4L2_STD_PAL_N |
+ V4L2_STD_PAL_Nc |
+ V4L2_STD_SECAM)
+
+ #define V4L2_STD_UNKNOWN 0
+ #define V4L2_STD_ALL (V4L2_STD_525_60 |
+ V4L2_STD_625_50)
+
+
+.. _video-standards:
+
+.. flat-table:: Video Standards (based on [])
+ :header-rows: 1
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Characteristics
+
+ - M/NTSC [2]_
+
+ - M/PAL
+
+ - N/PAL [3]_
+
+ - B, B1, G/PAL
+
+ - D, D1, K/PAL
+
+ - H/PAL
+
+ - I/PAL
+
+ - B, G/SECAM
+
+ - D, K/SECAM
+
+ - K1/SECAM
+
+ - L/SECAM
+
+ - .. row 2
+
+ - Frame lines
+
+ - :cspan:`1` 525
+
+ - :cspan:`9` 625
+
+ - .. row 3
+
+ - Frame period (s)
+
+ - :cspan:`1` 1001/30000
+
+ - :cspan:`9` 1/25
+
+ - .. row 4
+
+ - Chrominance sub-carrier frequency (Hz)
+
+ - 3579545 ± 10
+
+ - 3579611.49 ± 10
+
+ - 4433618.75 ± 5 (3582056.25 ± 5)
+
+ - :cspan:`3` 4433618.75 ± 5
+
+ - 4433618.75 ± 1
+
+ - :cspan:`3` f\ :sub:`OR` = 4406250 ± 2000, f\ :sub:`OB` = 4250000
+ ± 2000
+
+ - .. row 5
+
+ - Nominal radio-frequency channel bandwidth (MHz)
+
+ - 6
+
+ - 6
+
+ - 6
+
+ - B: 7; B1, G: 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - 8
+
+ - .. row 6
+
+ - Sound carrier relative to vision carrier (MHz)
+
+ - + 4.5
+
+ - + 4.5
+
+ - + 4.5
+
+ - + 5.5 ± 0.001 [4]_ [5]_ [6]_ [7]_
+
+ - + 6.5 ± 0.001
+
+ - + 5.5
+
+ - + 5.9996 ± 0.0005
+
+ - + 5.5 ± 0.001
+
+ - + 6.5 ± 0.001
+
+ - + 6.5
+
+ - + 6.5 [8]_
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_standard <v4l2-standard>` ``index`` is out
+ of bounds.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
+
+.. [1]
+ The supported standards may overlap and we need an unambiguous set to
+ find the current standard returned by :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`.
+
+.. [2]
+ Japan uses a standard similar to M/NTSC (V4L2_STD_NTSC_M_JP).
+
+.. [3]
+ The values in brackets apply to the combination N/PAL a.k.a.
+ N\ :sub:`C` used in Argentina (V4L2_STD_PAL_Nc).
+
+.. [4]
+ In the Federal Republic of Germany, Austria, Italy, the Netherlands,
+ Slovakia and Switzerland a system of two sound carriers is used, the
+ frequency of the second carrier being 242.1875 kHz above the
+ frequency of the first sound carrier. For stereophonic sound
+ transmissions a similar system is used in Australia.
+
+.. [5]
+ New Zealand uses a sound carrier displaced 5.4996 ± 0.0005 MHz from
+ the vision carrier.
+
+.. [6]
+ In Denmark, Finland, New Zealand, Sweden and Spain a system of two
+ sound carriers is used. In Iceland, Norway and Poland the same system
+ is being introduced. The second carrier is 5.85 MHz above the vision
+ carrier and is DQPSK modulated with 728 kbit/s sound and data
+ multiplex. (NICAM system)
+
+.. [7]
+ In the United Kingdom, a system of two sound carriers is used. The
+ second sound carrier is 6.552 MHz above the vision carrier and is
+ DQPSK modulated with a 728 kbit/s sound and data multiplex able to
+ carry two sound channels. (NICAM system)
+
+.. [8]
+ In France, a digital carrier 5.85 MHz away from the vision carrier
+ may be used in addition to the main sound carrier. It is modulated in
+ differentially encoded QPSK with a 728 kbit/s sound and data
+ multiplexer capable of carrying two sound channels. (NICAM system)
diff --git a/Documentation/media/uapi/v4l/vidioc-expbuf.rst b/Documentation/media/uapi/v4l/vidioc-expbuf.rst
new file mode 100644
index 000000000000..ded708e647fa
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-expbuf.rst
@@ -0,0 +1,197 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_EXPBUF:
+
+*******************
+ioctl VIDIOC_EXPBUF
+*******************
+
+Name
+====
+
+VIDIOC_EXPBUF - Export a buffer as a DMABUF file descriptor.
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_exportbuffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_EXPBUF
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is an extension to the :ref:`memory mapping <mmap>` I/O
+method, therefore it is available only for ``V4L2_MEMORY_MMAP`` buffers.
+It can be used to export a buffer as a DMABUF file at any time after
+buffers have been allocated with the
+:ref:`VIDIOC_REQBUFS` ioctl.
+
+To export a buffer, applications fill struct
+:ref:`v4l2_exportbuffer <v4l2-exportbuffer>`. The ``type`` field is
+set to the same buffer type as was previously used with struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+Applications must also set the ``index`` field. Valid index numbers
+range from zero to the number of buffers allocated with
+:ref:`VIDIOC_REQBUFS` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. For the multi-planar API, applications set the ``plane`` field to
+the index of the plane to be exported. Valid planes range from zero to
+the maximal number of valid planes for the currently active format. For
+the single-planar API, applications must set ``plane`` to zero.
+Additional flags may be posted in the ``flags`` field. Refer to a manual
+for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY,
+and O_RDWR are supported. All other fields must be set to zero. In the
+case of multi-planar API, every plane is exported separately using
+multiple :ref:`VIDIOC_EXPBUF` calls.
+
+After calling :ref:`VIDIOC_EXPBUF` the ``fd`` field will be set by a
+driver. This is a DMABUF file descriptor. The application may pass it to
+other DMABUF-aware devices. Refer to :ref:`DMABUF importing <dmabuf>`
+for details about importing DMABUF files into V4L2 nodes. It is
+recommended to close a DMABUF file when it is no longer used to allow
+the associated memory to be reclaimed.
+
+
+Examples
+========
+
+
+.. code-block:: c
+
+ int buffer_export(int v4lfd, enum v4l2_buf_type bt, int index, int *dmafd)
+ {
+ struct v4l2_exportbuffer expbuf;
+
+ memset(&expbuf, 0, sizeof(expbuf));
+ expbuf.type = bt;
+ expbuf.index = index;
+ if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
+ perror("VIDIOC_EXPBUF");
+ return -1;
+ }
+
+ *dmafd = expbuf.fd;
+
+ return 0;
+ }
+
+
+.. code-block:: c
+
+ int buffer_export_mp(int v4lfd, enum v4l2_buf_type bt, int index,
+ int dmafd[], int n_planes)
+ {
+ int i;
+
+ for (i = 0; i < n_planes; ++i) {
+ struct v4l2_exportbuffer expbuf;
+
+ memset(&expbuf, 0, sizeof(expbuf));
+ expbuf.type = bt;
+ expbuf.index = index;
+ expbuf.plane = i;
+ if (ioctl(v4lfd, VIDIOC_EXPBUF, &expbuf) == -1) {
+ perror("VIDIOC_EXPBUF");
+ while (i)
+ close(dmafd[--i]);
+ return -1;
+ }
+ dmafd[i] = expbuf.fd;
+ }
+
+ return 0;
+ }
+
+
+.. _v4l2-exportbuffer:
+
+.. flat-table:: struct v4l2_exportbuffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the buffer, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` or struct
+ :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``, set
+ by the application. See :ref:`v4l2-buf-type`
+
+ - .. row 2
+
+ - __u32
+
+ - ``index``
+
+ - Number of the buffer, set by the application. This field is only
+ used for :ref:`memory mapping <mmap>` I/O and can range from
+ zero to the number of buffers allocated with the
+ :ref:`VIDIOC_REQBUFS` and/or
+ :ref:`VIDIOC_CREATE_BUFS` ioctls.
+
+ - .. row 3
+
+ - __u32
+
+ - ``plane``
+
+ - Index of the plane to be exported when using the multi-planar API.
+ Otherwise this value must be set to zero.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags for the newly created file, currently only ``O_CLOEXEC``,
+ ``O_RDONLY``, ``O_WRONLY``, and ``O_RDWR`` are supported, refer to
+ the manual of open() for more details.
+
+ - .. row 5
+
+ - __s32
+
+ - ``fd``
+
+ - The DMABUF file descriptor associated with a buffer. Set by the
+ driver.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved[11]``
+
+ - Reserved field for future use. Drivers and applications must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ A queue is not in MMAP mode or DMABUF exporting is not supported or
+ ``flags`` or ``type`` or ``index`` or ``plane`` fields are invalid.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-audio.rst b/Documentation/media/uapi/v4l/vidioc-g-audio.rst
new file mode 100644
index 000000000000..cccbcdb8c463
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-audio.rst
@@ -0,0 +1,162 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_AUDIO:
+
+************************************
+ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
+************************************
+
+Name
+====
+
+VIDIOC_G_AUDIO - VIDIOC_S_AUDIO - Query or select the current audio input and its attributes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audio *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audio *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_AUDIO, VIDIOC_S_AUDIO
+
+``argp``
+
+
+Description
+===========
+
+To query the current audio input applications zero out the ``reserved``
+array of a struct :ref:`v4l2_audio <v4l2-audio>` and call the
+:ref:`VIDIOC_G_AUDIO <VIDIOC_G_AUDIO>` ioctl with a pointer to this structure. Drivers fill
+the rest of the structure or return an ``EINVAL`` error code when the device
+has no audio inputs, or none which combine with the current video input.
+
+Audio inputs have one writable property, the audio mode. To select the
+current audio input *and* change the audio mode, applications initialize
+the ``index`` and ``mode`` fields, and the ``reserved`` array of a
+:ref:`struct v4l2_audio <v4l2-audio>` structure and call the :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>`
+ioctl. Drivers may switch to a different audio mode if the request
+cannot be satisfied. However, this is a write-only ioctl, it does not
+return the actual new audio mode.
+
+
+.. _v4l2-audio:
+
+.. flat-table:: struct v4l2_audio
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the audio input, set by the driver or application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the audio input, a NUL-terminated ASCII string, for
+ example: "Line In". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Audio capability flags, see :ref:`audio-capability`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``mode``
+
+ - Audio mode flags set by drivers and applications (on
+ :ref:`VIDIOC_S_AUDIO <VIDIOC_G_AUDIO>` ioctl), see :ref:`audio-mode`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _audio-capability:
+
+.. flat-table:: Audio Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_AUDCAP_STEREO``
+
+ - 0x00001
+
+ - This is a stereo input. The flag is intended to automatically
+ disable stereo recording etc. when the signal is always monaural.
+ The API provides no means to detect if stereo is *received*,
+ unless the audio input belongs to a tuner.
+
+ - .. row 2
+
+ - ``V4L2_AUDCAP_AVL``
+
+ - 0x00002
+
+ - Automatic Volume Level mode is supported.
+
+
+
+.. _audio-mode:
+
+.. flat-table:: Audio Mode Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_AUDMODE_AVL``
+
+ - 0x00001
+
+ - AVL mode is on.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ No audio inputs combine with the current video input, or the number
+ of the selected audio input is out of bounds or it does not combine.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-audioout.rst b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst
new file mode 100644
index 000000000000..bee5f78ed7c1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-audioout.rst
@@ -0,0 +1,122 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_AUDOUT:
+
+**************************************
+ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
+**************************************
+
+Name
+====
+
+VIDIOC_G_AUDOUT - VIDIOC_S_AUDOUT - Query or select the current audio output
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_audioout *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_audioout *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current audio output applications zero out the ``reserved``
+array of a struct :ref:`v4l2_audioout <v4l2-audioout>` and call the
+``VIDIOC_G_AUDOUT`` ioctl with a pointer to this structure. Drivers fill
+the rest of the structure or return an ``EINVAL`` error code when the device
+has no audio inputs, or none which combine with the current video
+output.
+
+Audio outputs have no writable properties. Nevertheless, to select the
+current audio output applications can initialize the ``index`` field and
+``reserved`` array (which in the future may contain writable properties)
+of a :ref:`struct v4l2_audioout <v4l2-audioout>` structure and call the
+``VIDIOC_S_AUDOUT`` ioctl. Drivers switch to the requested output or
+return the ``EINVAL`` error code when the index is out of bounds. This is a
+write-only ioctl, it does not return the current audio output attributes
+as ``VIDIOC_G_AUDOUT`` does.
+
+Note connectors on a TV card to loop back the received audio signal to a
+sound card are not audio outputs in this sense.
+
+
+.. _v4l2-audioout:
+
+.. flat-table:: struct v4l2_audioout
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the audio output, set by the driver or application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the audio output, a NUL-terminated ASCII string, for
+ example: "Line Out". This information is intended for the user,
+ preferably the connector label on the device itself.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Audio capability flags, none defined yet. Drivers must set this
+ field to zero.
+
+ - .. row 4
+
+ - __u32
+
+ - ``mode``
+
+ - Audio mode, none defined yet. Drivers and applications (on
+ ``VIDIOC_S_AUDOUT``) must set this field to zero.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ No audio outputs combine with the current video output, or the
+ number of the selected audio output is out of bounds or it does not
+ combine.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-g-crop.rst
new file mode 100644
index 000000000000..6cf76497937c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-crop.rst
@@ -0,0 +1,113 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_CROP:
+
+**********************************
+ioctl VIDIOC_G_CROP, VIDIOC_S_CROP
+**********************************
+
+Name
+====
+
+VIDIOC_G_CROP - VIDIOC_S_CROP - Get or set the current cropping rectangle
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_crop *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_crop *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_CROP, VIDIOC_S_CROP
+
+``argp``
+
+
+Description
+===========
+
+To query the cropping rectangle size and position applications set the
+``type`` field of a :ref:`struct v4l2_crop <v4l2-crop>` structure to the
+respective buffer (stream) type and call the :ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` ioctl
+with a pointer to this structure. The driver fills the rest of the
+structure or returns the ``EINVAL`` error code if cropping is not supported.
+
+To change the cropping rectangle applications initialize the ``type``
+and struct :ref:`v4l2_rect <v4l2-rect>` substructure named ``c`` of a
+v4l2_crop structure and call the :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` ioctl with a pointer
+to this structure.
+
+Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``.
+
+The driver first adjusts the requested dimensions against hardware
+limits, i. e. the bounds given by the capture/output window, and it
+rounds to the closest possible values of horizontal and vertical offset,
+width and height. In particular the driver must round the vertical
+offset of the cropping rectangle to frame lines modulo two, such that
+the field order cannot be confused.
+
+Second the driver adjusts the image size (the opposite rectangle of the
+scaling process, source or target depending on the data direction) to
+the closest size possible while maintaining the current horizontal and
+vertical scaling factor.
+
+Finally the driver programs the hardware with the actual cropping and
+image parameters. :ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` is a write-only ioctl, it does not
+return the actual parameters. To query them applications must call
+:ref:`VIDIOC_G_CROP <VIDIOC_G_CROP>` and :ref:`VIDIOC_G_FMT`. When the
+parameters are unsuitable the application may modify the cropping or
+image parameters and repeat the cycle until satisfactory parameters have
+been negotiated.
+
+When cropping is not supported then no parameters are changed and
+:ref:`VIDIOC_S_CROP <VIDIOC_G_CROP>` returns the ``EINVAL`` error code.
+
+
+.. _v4l2-crop:
+
+.. flat-table:: struct v4l2_crop
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, set by the application. Only these types
+ are valid here: ``V4L2_BUF_TYPE_VIDEO_CAPTURE``,
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` and
+ ``V4L2_BUF_TYPE_VIDEO_OVERLAY``. See :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``c``
+
+ - Cropping rectangle. The same co-ordinate system as for struct
+ :ref:`v4l2_cropcap <v4l2-cropcap>` ``bounds`` is used.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst b/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst
new file mode 100644
index 000000000000..ee929f692ebe
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-ctrl.rst
@@ -0,0 +1,105 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_CTRL:
+
+**********************************
+ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL
+**********************************
+
+Name
+====
+
+VIDIOC_G_CTRL - VIDIOC_S_CTRL - Get or set the value of a control
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_control *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_CTRL, VIDIOC_S_CTRL
+
+``argp``
+
+
+Description
+===========
+
+To get the current value of a control applications initialize the ``id``
+field of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
+:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl with a pointer to this structure. To change the
+value of a control applications initialize the ``id`` and ``value``
+fields of a struct :ref:`struct v4l2_control <v4l2-control>` and call the
+:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` ioctl.
+
+When the ``id`` is invalid drivers return an ``EINVAL`` error code. When the
+``value`` is out of bounds drivers can choose to take the closest valid
+value or return an ``ERANGE`` error code, whatever seems more appropriate.
+However, :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` is a write-only ioctl, it does not return the
+actual new value. If the ``value`` is inappropriate for the control
+(e.g. if it refers to an unsupported menu index of a menu control), then
+EINVAL error code is returned as well.
+
+These ioctls work only with user controls. For other control classes the
+:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`,
+:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` or
+:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` must be used.
+
+
+.. _v4l2-control:
+
+.. flat-table:: struct v4l2_control
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application.
+
+ - .. row 2
+
+ - __s32
+
+ - ``value``
+
+ - New value or current value.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_control <v4l2-control>` ``id`` is invalid
+ or the ``value`` is inappropriate for the given control (i.e. if a
+ menu item is selected that is not supported by the driver according
+ to :ref:`VIDIOC_QUERYMENU <VIDIOC_QUERYCTRL>`).
+
+ERANGE
+ The struct :ref:`v4l2_control <v4l2-control>` ``value`` is out of
+ bounds.
+
+EBUSY
+ The control is temporarily not changeable, possibly because another
+ applications took over control of the device function this control
+ belongs to.
+
+EACCES
+ Attempt to set a read-only control or to get a write-only control.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
new file mode 100644
index 000000000000..e19d64e0116a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst
@@ -0,0 +1,417 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_DV_TIMINGS:
+
+**********************************************
+ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
+**********************************************
+
+Name
+====
+
+VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS,
+ VIDIOC_SUBDEV_G_DV_TIMINGS, VIDIOC_SUBDEV_S_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+To set DV timings for the input or output, applications use the
+:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings,
+applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing
+information is filled in using the structure struct
+:ref:`v4l2_dv_timings <v4l2-dv-timings>`. These ioctls take a
+pointer to the struct :ref:`v4l2_dv_timings <v4l2-dv-timings>`
+structure as argument. If the ioctl is not supported or the timing
+values are not correct, the driver returns ``EINVAL`` error code.
+
+The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
+the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
+the current input or output does not support DV timings (e.g. if
+:ref:`VIDIOC_ENUMINPUT` does not set the
+``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`
+ parameter was unsuitable.
+
+ENODATA
+ Digital video timings are not supported for this input or output.
+
+EBUSY
+ The device is busy and therefore can not change the timings.
+
+
+.. _v4l2-bt-timings:
+
+.. flat-table:: struct v4l2_bt_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``width``
+
+ - Width of the active video in pixels.
+
+ - .. row 2
+
+ - __u32
+
+ - ``height``
+
+ - Height of the active video frame in lines. So for interlaced
+ formats the height of the active video in each field is
+ ``height``/2.
+
+ - .. row 3
+
+ - __u32
+
+ - ``interlaced``
+
+ - Progressive (0) or interlaced (1)
+
+ - .. row 4
+
+ - __u32
+
+ - ``polarities``
+
+ - This is a bit mask that defines polarities of sync signals. bit 0
+ (``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
+ 1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
+ the bit is set (1) it is positive polarity and if is cleared (0),
+ it is negative polarity.
+
+ - .. row 5
+
+ - __u64
+
+ - ``pixelclock``
+
+ - Pixel clock in Hz. Ex. 74.25MHz->74250000
+
+ - .. row 6
+
+ - __u32
+
+ - ``hfrontporch``
+
+ - Horizontal front porch in pixels
+
+ - .. row 7
+
+ - __u32
+
+ - ``hsync``
+
+ - Horizontal sync length in pixels
+
+ - .. row 8
+
+ - __u32
+
+ - ``hbackporch``
+
+ - Horizontal back porch in pixels
+
+ - .. row 9
+
+ - __u32
+
+ - ``vfrontporch``
+
+ - Vertical front porch in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 10
+
+ - __u32
+
+ - ``vsync``
+
+ - Vertical sync length in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 11
+
+ - __u32
+
+ - ``vbackporch``
+
+ - Vertical back porch in lines. For interlaced formats this refers
+ to the odd field (aka field 1).
+
+ - .. row 12
+
+ - __u32
+
+ - ``il_vfrontporch``
+
+ - Vertical front porch in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 13
+
+ - __u32
+
+ - ``il_vsync``
+
+ - Vertical sync length in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 14
+
+ - __u32
+
+ - ``il_vbackporch``
+
+ - Vertical back porch in lines for the even field (aka field 2) of
+ interlaced field formats. Must be 0 for progressive formats.
+
+ - .. row 15
+
+ - __u32
+
+ - ``standards``
+
+ - The video standard(s) this format belongs to. This will be filled
+ in by the driver. Applications must set this to 0. See
+ :ref:`dv-bt-standards` for a list of standards.
+
+ - .. row 16
+
+ - __u32
+
+ - ``flags``
+
+ - Several flags giving more information about the format. See
+ :ref:`dv-bt-flags` for a description of the flags.
+
+
+
+.. _v4l2-dv-timings:
+
+.. flat-table:: struct v4l2_dv_timings
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of DV timings as listed in :ref:`dv-timing-types`.
+
+ - .. row 2
+
+ - union
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_bt_timings <v4l2-bt-timings>`
+
+ - ``bt``
+
+ - Timings defined by BT.656/1120 specifications
+
+ - .. row 4
+
+ -
+ - __u32
+
+ - ``reserved``\ [32]
+
+ -
+
+
+
+.. _dv-timing-types:
+
+.. flat-table:: DV Timing types
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - Timing type
+
+ - value
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_BT_656_1120``
+
+ - 0
+
+ - BT.656/1120 timings
+
+
+
+.. _dv-bt-standards:
+
+.. flat-table:: DV BT Timing standards
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Timing standard
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_BT_STD_CEA861``
+
+ - The timings follow the CEA-861 Digital TV Profile standard
+
+ - .. row 4
+
+ - ``V4L2_DV_BT_STD_DMT``
+
+ - The timings follow the VESA Discrete Monitor Timings standard
+
+ - .. row 5
+
+ - ``V4L2_DV_BT_STD_CVT``
+
+ - The timings follow the VESA Coordinated Video Timings standard
+
+ - .. row 6
+
+ - ``V4L2_DV_BT_STD_GTF``
+
+ - The timings follow the VESA Generalized Timings Formula standard
+
+
+
+.. _dv-bt-flags:
+
+.. flat-table:: DV BT Timing flags
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - Flag
+
+ - Description
+
+ - .. row 2
+
+ -
+ -
+
+ - .. row 3
+
+ - ``V4L2_DV_FL_REDUCED_BLANKING``
+
+ - CVT/GTF specific: the timings use reduced blanking (CVT) or the
+ 'Secondary GTF' curve (GTF). In both cases the horizontal and/or
+ vertical blanking intervals are reduced, allowing a higher
+ resolution over the same bandwidth. This is a read-only flag,
+ applications must not set this.
+
+ - .. row 4
+
+ - ``V4L2_DV_FL_CAN_REDUCE_FPS``
+
+ - CEA-861 specific: set for CEA-861 formats with a framerate that is
+ a multiple of six. These formats can be optionally played at 1 /
+ 1.001 speed to be compatible with 60 Hz based standards such as
+ NTSC and PAL-M that use a framerate of 29.97 frames per second. If
+ the transmitter can't generate such frequencies, then the flag
+ will also be cleared. This is a read-only flag, applications must
+ not set this.
+
+ - .. row 5
+
+ - ``V4L2_DV_FL_REDUCED_FPS``
+
+ - CEA-861 specific: only valid for video transmitters, the flag is
+ cleared by receivers. It is also only valid for formats with the
+ ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other formats the
+ flag will be cleared by the driver. If the application sets this
+ flag, then the pixelclock used to set up the transmitter is
+ divided by 1.001 to make it compatible with NTSC framerates. If
+ the transmitter can't generate such frequencies, then the flag
+ will also be cleared.
+
+ - .. row 6
+
+ - ``V4L2_DV_FL_HALF_LINE``
+
+ - Specific to interlaced formats: if set, then the vertical
+ frontporch of field 1 (aka the odd field) is really one half-line
+ longer and the vertical backporch of field 2 (aka the even field)
+ is really one half-line shorter, so each field has exactly the
+ same number of half-lines. Whether half-lines can be detected or
+ used depends on the hardware.
+
+ - .. row 7
+
+ - ``V4L2_DV_FL_IS_CE_VIDEO``
+
+ - If set, then this is a Consumer Electronics (CE) video format.
+ Such formats differ from other formats (commonly called IT
+ formats) in that if R'G'B' encoding is used then by default the
+ R'G'B' values use limited range (i.e. 16-235) as opposed to full
+ range (i.e. 0-255). All formats defined in CEA-861 except for the
+ 640x480p59.94 format are CE formats.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-edid.rst b/Documentation/media/uapi/v4l/vidioc-g-edid.rst
new file mode 100644
index 000000000000..907b2c1764a3
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-edid.rst
@@ -0,0 +1,158 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_EDID:
+
+******************************************************************************
+ioctl VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID
+******************************************************************************
+
+Name
+====
+
+VIDIOC_G_EDID - VIDIOC_S_EDID - VIDIOC_SUBDEV_G_EDID - VIDIOC_SUBDEV_S_EDID - Get or set the EDID of a video receiver/transmitter
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_edid *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_EDID, VIDIOC_S_EDID, VIDIOC_SUBDEV_G_EDID,
+ VIDIOC_SUBDEV_S_EDID
+
+``argp``
+
+
+Description
+===========
+
+These ioctls can be used to get or set an EDID associated with an input
+from a receiver or an output of a transmitter device. They can be used
+with subdevice nodes (/dev/v4l-subdevX) or with video nodes
+(/dev/videoX).
+
+When used with video nodes the ``pad`` field represents the input (for
+video capture devices) or output (for video output devices) index as is
+returned by :ref:`VIDIOC_ENUMINPUT` and
+:ref:`VIDIOC_ENUMOUTPUT` respectively. When used
+with subdevice nodes the ``pad`` field represents the input or output
+pad of the subdevice. If there is no EDID support for the given ``pad``
+value, then the ``EINVAL`` error code will be returned.
+
+To get the EDID data the application has to fill in the ``pad``,
+``start_block``, ``blocks`` and ``edid`` fields, zero the ``reserved``
+array and call :ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>`. The current EDID from block
+``start_block`` and of size ``blocks`` will be placed in the memory
+``edid`` points to. The ``edid`` pointer must point to memory at least
+``blocks`` * 128 bytes large (the size of one block is 128 bytes).
+
+If there are fewer blocks than specified, then the driver will set
+``blocks`` to the actual number of blocks. If there are no EDID blocks
+available at all, then the error code ``ENODATA`` is set.
+
+If blocks have to be retrieved from the sink, then this call will block
+until they have been read.
+
+If ``start_block`` and ``blocks`` are both set to 0 when
+:ref:`VIDIOC_G_EDID <VIDIOC_G_EDID>` is called, then the driver will set ``blocks`` to the
+total number of available EDID blocks and it will return 0 without
+copying any data. This is an easy way to discover how many EDID blocks
+there are. Note that if there are no EDID blocks available at all, then
+the driver will set ``blocks`` to 0 and it returns 0.
+
+To set the EDID blocks of a receiver the application has to fill in the
+``pad``, ``blocks`` and ``edid`` fields, set ``start_block`` to 0 and
+zero the ``reserved`` array. It is not possible to set part of an EDID,
+it is always all or nothing. Setting the EDID data is only valid for
+receivers as it makes no sense for a transmitter.
+
+The driver assumes that the full EDID is passed in. If there are more
+EDID blocks than the hardware can handle then the EDID is not written,
+but instead the error code ``E2BIG`` is set and ``blocks`` is set to the
+maximum that the hardware supports. If ``start_block`` is any value
+other than 0 then the error code ``EINVAL`` is set.
+
+To disable an EDID you set ``blocks`` to 0. Depending on the hardware
+this will drive the hotplug pin low and/or block the source from reading
+the EDID data in some way. In any case, the end result is the same: the
+EDID is no longer available.
+
+
+.. _v4l2-edid:
+
+.. flat-table:: struct v4l2_edid
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad for which to get/set the EDID blocks. When used with a video
+ device node the pad represents the input or output index as
+ returned by :ref:`VIDIOC_ENUMINPUT` and
+ :ref:`VIDIOC_ENUMOUTPUT` respectively.
+
+ - .. row 2
+
+ - __u32
+
+ - ``start_block``
+
+ - Read the EDID from starting with this block. Must be 0 when
+ setting the EDID.
+
+ - .. row 3
+
+ - __u32
+
+ - ``blocks``
+
+ - The number of blocks to get or set. Must be less or equal to 256
+ (the maximum number of blocks as defined by the standard). When
+ you set the EDID and ``blocks`` is 0, then the EDID is disabled or
+ erased.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+ - .. row 5
+
+ - __u8 *
+
+ - ``edid``
+
+ - Pointer to memory that contains the EDID. The minimum size is
+ ``blocks`` * 128.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+``ENODATA``
+ The EDID data is not available.
+
+``E2BIG``
+ The EDID data you provided is more than the hardware can handle.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst b/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst
new file mode 100644
index 000000000000..f0f41ac56b80
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-enc-index.rst
@@ -0,0 +1,210 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_ENC_INDEX:
+
+************************
+ioctl VIDIOC_G_ENC_INDEX
+************************
+
+Name
+====
+
+VIDIOC_G_ENC_INDEX - Get meta data about a compressed video stream
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_enc_idx *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_ENC_INDEX
+
+``argp``
+
+
+Description
+===========
+
+The :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` ioctl provides meta data about a compressed
+video stream the same or another application currently reads from the
+driver, which is useful for random access into the stream without
+decoding it.
+
+To read the data applications must call :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` with a
+pointer to a struct :ref:`v4l2_enc_idx <v4l2-enc-idx>`. On success
+the driver fills the ``entry`` array, stores the number of elements
+written in the ``entries`` field, and initializes the ``entries_cap``
+field.
+
+Each element of the ``entry`` array contains meta data about one
+picture. A :ref:`VIDIOC_G_ENC_INDEX <VIDIOC_G_ENC_INDEX>` call reads up to
+``V4L2_ENC_IDX_ENTRIES`` entries from a driver buffer, which can hold up
+to ``entries_cap`` entries. This number can be lower or higher than
+``V4L2_ENC_IDX_ENTRIES``, but not zero. When the application fails to
+read the meta data in time the oldest entries will be lost. When the
+buffer is empty or no capturing/encoding is in progress, ``entries``
+will be zero.
+
+Currently this ioctl is only defined for MPEG-2 program streams and
+video elementary streams.
+
+
+.. _v4l2-enc-idx:
+
+.. flat-table:: struct v4l2_enc_idx
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``entries``
+
+ - The number of entries the driver stored in the ``entry`` array.
+
+ - .. row 2
+
+ - __u32
+
+ - ``entries_cap``
+
+ - The number of entries the driver can buffer. Must be greater than
+ zero.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - :cspan:`2` Reserved for future extensions. Drivers must set the
+ array to zero.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_enc_idx_entry <v4l2-enc-idx-entry>`
+
+ - ``entry``\ [``V4L2_ENC_IDX_ENTRIES``]
+
+ - Meta data about a compressed video stream. Each element of the
+ array corresponds to one picture, sorted in ascending order by
+ their ``offset``.
+
+
+
+.. _v4l2-enc-idx-entry:
+
+.. flat-table:: struct v4l2_enc_idx_entry
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u64
+
+ - ``offset``
+
+ - The offset in bytes from the beginning of the compressed video
+ stream to the beginning of this picture, that is a *PES packet
+ header* as defined in :ref:`mpeg2part1` or a *picture header* as
+ defined in :ref:`mpeg2part2`. When the encoder is stopped, the
+ driver resets the offset to zero.
+
+ - .. row 2
+
+ - __u64
+
+ - ``pts``
+
+ - The 33 bit *Presentation Time Stamp* of this picture as defined in
+ :ref:`mpeg2part1`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``length``
+
+ - The length of this picture in bytes.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags containing the coding type of this picture, see
+ :ref:`enc-idx-flags`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _enc-idx-flags:
+
+.. flat-table:: Index Entry Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_ENC_IDX_FRAME_I``
+
+ - 0x00
+
+ - This is an Intra-coded picture.
+
+ - .. row 2
+
+ - ``V4L2_ENC_IDX_FRAME_P``
+
+ - 0x01
+
+ - This is a Predictive-coded picture.
+
+ - .. row 3
+
+ - ``V4L2_ENC_IDX_FRAME_B``
+
+ - 0x02
+
+ - This is a Bidirectionally predictive-coded picture.
+
+ - .. row 4
+
+ - ``V4L2_ENC_IDX_FRAME_MASK``
+
+ - 0x0F
+
+ - *AND* the flags field with this mask to obtain the picture coding
+ type.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst
new file mode 100644
index 000000000000..96b6eaca755c
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst
@@ -0,0 +1,488 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_EXT_CTRLS:
+
+******************************************************************
+ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS
+******************************************************************
+
+Name
+====
+
+VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_ext_controls *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
+ VIDIOC_TRY_EXT_CTRLS
+
+``argp``
+
+
+Description
+===========
+
+These ioctls allow the caller to get or set multiple controls
+atomically. Control IDs are grouped into control classes (see
+:ref:`ctrl-class`) and all controls in the control array must belong
+to the same control class.
+
+Applications must always fill in the ``count``, ``which``, ``controls``
+and ``reserved`` fields of struct
+:ref:`v4l2_ext_controls <v4l2-ext-controls>`, and initialize the
+struct :ref:`v4l2_ext_control <v4l2-ext-control>` array pointed to
+by the ``controls`` fields.
+
+To get the current value of a set of controls applications initialize
+the ``id``, ``size`` and ``reserved2`` fields of each struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
+:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the
+``string`` field. Controls of compound types
+(``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field.
+
+If the ``size`` is too small to receive the control result (only
+relevant for pointer-type controls like strings), then the driver will
+set ``size`` to a valid value and return an ``ENOSPC`` error code. You
+should re-allocate the memory to this new size and try again. For the
+string type it is possible that the same issue occurs again if the
+string has grown in the meantime. It is recommended to call
+:ref:`VIDIOC_QUERYCTRL` first and use
+``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is
+sufficient memory.
+
+N-dimensional arrays are set and retrieved row-by-row. You cannot set a
+partial array, all elements have to be set or retrieved. The total size
+is calculated as ``elems`` * ``elem_size``. These values can be obtained
+by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
+
+To change the value of a set of controls applications initialize the
+``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
+of each struct :ref:`v4l2_ext_control <v4l2-ext-control>` and call
+the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all*
+control values are valid.
+
+To check if a set of controls have correct values applications
+initialize the ``id``, ``size``, ``reserved2`` and
+``value/value64/string/ptr`` fields of each struct
+:ref:`v4l2_ext_control <v4l2-ext-control>` and call the
+:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. It is up to the driver whether wrong
+values are automatically adjusted to a valid value or if an error is
+returned.
+
+When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error
+code. When the value is out of bounds drivers can choose to take the
+closest valid value or return an ``ERANGE`` error code, whatever seems more
+appropriate. In the first case the new value is set in struct
+:ref:`v4l2_ext_control <v4l2-ext-control>`. If the new control value
+is inappropriate (e.g. the given menu index is not supported by the menu
+control), then this will also result in an ``EINVAL`` error code error.
+
+The driver will only set/get these controls if all control values are
+correct. This prevents the situation where only some of the controls
+were set/get. Only low-level errors (e. g. a failed i2c command) can
+still cause this situation.
+
+
+.. _v4l2-ext-control:
+
+.. flat-table:: struct v4l2_ext_control
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ -
+ - Identifies the control, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``size``
+
+ -
+ - The total size in bytes of the payload of this control. This is
+ normally 0, but for pointer controls this should be set to the
+ size of the memory containing the payload, or that will receive
+ the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is
+ less than is required to store the payload result, then it is set
+ to a value large enough to store the payload result and ``ENOSPC`` is
+ returned. Note that for string controls this ``size`` field should
+ not be confused with the length of the string. This field refers
+ to the size of the memory that contains the string. The actual
+ *length* of the string may well be much smaller.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved2``\ [1]
+
+ -
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 4
+
+ - union
+
+ - (anonymous)
+
+ - .. row 5
+
+ -
+ - __s32
+
+ - ``value``
+
+ - New value or current value. Valid if this control is not of type
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
+ not set.
+
+ - .. row 6
+
+ -
+ - __s64
+
+ - ``value64``
+
+ - New value or current value. Valid if this control is of type
+ ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
+ not set.
+
+ - .. row 7
+
+ -
+ - char *
+
+ - ``string``
+
+ - A pointer to a string. Valid if this control is of type
+ ``V4L2_CTRL_TYPE_STRING``.
+
+ - .. row 8
+
+ -
+ - __u8 *
+
+ - ``p_u8``
+
+ - A pointer to a matrix control of unsigned 8-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U8``.
+
+ - .. row 9
+
+ -
+ - __u16 *
+
+ - ``p_u16``
+
+ - A pointer to a matrix control of unsigned 16-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U16``.
+
+ - .. row 10
+
+ -
+ - __u32 *
+
+ - ``p_u32``
+
+ - A pointer to a matrix control of unsigned 32-bit values. Valid if
+ this control is of type ``V4L2_CTRL_TYPE_U32``.
+
+ - .. row 11
+
+ -
+ - void *
+
+ - ``ptr``
+
+ - A pointer to a compound type which can be an N-dimensional array
+ and/or a compound type (the control's type is >=
+ ``V4L2_CTRL_COMPOUND_TYPES``). Valid if
+ ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control.
+
+
+
+.. _v4l2-ext-controls:
+
+.. flat-table:: struct v4l2_ext_controls
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - union
+
+ - (anonymous)
+
+ - .. row 2
+
+ -
+ - __u32
+
+ - ``ctrl_class``
+
+ - The control class to which all controls belong, see
+ :ref:`ctrl-class`. Drivers that use a kernel framework for
+ handling controls will also accept a value of 0 here, meaning that
+ the controls can belong to any control class. Whether drivers
+ support this can be tested by setting ``ctrl_class`` to 0 and
+ calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that
+ succeeds, then the driver supports this feature.
+
+ - .. row 3
+
+ -
+ - __u32
+
+ - ``which``
+
+ - Which value of the control to get/set/try.
+ ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the
+ control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
+ value of the control. Please note that you can only get the
+ default value of the control, you cannot set or try it.
+
+ For backwards compatibility you can also use a control class here
+ (see :ref:`ctrl-class`). In that case all controls have to
+ belong to that control class. This usage is deprecated, instead
+ just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old
+ drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and
+ that require a control class here. You can test for such drivers
+ by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling
+ VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the
+ driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``.
+
+ - .. row 4
+
+ - __u32
+
+ - ``count``
+
+ - The number of controls in the controls array. May also be zero.
+
+ - .. row 5
+
+ - __u32
+
+ - ``error_idx``
+
+ - Set by the driver in case of an error. If the error is associated
+ with a particular control, then ``error_idx`` is set to the index
+ of that control. If the error is not related to a specific
+ control, or the validation step failed (see below), then
+ ``error_idx`` is set to ``count``. The value is undefined if the
+ ioctl returned 0 (success).
+
+ Before controls are read from/written to hardware a validation
+ step takes place: this checks if all controls in the list are
+ valid controls, if no attempt is made to write to a read-only
+ control or read from a write-only control, and any other up-front
+ checks that can be done without accessing the hardware. The exact
+ validations done during this step are driver dependent since some
+ checks might require hardware access for some devices, thus making
+ it impossible to do those checks up-front. However, drivers should
+ make a best-effort to do as many up-front checks as possible.
+
+ This check is done to avoid leaving the hardware in an
+ inconsistent state due to easy-to-avoid problems. But it leads to
+ another problem: the application needs to know whether an error
+ came from the validation step (meaning that the hardware was not
+ touched) or from an error during the actual reading from/writing
+ to hardware.
+
+ The, in hindsight quite poor, solution for that is to set
+ ``error_idx`` to ``count`` if the validation failed. This has the
+ unfortunate side-effect that it is not possible to see which
+ control failed the validation. If the validation was successful
+ and the error happened while accessing the hardware, then
+ ``error_idx`` is less than ``count`` and only the controls up to
+ ``error_idx-1`` were read or written correctly, and the state of
+ the remaining controls is undefined.
+
+ Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is
+ also no need to handle the validation step in this special way, so
+ ``error_idx`` will just be set to the control that failed the
+ validation step instead of to ``count``. This means that if
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``,
+ then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the
+ actual control that failed the validation step. Unfortunately,
+ there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+ - .. row 7
+
+ - struct :ref:`v4l2_ext_control <v4l2-ext-control>` *
+
+ - ``controls``
+
+ - Pointer to an array of ``count`` v4l2_ext_control structures.
+ Ignored if ``count`` equals zero.
+
+
+
+.. _ctrl-class:
+
+.. flat-table:: Control classes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CTRL_CLASS_USER``
+
+ - 0x980000
+
+ - The class containing user controls. These controls are described
+ in :ref:`control`. All controls that can be set using the
+ :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and
+ :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this
+ class.
+
+ - .. row 2
+
+ - ``V4L2_CTRL_CLASS_MPEG``
+
+ - 0x990000
+
+ - The class containing MPEG compression controls. These controls are
+ described in :ref:`mpeg-controls`.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_CLASS_CAMERA``
+
+ - 0x9a0000
+
+ - The class containing camera controls. These controls are described
+ in :ref:`camera-controls`.
+
+ - .. row 4
+
+ - ``V4L2_CTRL_CLASS_FM_TX``
+
+ - 0x9b0000
+
+ - The class containing FM Transmitter (FM TX) controls. These
+ controls are described in :ref:`fm-tx-controls`.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_CLASS_FLASH``
+
+ - 0x9c0000
+
+ - The class containing flash device controls. These controls are
+ described in :ref:`flash-controls`.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_CLASS_JPEG``
+
+ - 0x9d0000
+
+ - The class containing JPEG compression controls. These controls are
+ described in :ref:`jpeg-controls`.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_CLASS_IMAGE_SOURCE``
+
+ - 0x9e0000
+
+ - The class containing image source controls. These controls are
+ described in :ref:`image-source-controls`.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_CLASS_IMAGE_PROC``
+
+ - 0x9f0000
+
+ - The class containing image processing controls. These controls are
+ described in :ref:`image-process-controls`.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_CLASS_FM_RX``
+
+ - 0xa10000
+
+ - The class containing FM Receiver (FM RX) controls. These controls
+ are described in :ref:`fm-rx-controls`.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_CLASS_RF_TUNER``
+
+ - 0xa20000
+
+ - The class containing RF tuner controls. These controls are
+ described in :ref:`rf-tuner-controls`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``id`` is
+ invalid, the struct :ref:`v4l2_ext_controls <v4l2-ext-controls>`
+ ``which`` is invalid, or the struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` was
+ inappropriate (e.g. the given menu index is not supported by the
+ driver). This error code is also returned by the
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or
+ more control values are in conflict.
+
+ERANGE
+ The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``value``
+ is out of bounds.
+
+EBUSY
+ The control is temporarily not changeable, possibly because another
+ applications took over control of the device function this control
+ belongs to.
+
+ENOSPC
+ The space reserved for the control's payload is insufficient. The
+ field ``size`` is set to a value that is enough to store the payload
+ and this error code is returned.
+
+EACCES
+ Attempt to try or set a read-only control or to get a write-only
+ control.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst b/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst
new file mode 100644
index 000000000000..ef4592c338ef
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-fbuf.rst
@@ -0,0 +1,500 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_FBUF:
+
+**********************************
+ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF
+**********************************
+
+Name
+====
+
+VIDIOC_G_FBUF - VIDIOC_S_FBUF - Get or set frame buffer overlay parameters
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_framebuffer *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_framebuffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FBUF, VIDIOC_S_FBUF
+
+``argp``
+
+
+Description
+===========
+
+Applications can use the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` and :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` ioctl
+to get and set the framebuffer parameters for a
+:ref:`Video Overlay <overlay>` or :ref:`Video Output Overlay <osd>`
+(OSD). The type of overlay is implied by the device type (capture or
+output device) and can be determined with the
+:ref:`VIDIOC_QUERYCAP` ioctl. One ``/dev/videoN``
+device must not support both kinds of overlay.
+
+The V4L2 API distinguishes destructive and non-destructive overlays. A
+destructive overlay copies captured video images into the video memory
+of a graphics card. A non-destructive overlay blends video images into a
+VGA signal or graphics into a video signal. *Video Output Overlays* are
+always non-destructive.
+
+To get the current parameters applications call the :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+ioctl with a pointer to a :ref:`struct v4l2_framebuffer <v4l2-framebuffer>`
+structure. The driver fills all fields of the structure or returns an
+EINVAL error code when overlays are not supported.
+
+To set the parameters for a *Video Output Overlay*, applications must
+initialize the ``flags`` field of a struct
+:ref:`struct v4l2_framebuffer <v4l2-framebuffer>`. Since the framebuffer is
+implemented on the TV card all other parameters are determined by the
+driver. When an application calls :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` with a pointer to
+this structure, the driver prepares for the overlay and returns the
+framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>` does, or it returns an error
+code.
+
+To set the parameters for a *non-destructive Video Overlay*,
+applications must initialize the ``flags`` field, the ``fmt``
+substructure, and call :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>`. Again the driver prepares for
+the overlay and returns the framebuffer parameters as :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`
+does, or it returns an error code.
+
+For a *destructive Video Overlay* applications must additionally provide
+a ``base`` address. Setting up a DMA to a random memory location can
+jeopardize the system security, its stability or even damage the
+hardware, therefore only the superuser can set the parameters for a
+destructive video overlay.
+
+
+.. _v4l2-framebuffer:
+
+.. flat-table:: struct v4l2_framebuffer
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ -
+ - Overlay capability flags set by the driver, see
+ :ref:`framebuffer-cap`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``flags``
+
+ -
+ - Overlay control flags set by application and driver, see
+ :ref:`framebuffer-flags`
+
+ - .. row 3
+
+ - void *
+
+ - ``base``
+
+ -
+ - Physical base address of the framebuffer, that is the address of
+ the pixel in the top left corner of the framebuffer. [1]_
+
+ - .. row 4
+
+ -
+ -
+ -
+ - This field is irrelevant to *non-destructive Video Overlays*. For
+ *destructive Video Overlays* applications must provide a base
+ address. The driver may accept only base addresses which are a
+ multiple of two, four or eight bytes. For *Video Output Overlays*
+ the driver must return a valid base address, so applications can
+ find the corresponding Linux framebuffer device (see
+ :ref:`osd`).
+
+ - .. row 5
+
+ - struct
+
+ - ``fmt``
+
+ -
+ - Layout of the frame buffer.
+
+ - .. row 6
+
+ -
+ - __u32
+
+ - ``width``
+
+ - Width of the frame buffer in pixels.
+
+ - .. row 7
+
+ -
+ - __u32
+
+ - ``height``
+
+ - Height of the frame buffer in pixels.
+
+ - .. row 8
+
+ -
+ - __u32
+
+ - ``pixelformat``
+
+ - The pixel format of the framebuffer.
+
+ - .. row 9
+
+ -
+ -
+ -
+ - For *non-destructive Video Overlays* this field only defines a
+ format for the struct :ref:`v4l2_window <v4l2-window>`
+ ``chromakey`` field.
+
+ - .. row 10
+
+ -
+ -
+ -
+ - For *destructive Video Overlays* applications must initialize this
+ field. For *Video Output Overlays* the driver must return a valid
+ format.
+
+ - .. row 11
+
+ -
+ -
+ -
+ - Usually this is an RGB format (for example
+ :ref:`V4L2_PIX_FMT_RGB565 <V4L2-PIX-FMT-RGB565>`) but YUV
+ formats (only packed YUV formats when chroma keying is used, not
+ including ``V4L2_PIX_FMT_YUYV`` and ``V4L2_PIX_FMT_UYVY``) and the
+ ``V4L2_PIX_FMT_PAL8`` format are also permitted. The behavior of
+ the driver when an application requests a compressed format is
+ undefined. See :ref:`pixfmt` for information on pixel formats.
+
+ - .. row 12
+
+ -
+ - enum :ref:`v4l2_field <v4l2-field>`
+
+ - ``field``
+
+ - Drivers and applications shall ignore this field. If applicable,
+ the field order is selected with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, using the ``field``
+ field of struct :ref:`v4l2_window <v4l2-window>`.
+
+ - .. row 13
+
+ -
+ - __u32
+
+ - ``bytesperline``
+
+ - Distance in bytes between the leftmost pixels in two adjacent
+ lines.
+
+ - .. row 14
+
+ - :cspan:`3`
+
+ This field is irrelevant to *non-destructive Video Overlays*.
+
+ For *destructive Video Overlays* both applications and drivers can
+ set this field to request padding bytes at the end of each line.
+ Drivers however may ignore the requested value, returning
+ ``width`` times bytes-per-pixel or a larger value required by the
+ hardware. That implies applications can just set this field to
+ zero to get a reasonable default.
+
+ For *Video Output Overlays* the driver must return a valid value.
+
+ Video hardware may access padding bytes, therefore they must
+ reside in accessible memory. Consider for example the case where
+ padding bytes after the last line of an image cross a system page
+ boundary. Capture devices may write padding bytes, the value is
+ undefined. Output devices ignore the contents of padding bytes.
+
+ When the image format is planar the ``bytesperline`` value applies
+ to the first plane and is divided by the same factor as the
+ ``width`` field for the other planes. For example the Cb and Cr
+ planes of a YUV 4:2:0 image have half as many padding bytes
+ following each line as the Y plane. To avoid ambiguities drivers
+ must return a ``bytesperline`` value rounded up to a multiple of
+ the scale factor.
+
+ - .. row 15
+
+ -
+ - __u32
+
+ - ``sizeimage``
+
+ - This field is irrelevant to *non-destructive Video Overlays*. For
+ *destructive Video Overlays* applications must initialize this
+ field. For *Video Output Overlays* the driver must return a valid
+ format.
+
+ Together with ``base`` it defines the framebuffer memory
+ accessible by the driver.
+
+ - .. row 16
+
+ -
+ - enum :ref:`v4l2_colorspace <v4l2-colorspace>`
+
+ - ``colorspace``
+
+ - This information supplements the ``pixelformat`` and must be set
+ by the driver, see :ref:`colorspaces`.
+
+ - .. row 17
+
+ -
+ - __u32
+
+ - ``priv``
+
+ - Reserved. Drivers and applications must set this field to zero.
+
+
+
+.. _framebuffer-cap:
+
+.. flat-table:: Frame Buffer Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+
+ - 0x0001
+
+ - The device is capable of non-destructive overlays. When the driver
+ clears this flag, only destructive overlays are supported. There
+ are no drivers yet which support both destructive and
+ non-destructive overlays. Video Output Overlays are in practice
+ always non-destructive.
+
+ - .. row 2
+
+ - ``V4L2_FBUF_CAP_CHROMAKEY``
+
+ - 0x0002
+
+ - The device supports clipping by chroma-keying the images. That is,
+ image pixels replace pixels in the VGA or video signal only where
+ the latter assume a certain color. Chroma-keying makes no sense
+ for destructive overlays.
+
+ - .. row 3
+
+ - ``V4L2_FBUF_CAP_LIST_CLIPPING``
+
+ - 0x0004
+
+ - The device supports clipping using a list of clip rectangles.
+
+ - .. row 4
+
+ - ``V4L2_FBUF_CAP_BITMAP_CLIPPING``
+
+ - 0x0008
+
+ - The device supports clipping using a bit mask.
+
+ - .. row 5
+
+ - ``V4L2_FBUF_CAP_LOCAL_ALPHA``
+
+ - 0x0010
+
+ - The device supports clipping/blending using the alpha channel of
+ the framebuffer or VGA signal. Alpha blending makes no sense for
+ destructive overlays.
+
+ - .. row 6
+
+ - ``V4L2_FBUF_CAP_GLOBAL_ALPHA``
+
+ - 0x0020
+
+ - The device supports alpha blending using a global alpha value.
+ Alpha blending makes no sense for destructive overlays.
+
+ - .. row 7
+
+ - ``V4L2_FBUF_CAP_LOCAL_INV_ALPHA``
+
+ - 0x0040
+
+ - The device supports clipping/blending using the inverted alpha
+ channel of the framebuffer or VGA signal. Alpha blending makes no
+ sense for destructive overlays.
+
+ - .. row 8
+
+ - ``V4L2_FBUF_CAP_SRC_CHROMAKEY``
+
+ - 0x0080
+
+ - The device supports Source Chroma-keying. Video pixels with the
+ chroma-key colors are replaced by framebuffer pixels, which is
+ exactly opposite of ``V4L2_FBUF_CAP_CHROMAKEY``
+
+
+
+.. _framebuffer-flags:
+
+.. flat-table:: Frame Buffer Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_FBUF_FLAG_PRIMARY``
+
+ - 0x0001
+
+ - The framebuffer is the primary graphics surface. In other words,
+ the overlay is destructive. This flag is typically set by any
+ driver that doesn't have the ``V4L2_FBUF_CAP_EXTERNOVERLAY``
+ capability and it is cleared otherwise.
+
+ - .. row 2
+
+ - ``V4L2_FBUF_FLAG_OVERLAY``
+
+ - 0x0002
+
+ - If this flag is set for a video capture device, then the driver
+ will set the initial overlay size to cover the full framebuffer
+ size, otherwise the existing overlay size (as set by
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`) will be used. Only one
+ video capture driver (bttv) supports this flag. The use of this
+ flag for capture devices is deprecated. There is no way to detect
+ which drivers support this flag, so the only reliable method of
+ setting the overlay size is through
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. If this flag is set for a
+ video output device, then the video output overlay window is
+ relative to the top-left corner of the framebuffer and restricted
+ to the size of the framebuffer. If it is cleared, then the video
+ output overlay window is relative to the video output display.
+
+ - .. row 3
+
+ - ``V4L2_FBUF_FLAG_CHROMAKEY``
+
+ - 0x0004
+
+ - Use chroma-keying. The chroma-key color is determined by the
+ ``chromakey`` field of struct :ref:`v4l2_window <v4l2-window>`
+ and negotiated with the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ ioctl, see :ref:`overlay` and :ref:`osd`.
+
+ - .. row 4
+
+ - :cspan:`2` There are no flags to enable clipping using a list of
+ clip rectangles or a bitmap. These methods are negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+
+ - .. row 5
+
+ - ``V4L2_FBUF_FLAG_LOCAL_ALPHA``
+
+ - 0x0008
+
+ - Use the alpha channel of the framebuffer to clip or blend
+ framebuffer pixels with video images. The blend function is:
+ output = framebuffer pixel * alpha + video pixel * (1 - alpha).
+ The actual alpha depth depends on the framebuffer pixel format.
+
+ - .. row 6
+
+ - ``V4L2_FBUF_FLAG_GLOBAL_ALPHA``
+
+ - 0x0010
+
+ - Use a global alpha value to blend the framebuffer with video
+ images. The blend function is: output = (framebuffer pixel * alpha
+ + video pixel * (255 - alpha)) / 255. The alpha value is
+ determined by the ``global_alpha`` field of struct
+ :ref:`v4l2_window <v4l2-window>` and negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`.
+
+ - .. row 7
+
+ - ``V4L2_FBUF_FLAG_LOCAL_INV_ALPHA``
+
+ - 0x0020
+
+ - Like ``V4L2_FBUF_FLAG_LOCAL_ALPHA``, use the alpha channel of the
+ framebuffer to clip or blend framebuffer pixels with video images,
+ but with an inverted alpha value. The blend function is: output =
+ framebuffer pixel * (1 - alpha) + video pixel * alpha. The actual
+ alpha depth depends on the framebuffer pixel format.
+
+ - .. row 8
+
+ - ``V4L2_FBUF_FLAG_SRC_CHROMAKEY``
+
+ - 0x0040
+
+ - Use source chroma-keying. The source chroma-key color is
+ determined by the ``chromakey`` field of struct
+ :ref:`v4l2_window <v4l2-window>` and negotiated with the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, see :ref:`overlay`
+ and :ref:`osd`. Both chroma-keying are mutual exclusive to each
+ other, so same ``chromakey`` field of struct
+ :ref:`v4l2_window <v4l2-window>` is being used.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EPERM
+ :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` can only be called by a privileged user to
+ negotiate the parameters for a destructive overlay.
+
+EINVAL
+ The :ref:`VIDIOC_S_FBUF <VIDIOC_G_FBUF>` parameters are unsuitable.
+
+.. [1]
+ A physical base address may not suit all platforms. GK notes in
+ theory we should pass something like PCI device + memory region +
+ offset instead. If you encounter problems please discuss on the
+ linux-media mailing list:
+ `https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
new file mode 100644
index 000000000000..ee6f11978fd6
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-fmt.rst
@@ -0,0 +1,188 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_FMT:
+
+************************************************
+ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
+************************************************
+
+Name
+====
+
+VIDIOC_G_FMT - VIDIOC_S_FMT - VIDIOC_TRY_FMT - Get or set the data format, try a format
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_format *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to negotiate the format of data (typically image
+format) exchanged between driver and application.
+
+To query the current parameters applications set the ``type`` field of a
+struct :ref:`struct v4l2_format <v4l2-format>` to the respective buffer (stream)
+type. For example video capture devices use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. When the application calls the
+:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this structure the driver fills
+the respective member of the ``fmt`` union. In case of video capture
+devices that is either the struct
+:ref:`v4l2_pix_format <v4l2-pix-format>` ``pix`` or the struct
+:ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>` ``pix_mp``
+member. When the requested buffer type is not supported drivers return
+an ``EINVAL`` error code.
+
+To change the current format parameters applications initialize the
+``type`` field and all fields of the respective ``fmt`` union member.
+For details see the documentation of the various devices types in
+:ref:`devices`. Good practice is to query the current parameters
+first, and to modify only those parameters not suitable for the
+application. When the application calls the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with
+a pointer to a :ref:`struct v4l2_format <v4l2-format>` structure the driver
+checks and adjusts the parameters against hardware abilities. Drivers
+should not return an error code unless the ``type`` field is invalid,
+this is a mechanism to fathom device capabilities and to approach
+parameters acceptable for both the application and driver. On success
+the driver may program the hardware, allocate resources and generally
+prepare for data exchange. Finally the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl returns
+the current format parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. Very simple,
+inflexible devices may even ignore all input and always return the
+default parameters. However all V4L2 devices exchanging data with the
+application must implement the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
+ioctl. When the requested buffer type is not supported drivers return an
+EINVAL error code on a :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` attempt. When I/O is already in
+progress or the resource is not available for other reasons drivers
+return the ``EBUSY`` error code.
+
+The :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` with one
+exception: it does not change driver state. It can also be called at any
+time, never returning ``EBUSY``. This function is provided to negotiate
+parameters, to learn about hardware limitations, without disabling I/O
+or possibly time consuming hardware preparations. Although strongly
+recommended drivers are not required to implement this ioctl.
+
+The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical to what
+:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` returns for the same input or output.
+
+
+.. _v4l2-format:
+
+.. flat-table:: struct v4l2_format
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - Type of the data stream, see :ref:`v4l2-buf-type`.
+
+ - .. row 2
+
+ - union
+
+ - ``fmt``
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_pix_format <v4l2-pix-format>`
+
+ - ``pix``
+
+ - Definition of an image format, see :ref:`pixfmt`, used by video
+ capture and output devices.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_pix_format_mplane <v4l2-pix-format-mplane>`
+
+ - ``pix_mp``
+
+ - Definition of an image format, see :ref:`pixfmt`, used by video
+ capture and output devices that support the
+ :ref:`multi-planar version of the API <planar-apis>`.
+
+ - .. row 5
+
+ -
+ - struct :ref:`v4l2_window <v4l2-window>`
+
+ - ``win``
+
+ - Definition of an overlaid image, see :ref:`overlay`, used by
+ video overlay devices.
+
+ - .. row 6
+
+ -
+ - struct :ref:`v4l2_vbi_format <v4l2-vbi-format>`
+
+ - ``vbi``
+
+ - Raw VBI capture or output parameters. This is discussed in more
+ detail in :ref:`raw-vbi`. Used by raw VBI capture and output
+ devices.
+
+ - .. row 7
+
+ -
+ - struct :ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`
+
+ - ``sliced``
+
+ - Sliced VBI capture or output parameters. See :ref:`sliced` for
+ details. Used by sliced VBI capture and output devices.
+
+ - .. row 8
+
+ -
+ - struct :ref:`v4l2_sdr_format <v4l2-sdr-format>`
+
+ - ``sdr``
+
+ - Definition of a data format, see :ref:`pixfmt`, used by SDR
+ capture and output devices.
+
+ - .. row 9
+
+ -
+ - __u8
+
+ - ``raw_data``\ [200]
+
+ - Place holder for future extensions.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_format <v4l2-format>` ``type`` field is
+ invalid or the requested buffer type not supported.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-frequency.rst b/Documentation/media/uapi/v4l/vidioc-g-frequency.rst
new file mode 100644
index 000000000000..a1fd2a870de4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-frequency.rst
@@ -0,0 +1,123 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_FREQUENCY:
+
+********************************************
+ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
+********************************************
+
+Name
+====
+
+VIDIOC_G_FREQUENCY - VIDIOC_S_FREQUENCY - Get or set tuner or modulator radio frequency
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_frequency *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_frequency *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY
+
+``argp``
+
+
+Description
+===========
+
+To get the current tuner or modulator radio frequency applications set
+the ``tuner`` field of a struct
+:ref:`v4l2_frequency <v4l2-frequency>` to the respective tuner or
+modulator number (only input devices have tuners, only output devices
+have modulators), zero out the ``reserved`` array and call the
+:ref:`VIDIOC_G_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this structure. The
+driver stores the current frequency in the ``frequency`` field.
+
+To change the current tuner or modulator radio frequency applications
+initialize the ``tuner``, ``type`` and ``frequency`` fields, and the
+``reserved`` array of a struct :ref:`v4l2_frequency <v4l2-frequency>`
+and call the :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl with a pointer to this
+structure. When the requested frequency is not possible the driver
+assumes the closest possible value. However :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` is a
+write-only ioctl, it does not return the actual new frequency.
+
+
+.. _v4l2-frequency:
+
+.. flat-table:: struct v4l2_frequency
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner or modulator index number. This is the same value as in
+ the struct :ref:`v4l2_input <v4l2-input>` ``tuner`` field and
+ the struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field, or
+ the struct :ref:`v4l2_output <v4l2-output>` ``modulator`` field
+ and the struct :ref:`v4l2_modulator <v4l2-modulator>` ``index``
+ field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. The type must be
+ set to ``V4L2_TUNER_RADIO`` for ``/dev/radioX`` device nodes, and
+ to ``V4L2_TUNER_ANALOG_TV`` for all others. Set this field to
+ ``V4L2_TUNER_RADIO`` for modulators (currently only radio
+ modulators are supported). See :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``frequency``
+
+ - Tuning frequency in units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` or struct
+ :ref:`v4l2_modulator <v4l2-modulator>` ``capability`` flag
+ ``V4L2_TUNER_CAP_LOW`` is set, in units of 62.5 Hz. A 1 Hz unit is
+ used when the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is set.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``tuner`` index is out of bounds or the value in the ``type``
+ field is wrong.
+
+EBUSY
+ A hardware seek is in progress.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-input.rst b/Documentation/media/uapi/v4l/vidioc-g-input.rst
new file mode 100644
index 000000000000..29e22f6f8028
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-input.rst
@@ -0,0 +1,62 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_INPUT:
+
+************************************
+ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT
+************************************
+
+Name
+====
+
+VIDIOC_G_INPUT - VIDIOC_S_INPUT - Query or select the current video input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_INPUT, VIDIOC_S_INPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current video input applications call the
+:ref:`VIDIOC_G_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer to an integer where the driver
+stores the number of the input, as in the struct
+:ref:`v4l2_input <v4l2-input>` ``index`` field. This ioctl will fail
+only when there are no video inputs, returning ``EINVAL``.
+
+To select a video input applications store the number of the desired
+input in an integer and call the :ref:`VIDIOC_S_INPUT <VIDIOC_G_INPUT>` ioctl with a pointer
+to this integer. Side effects are possible. For example inputs may
+support different video standards, so the driver may implicitly switch
+the current standard. Because of these possible side effects
+applications must select an input before querying or negotiating any
+other parameters.
+
+Information about video inputs is available using the
+:ref:`VIDIOC_ENUMINPUT` ioctl.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the video input is out of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst b/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst
new file mode 100644
index 000000000000..f5bf8b7915ed
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst
@@ -0,0 +1,184 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_JPEGCOMP:
+
+******************************************
+ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
+******************************************
+
+Name
+====
+
+VIDIOC_G_JPEGCOMP - VIDIOC_S_JPEGCOMP
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_jpegcompression *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const v4l2_jpegcompression *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are **deprecated**. New drivers and applications should use
+:ref:`JPEG class controls <jpeg-controls>` for image quality and JPEG
+markers control.
+
+[to do]
+
+Ronald Bultje elaborates:
+
+APP is some application-specific information. The application can set it
+itself, and it'll be stored in the JPEG-encoded fields (eg; interlacing
+information for in an AVI or so). COM is the same, but it's comments,
+like 'encoded by me' or so.
+
+jpeg_markers describes whether the huffman tables, quantization tables
+and the restart interval information (all JPEG-specific stuff) should be
+stored in the JPEG-encoded fields. These define how the JPEG field is
+encoded. If you omit them, applications assume you've used standard
+encoding. You usually do want to add them.
+
+
+.. _v4l2-jpegcompression:
+
+.. flat-table:: struct v4l2_jpegcompression
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - int
+
+ - ``quality``
+
+ - Deprecated. If
+ :ref:`V4L2_CID_JPEG_COMPRESSION_QUALITY <jpeg-quality-control>`
+ control is exposed by a driver applications should use it instead
+ and ignore this field.
+
+ - .. row 2
+
+ - int
+
+ - ``APPn``
+
+ -
+
+ - .. row 3
+
+ - int
+
+ - ``APP_len``
+
+ -
+
+ - .. row 4
+
+ - char
+
+ - ``APP_data``\ [60]
+
+ -
+
+ - .. row 5
+
+ - int
+
+ - ``COM_len``
+
+ -
+
+ - .. row 6
+
+ - char
+
+ - ``COM_data``\ [60]
+
+ -
+
+ - .. row 7
+
+ - __u32
+
+ - ``jpeg_markers``
+
+ - See :ref:`jpeg-markers`. Deprecated. If
+ :ref:`V4L2_CID_JPEG_ACTIVE_MARKER <jpeg-active-marker-control>`
+ control is exposed by a driver applications should use it instead
+ and ignore this field.
+
+
+
+.. _jpeg-markers:
+
+.. flat-table:: JPEG Markers Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_JPEG_MARKER_DHT``
+
+ - (1<<3)
+
+ - Define Huffman Tables
+
+ - .. row 2
+
+ - ``V4L2_JPEG_MARKER_DQT``
+
+ - (1<<4)
+
+ - Define Quantization Tables
+
+ - .. row 3
+
+ - ``V4L2_JPEG_MARKER_DRI``
+
+ - (1<<5)
+
+ - Define Restart Interval
+
+ - .. row 4
+
+ - ``V4L2_JPEG_MARKER_COM``
+
+ - (1<<6)
+
+ - Comment segment
+
+ - .. row 5
+
+ - ``V4L2_JPEG_MARKER_APP``
+
+ - (1<<7)
+
+ - App segment, driver will always use APP0
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-modulator.rst b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst
new file mode 100644
index 000000000000..05d83610bdc5
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-modulator.rst
@@ -0,0 +1,255 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_MODULATOR:
+
+********************************************
+ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
+********************************************
+
+Name
+====
+
+VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_modulator *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_modulator *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a modulator applications initialize the
+``index`` field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_modulator <v4l2-modulator>` and call the
+:ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers
+fill the rest of the structure or return an ``EINVAL`` error code when the
+index is out of bounds. To enumerate all modulators applications shall
+begin at index zero, incrementing by one until the driver returns
+EINVAL.
+
+Modulators have two writable properties, an audio modulation set and the
+radio frequency. To change the modulated audio subprograms, applications
+initialize the ``index`` and ``txsubchans`` fields and the ``reserved``
+array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a
+different audio modulation if the request cannot be satisfied. However
+this is a write-only ioctl, it does not return the actual audio
+modulation selected.
+
+:ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and
+``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be
+initialized to zero. The term 'modulator' means SDR transmitter in this
+context.
+
+To change the radio frequency the
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
+
+
+.. _v4l2-modulator:
+
+.. flat-table:: struct v4l2_modulator
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1 1
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Identifies the modulator, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the modulator, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 3
+
+ - __u32
+
+ - ``capability``
+
+ - Modulator capability flags. No flags are defined for this field,
+ the tuner flags in struct :ref:`v4l2_tuner <v4l2-tuner>` are
+ used accordingly. The audio flags indicate the ability to encode
+ audio subprograms. They will *not* change for example with the
+ current video standard.
+
+ - .. row 4
+
+ - __u32
+
+ - ``rangelow``
+
+ - The lowest tunable frequency in units of 62.5 KHz, or if the
+ ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
+ 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
+ set, in units of 1 Hz.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangehigh``
+
+ - The highest tunable frequency in units of 62.5 KHz, or if the
+ ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
+ 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
+ set, in units of 1 Hz.
+
+ - .. row 6
+
+ - __u32
+
+ - ``txsubchans``
+
+ - With this field applications can determine how audio sub-carriers
+ shall be modulated. It contains a set of flags as defined in
+ :ref:`modulator-txsubchans`. Note the tuner ``rxsubchans`` flags
+ are reused, but the semantics are different. Video output devices
+ are assumed to have an analog or PCM audio input with 1-3
+ channels. The ``txsubchans`` flags select one or more channels for
+ modulation, together with some audio subprogram indicator, for
+ example a stereo pilot tone.
+
+ - .. row 7
+
+ - __u32
+
+ - ``type``
+
+ - :cspan:`2` Type of the modulator, see :ref:`v4l2-tuner-type`.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _modulator-txsubchans:
+
+.. flat-table:: Modulator Audio Transmission Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - 0x0001
+
+ - Modulate channel 1 as mono audio, when the input has more
+ channels, a down-mix of channel 1 and 2. This flag does not
+ combine with ``V4L2_TUNER_SUB_STEREO`` or
+ ``V4L2_TUNER_SUB_LANG1``.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_SUB_STEREO``
+
+ - 0x0002
+
+ - Modulate channel 1 and 2 as left and right channel of a stereo
+ audio signal. When the input has only one channel or two channels
+ and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as
+ left and right channel. This flag does not combine with
+ ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the
+ driver does not support stereo audio it shall fall back to mono.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SUB_LANG1``
+
+ - 0x0008
+
+ - Modulate channel 1 and 2 as primary and secondary language of a
+ bilingual audio signal. When the input has only one channel it is
+ used for both languages. It is not possible to encode the primary
+ or secondary language only. This flag does not combine with
+ ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or
+ ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the
+ respective audio matrix, or the current video standard does not
+ permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall
+ return an ``EINVAL`` error code and the driver shall fall back to mono
+ or stereo mode.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_SUB_LANG2``
+
+ - 0x0004
+
+ - Same effect as ``V4L2_TUNER_SUB_SAP``.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_SUB_SAP``
+
+ - 0x0004
+
+ - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is
+ encoded as mono audio, the last channel as Second Audio Program.
+ When the input has only one channel it is used for both audio
+ tracks. When the input has three channels the mono track is a
+ down-mix of channel 1 and 2. When combined with
+ ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and
+ right stereo audio, channel 3 as Second Audio Program. When the
+ input has only two channels, the first is encoded as left and
+ right channel and the second as SAP. When the input has only one
+ channel it is used for all audio tracks. It is not possible to
+ encode a Second Audio Program only. This flag must combine with
+ ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the
+ hardware does not support the respective audio matrix, or the
+ current video standard does not permit SAP the
+ :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and
+ driver shall fall back to mono or stereo mode.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_SUB_RDS``
+
+ - 0x0010
+
+ - Enable the RDS encoder for a radio FM transmitter.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_modulator <v4l2-modulator>` ``index`` is
+ out of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-output.rst b/Documentation/media/uapi/v4l/vidioc-g-output.rst
new file mode 100644
index 000000000000..ae0ad577ba97
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-output.rst
@@ -0,0 +1,64 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_OUTPUT:
+
+**************************************
+ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
+**************************************
+
+Name
+====
+
+VIDIOC_G_OUTPUT - VIDIOC_S_OUTPUT - Query or select the current video output
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT
+
+``argp``
+
+
+Description
+===========
+
+To query the current video output applications call the
+:ref:`VIDIOC_G_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a pointer to an integer where the driver
+stores the number of the output, as in the struct
+:ref:`v4l2_output <v4l2-output>` ``index`` field. This ioctl will
+fail only when there are no video outputs, returning the ``EINVAL`` error
+code.
+
+To select a video output applications store the number of the desired
+output in an integer and call the :ref:`VIDIOC_S_OUTPUT <VIDIOC_G_OUTPUT>` ioctl with a
+pointer to this integer. Side effects are possible. For example outputs
+may support different video standards, so the driver may implicitly
+switch the current standard. standard. Because of these possible side
+effects applications must select an output before querying or
+negotiating any other parameters.
+
+Information about video outputs is available using the
+:ref:`VIDIOC_ENUMOUTPUT` ioctl.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The number of the video output is out of bounds, or there are no
+ video outputs at all.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-parm.rst b/Documentation/media/uapi/v4l/vidioc-g-parm.rst
new file mode 100644
index 000000000000..7116e0decddc
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-parm.rst
@@ -0,0 +1,349 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_PARM:
+
+**********************************
+ioctl VIDIOC_G_PARM, VIDIOC_S_PARM
+**********************************
+
+Name
+====
+
+VIDIOC_G_PARM - VIDIOC_S_PARM - Get or set streaming parameters
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_streamparm *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_PARM, VIDIOC_S_PARM
+
+``argp``
+
+
+Description
+===========
+
+The current video standard determines a nominal number of frames per
+second. If less than this number of frames is to be captured or output,
+applications can request frame skipping or duplicating on the driver
+side. This is especially useful when using the :ref:`read() <func-read>` or
+:ref:`write() <func-write>`, which are not augmented by timestamps or sequence
+counters, and to avoid unnecessary data copying.
+
+Further these ioctls can be used to determine the number of buffers used
+internally by a driver in read/write mode. For implications see the
+section discussing the :ref:`read() <func-read>` function.
+
+To get and set the streaming parameters applications call the
+:ref:`VIDIOC_G_PARM <VIDIOC_G_PARM>` and :ref:`VIDIOC_S_PARM <VIDIOC_G_PARM>` ioctl, respectively. They take a
+pointer to a struct :ref:`struct v4l2_streamparm <v4l2-streamparm>` which contains a
+union holding separate parameters for input and output devices.
+
+
+.. _v4l2-streamparm:
+
+.. flat-table:: struct v4l2_streamparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ -
+ - The buffer (stream) type, same as struct
+ :ref:`v4l2_format <v4l2-format>` ``type``, set by the
+ application. See :ref:`v4l2-buf-type`
+
+ - .. row 2
+
+ - union
+
+ - ``parm``
+
+ -
+ -
+
+ - .. row 3
+
+ -
+ - struct :ref:`v4l2_captureparm <v4l2-captureparm>`
+
+ - ``capture``
+
+ - Parameters for capture devices, used when ``type`` is
+ ``V4L2_BUF_TYPE_VIDEO_CAPTURE``.
+
+ - .. row 4
+
+ -
+ - struct :ref:`v4l2_outputparm <v4l2-outputparm>`
+
+ - ``output``
+
+ - Parameters for output devices, used when ``type`` is
+ ``V4L2_BUF_TYPE_VIDEO_OUTPUT``.
+
+ - .. row 5
+
+ -
+ - __u8
+
+ - ``raw_data``\ [200]
+
+ - A place holder for future extensions.
+
+
+
+.. _v4l2-captureparm:
+
+.. flat-table:: struct v4l2_captureparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ - See :ref:`parm-caps`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``capturemode``
+
+ - Set by drivers and applications, see :ref:`parm-flags`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``timeperframe``
+
+ - This is the desired period between successive frames captured by
+ the driver, in seconds. The field is intended to skip frames on
+ the driver side, saving I/O bandwidth.
+
+ Applications store here the desired frame period, drivers return
+ the actual frame period, which must be greater or equal to the
+ nominal frame period determined by the current video standard
+ (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+ field). Changing the video standard (also implicitly by switching
+ the video input) may reset this parameter to the nominal frame
+ period. To reset manually applications can just set this field to
+ zero.
+
+ Drivers support this function only when they set the
+ ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+ - .. row 4
+
+ - __u32
+
+ - ``extendedmode``
+
+ - Custom (driver specific) streaming parameters. When unused,
+ applications and drivers must set this field to zero. Applications
+ using this field should check the driver name and version, see
+ :ref:`querycap`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``readbuffers``
+
+ - Applications set this field to the desired number of buffers used
+ internally by the driver in :ref:`read() <func-read>` mode.
+ Drivers return the actual number of buffers. When an application
+ requests zero buffers, drivers should just return the current
+ setting rather than the minimum or an error code. For details see
+ :ref:`rw`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _v4l2-outputparm:
+
+.. flat-table:: struct v4l2_outputparm
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``capability``
+
+ - See :ref:`parm-caps`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``outputmode``
+
+ - Set by drivers and applications, see :ref:`parm-flags`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``timeperframe``
+
+ - This is the desired period between successive frames output by the
+ driver, in seconds.
+
+ - .. row 4
+
+ - :cspan:`2`
+
+ The field is intended to repeat frames on the driver side in
+ :ref:`write() <func-write>` mode (in streaming mode timestamps
+ can be used to throttle the output), saving I/O bandwidth.
+
+ Applications store here the desired frame period, drivers return
+ the actual frame period, which must be greater or equal to the
+ nominal frame period determined by the current video standard
+ (struct :ref:`v4l2_standard <v4l2-standard>` ``frameperiod``
+ field). Changing the video standard (also implicitly by switching
+ the video output) may reset this parameter to the nominal frame
+ period. To reset manually applications can just set this field to
+ zero.
+
+ Drivers support this function only when they set the
+ ``V4L2_CAP_TIMEPERFRAME`` flag in the ``capability`` field.
+
+ - .. row 5
+
+ - __u32
+
+ - ``extendedmode``
+
+ - Custom (driver specific) streaming parameters. When unused,
+ applications and drivers must set this field to zero. Applications
+ using this field should check the driver name and version, see
+ :ref:`querycap`.
+
+ - .. row 6
+
+ - __u32
+
+ - ``writebuffers``
+
+ - Applications set this field to the desired number of buffers used
+ internally by the driver in :ref:`write() <func-write>` mode. Drivers
+ return the actual number of buffers. When an application requests
+ zero buffers, drivers should just return the current setting
+ rather than the minimum or an error code. For details see
+ :ref:`rw`.
+
+ - .. row 7
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _parm-caps:
+
+.. flat-table:: Streaming Parameters Capabilites
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CAP_TIMEPERFRAME``
+
+ - 0x1000
+
+ - The frame skipping/repeating controlled by the ``timeperframe``
+ field is supported.
+
+
+
+.. _parm-flags:
+
+.. flat-table:: Capture Parameters Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_MODE_HIGHQUALITY``
+
+ - 0x0001
+
+ - High quality imaging mode. High quality mode is intended for still
+ imaging applications. The idea is to get the best possible image
+ quality that the hardware can deliver. It is not defined how the
+ driver writer may achieve that; it will depend on the hardware and
+ the ingenuity of the driver writer. High quality mode is a
+ different mode from the regular motion video capture modes. In
+ high quality mode:
+
+ - The driver may be able to capture higher resolutions than for
+ motion capture.
+
+ - The driver may support fewer pixel formats than motion capture
+ (eg; true color).
+
+ - The driver may capture and arithmetically combine multiple
+ successive fields or frames to remove color edge artifacts and
+ reduce the noise in the video data.
+
+ - The driver may capture images in slices like a scanner in order
+ to handle larger format images than would otherwise be
+ possible.
+
+ - An image capture operation may be significantly slower than
+ motion capture.
+
+ - Moving objects in the image might have excessive motion blur.
+
+ - Capture might only work through the :ref:`read() <func-read>` call.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-priority.rst b/Documentation/media/uapi/v4l/vidioc-g-priority.rst
new file mode 100644
index 000000000000..9f774ce400a4
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-priority.rst
@@ -0,0 +1,117 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_PRIORITY:
+
+******************************************
+ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
+******************************************
+
+Name
+====
+
+VIDIOC_G_PRIORITY - VIDIOC_S_PRIORITY - Query or request the access priority associated with a file descriptor
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, enum v4l2_priority *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const enum v4l2_priority *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY
+
+``argp``
+ Pointer to an enum v4l2_priority type.
+
+
+Description
+===========
+
+To query the current access priority applications call the
+:ref:`VIDIOC_G_PRIORITY <VIDIOC_G_PRIORITY>` ioctl with a pointer to an enum v4l2_priority
+variable where the driver stores the current priority.
+
+To request an access priority applications store the desired priority in
+an enum v4l2_priority variable and call :ref:`VIDIOC_S_PRIORITY <VIDIOC_G_PRIORITY>` ioctl
+with a pointer to this variable.
+
+
+.. _v4l2-priority:
+
+.. flat-table:: enum v4l2_priority
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_PRIORITY_UNSET``
+
+ - 0
+
+ -
+
+ - .. row 2
+
+ - ``V4L2_PRIORITY_BACKGROUND``
+
+ - 1
+
+ - Lowest priority, usually applications running in background, for
+ example monitoring VBI transmissions. A proxy application running
+ in user space will be necessary if multiple applications want to
+ read from a device at this priority.
+
+ - .. row 3
+
+ - ``V4L2_PRIORITY_INTERACTIVE``
+
+ - 2
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_PRIORITY_DEFAULT``
+
+ - 2
+
+ - Medium priority, usually applications started and interactively
+ controlled by the user. For example TV viewers, Teletext browsers,
+ or just "panel" applications to change the channel or video
+ controls. This is the default priority unless an application
+ requests another.
+
+ - .. row 5
+
+ - ``V4L2_PRIORITY_RECORD``
+
+ - 3
+
+ - Highest priority. Only one file descriptor can have this priority,
+ it blocks any other fd from changing device properties. Usually
+ applications which must not be interrupted, like video recording.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The requested priority value is invalid.
+
+EBUSY
+ Another application already requested higher priority.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
new file mode 100644
index 000000000000..953931fabd00
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
@@ -0,0 +1,209 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_SELECTION:
+
+********************************************
+ioctl VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+********************************************
+
+Name
+====
+
+VIDIOC_G_SELECTION - VIDIOC_S_SELECTION - Get or set one of the selection rectangles
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_selection *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_SELECTION, VIDIOC_S_SELECTION
+
+``argp``
+
+
+Description
+===========
+
+The ioctls are used to query and configure selection rectangles.
+
+To query the cropping (composing) rectangle set struct
+:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
+respective buffer type. Do not use the multiplanar buffer types. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` and use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
+value of struct :ref:`v4l2_selection <v4l2-selection>` ``target``
+field to ``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer
+to table :ref:`v4l2-selections-common` or :ref:`selection-api` for
+additional targets. The ``flags`` and ``reserved`` fields of struct
+:ref:`v4l2_selection <v4l2-selection>` are ignored and they must be
+filled with zeros. The driver fills the rest of the structure or returns
+EINVAL error code if incorrect buffer type or target was used. If
+cropping (composing) is not supported then the active rectangle is not
+mutable and it is always equal to the bounds rectangle. Finally, the
+struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle is filled with
+the current cropping (composing) coordinates. The coordinates are
+expressed in driver-dependent units. The only exception are rectangles
+for images in raw formats, whose coordinates are always expressed in
+pixels.
+
+To change the cropping (composing) rectangle set the struct
+:ref:`v4l2_selection <v4l2-selection>` ``type`` field to the
+respective buffer type. Do not use multiplanar buffers. Use
+``V4L2_BUF_TYPE_VIDEO_CAPTURE`` instead of
+``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE``. Use
+``V4L2_BUF_TYPE_VIDEO_OUTPUT`` instead of
+``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``. The next step is setting the
+value of struct :ref:`v4l2_selection <v4l2-selection>` ``target`` to
+``V4L2_SEL_TGT_CROP`` (``V4L2_SEL_TGT_COMPOSE``). Please refer to table
+:ref:`v4l2-selections-common` or :ref:`selection-api` for additional
+targets. The struct :ref:`v4l2_rect <v4l2-rect>` ``r`` rectangle need
+to be set to the desired active area. Field struct
+:ref:`v4l2_selection <v4l2-selection>` ``reserved`` is ignored and
+must be filled with zeros. The driver may adjust coordinates of the
+requested rectangle. An application may introduce constraints to control
+rounding behaviour. The struct :ref:`v4l2_selection <v4l2-selection>`
+``flags`` field must be set to one of the following:
+
+- ``0`` - The driver can adjust the rectangle size freely and shall
+ choose a crop/compose rectangle as close as possible to the requested
+ one.
+
+- ``V4L2_SEL_FLAG_GE`` - The driver is not allowed to shrink the
+ rectangle. The original rectangle must lay inside the adjusted one.
+
+- ``V4L2_SEL_FLAG_LE`` - The driver is not allowed to enlarge the
+ rectangle. The adjusted rectangle must lay inside the original one.
+
+- ``V4L2_SEL_FLAG_GE | V4L2_SEL_FLAG_LE`` - The driver must choose the
+ size exactly the same as in the requested rectangle.
+
+Please refer to :ref:`sel-const-adjust`.
+
+The driver may have to adjusts the requested dimensions against hardware
+limits and other parts as the pipeline, i.e. the bounds given by the
+capture/output window or TV display. The closest possible values of
+horizontal and vertical offset and sizes are chosen according to
+following priority:
+
+1. Satisfy constraints from struct
+ :ref:`v4l2_selection <v4l2-selection>` ``flags``.
+
+2. Adjust width, height, left, and top to hardware limits and
+ alignments.
+
+3. Keep center of adjusted rectangle as close as possible to the
+ original one.
+
+4. Keep width and height as close as possible to original ones.
+
+5. Keep horizontal and vertical offset as close as possible to original
+ ones.
+
+On success the struct :ref:`v4l2_rect <v4l2-rect>` ``r`` field
+contains the adjusted rectangle. When the parameters are unsuitable the
+application may modify the cropping (composing) or image parameters and
+repeat the cycle until satisfactory parameters have been negotiated. If
+constraints flags have to be violated at then ``ERANGE`` is returned. The
+error indicates that *there exist no rectangle* that satisfies the
+constraints.
+
+Selection targets and flags are documented in
+:ref:`v4l2-selections-common`.
+
+
+.. _sel-const-adjust:
+
+.. figure:: vidioc-g-selection_files/constraints.*
+ :alt: constraints.png
+ :align: center
+
+ Size adjustments with constraint flags.
+
+ Behaviour of rectangle adjustment for different constraint flags.
+
+
+
+
+.. _v4l2-selection:
+
+.. flat-table:: struct v4l2_selection
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the buffer (from enum
+ :ref:`v4l2_buf_type <v4l2-buf-type>`).
+
+ - .. row 2
+
+ - __u32
+
+ - ``target``
+
+ - Used to select between
+ :ref:`cropping and composing rectangles <v4l2-selections-common>`.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Flags controlling the selection rectangle adjustments, refer to
+ :ref:`selection flags <v4l2-selection-flags>`.
+
+ - .. row 4
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``r``
+
+ - The selection rectangle.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved[9]``
+
+ - Reserved fields for future use. Drivers and applications must zero
+ this array.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ Given buffer type ``type`` or the selection target ``target`` is not
+ supported, or the ``flags`` argument is not valid.
+
+ERANGE
+ It is not possible to adjust struct :ref:`v4l2_rect <v4l2-rect>`
+ ``r`` rectangle to satisfy all constraints given in the ``flags``
+ argument.
+
+EBUSY
+ It is not possible to apply change of the selection rectangle at the
+ moment. Usually because streaming is in progress.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png
new file mode 100644
index 000000000000..20228d2c5504
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png
Binary files differ
diff --git a/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst
new file mode 100644
index 000000000000..76dd4ba3254f
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst
@@ -0,0 +1,276 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_SLICED_VBI_CAP:
+
+*****************************
+ioctl VIDIOC_G_SLICED_VBI_CAP
+*****************************
+
+Name
+====
+
+VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_sliced_vbi_cap *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_SLICED_VBI_CAP
+
+``argp``
+
+
+Description
+===========
+
+To find out which data services are supported by a sliced VBI capture or
+output device, applications initialize the ``type`` field of a struct
+:ref:`v4l2_sliced_vbi_cap <v4l2-sliced-vbi-cap>`, clear the
+``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The
+driver fills in the remaining fields or returns an ``EINVAL`` error code if
+the sliced VBI API is unsupported or ``type`` is invalid.
+
+Note the ``type`` field was added, and the ioctl changed from read-only
+to write-read, in Linux 2.6.19.
+
+
+.. _v4l2-sliced-vbi-cap:
+
+.. flat-table:: struct v4l2_sliced_vbi_cap
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 3 2 2 2
+
+
+ - .. row 1
+
+ - __u16
+
+ - ``service_set``
+
+ - :cspan:`2` A set of all data services supported by the driver.
+ Equal to the union of all elements of the ``service_lines`` array.
+
+ - .. row 2
+
+ - __u16
+
+ - ``service_lines``\ [2][24]
+
+ - :cspan:`2` Each element of this array contains a set of data
+ services the hardware can look for or insert into a particular
+ scan line. Data services are defined in :ref:`vbi-services`.
+ Array indices map to ITU-R line numbers (see also :ref:`vbi-525`
+ and :ref:`vbi-625`) as follows:
+
+ - .. row 3
+
+ -
+ -
+ - Element
+
+ - 525 line systems
+
+ - 625 line systems
+
+ - .. row 4
+
+ -
+ -
+ - ``service_lines``\ [0][1]
+
+ - 1
+
+ - 1
+
+ - .. row 5
+
+ -
+ -
+ - ``service_lines``\ [0][23]
+
+ - 23
+
+ - 23
+
+ - .. row 6
+
+ -
+ -
+ - ``service_lines``\ [1][1]
+
+ - 264
+
+ - 314
+
+ - .. row 7
+
+ -
+ -
+ - ``service_lines``\ [1][23]
+
+ - 286
+
+ - 336
+
+ - .. row 8
+
+ -
+
+ - .. row 9
+
+ -
+ -
+ - :cspan:`2` The number of VBI lines the hardware can capture or
+ output per frame, or the number of services it can identify on a
+ given line may be limited. For example on PAL line 16 the hardware
+ may be able to look for a VPS or Teletext signal, but not both at
+ the same time. Applications can learn about these limits using the
+ :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
+ :ref:`sliced`.
+
+ - .. row 10
+
+ -
+
+ - .. row 11
+
+ -
+ -
+ - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
+ ``service_lines``\ [1][0] to zero.
+
+ - .. row 12
+
+ - __u32
+
+ - ``type``
+
+ - Type of the data stream, see :ref:`v4l2-buf-type`. Should be
+ ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
+ ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - :cspan:`2` This array is reserved for future extensions.
+ Applications and drivers must set it to zero.
+
+
+
+.. _vbi-services:
+
+.. flat-table:: Sliced VBI services
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 2 1 1 2 2
+
+
+ - .. row 1
+
+ - Symbol
+
+ - Value
+
+ - Reference
+
+ - Lines, usually
+
+ - Payload
+
+ - .. row 2
+
+ - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
+
+ - 0x0001
+
+ - :ref:`ets300706`, :ref:`itu653`
+
+ - PAL/SECAM line 7-22, 320-335 (second field 7-22)
+
+ - Last 42 of the 45 byte Teletext packet, that is without clock
+ run-in and framing code, lsb first transmitted.
+
+ - .. row 3
+
+ - ``V4L2_SLICED_VPS``
+
+ - 0x0400
+
+ - :ref:`ets300231`
+
+ - PAL line 16
+
+ - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
+ first transmitted.
+
+ - .. row 4
+
+ - ``V4L2_SLICED_CAPTION_525``
+
+ - 0x1000
+
+ - :ref:`cea608`
+
+ - NTSC line 21, 284 (second field 21)
+
+ - Two bytes in transmission order, including parity bit, lsb first
+ transmitted.
+
+ - .. row 5
+
+ - ``V4L2_SLICED_WSS_625``
+
+ - 0x4000
+
+ - :ref:`en300294`, :ref:`itu1119`
+
+ - PAL/SECAM line 23
+
+ -
+
+ ::
+
+ Byte 0 1
+ msb lsb msb lsb
+ Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
+
+ - .. row 6
+
+ - ``V4L2_SLICED_VBI_525``
+
+ - 0x1000
+
+ - :cspan:`2` Set of services applicable to 525 line systems.
+
+ - .. row 7
+
+ - ``V4L2_SLICED_VBI_625``
+
+ - 0x4401
+
+ - :cspan:`2` Set of services applicable to 625 line systems.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The value in the ``type`` field is wrong.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-std.rst b/Documentation/media/uapi/v4l/vidioc-g-std.rst
new file mode 100644
index 000000000000..5c2b861f8d26
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-std.rst
@@ -0,0 +1,68 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_STD:
+
+********************************
+ioctl VIDIOC_G_STD, VIDIOC_S_STD
+********************************
+
+Name
+====
+
+VIDIOC_G_STD - VIDIOC_S_STD - Query or select the video standard of the current input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const v4l2_std_id *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_STD, VIDIOC_S_STD
+
+``argp``
+
+
+Description
+===========
+
+To query and select the current video standard applications use the
+:ref:`VIDIOC_G_STD <VIDIOC_G_STD>` and :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` ioctls which take a pointer to a
+:ref:`v4l2_std_id <v4l2-std-id>` type as argument. :ref:`VIDIOC_G_STD <VIDIOC_G_STD>`
+can return a single flag or a set of flags as in struct
+:ref:`v4l2_standard <v4l2-standard>` field ``id``. The flags must be
+unambiguous such that they appear in only one enumerated
+:ref:`struct v4l2_standard <v4l2-standard>` structure.
+
+:ref:`VIDIOC_S_STD <VIDIOC_G_STD>` accepts one or more flags, being a write-only ioctl it
+does not return the actual new standard as :ref:`VIDIOC_G_STD <VIDIOC_G_STD>` does. When
+no flags are given or the current input does not support the requested
+standard the driver returns an ``EINVAL`` error code. When the standard set
+is ambiguous drivers may return ``EINVAL`` or choose any of the requested
+standards. If the current input or output does not support standard
+video timings (e.g. if :ref:`VIDIOC_ENUMINPUT`
+does not set the ``V4L2_IN_CAP_STD`` flag), then ``ENODATA`` error code is
+returned.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The :ref:`VIDIOC_S_STD <VIDIOC_G_STD>` parameter was unsuitable.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-tuner.rst b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst
new file mode 100644
index 000000000000..a8d7ebd73e8a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-tuner.rst
@@ -0,0 +1,715 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_G_TUNER:
+
+************************************
+ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
+************************************
+
+Name
+====
+
+VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_tuner *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_tuner *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_G_TUNER, VIDIOC_S_TUNER
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a tuner applications initialize the ``index``
+field and zero out the ``reserved`` array of a struct
+:ref:`v4l2_tuner <v4l2-tuner>` and call the ``VIDIOC_G_TUNER`` ioctl
+with a pointer to this structure. Drivers fill the rest of the structure
+or return an ``EINVAL`` error code when the index is out of bounds. To
+enumerate all tuners applications shall begin at index zero,
+incrementing by one until the driver returns ``EINVAL``.
+
+Tuners have two writable properties, the audio mode and the radio
+frequency. To change the audio mode, applications initialize the
+``index``, ``audmode`` and ``reserved`` fields and call the
+``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
+which is determined by the current video input. Drivers may choose a
+different audio mode if the requested mode is invalid or unsupported.
+Since this is a write-only ioctl, it does not return the actually
+selected audio mode.
+
+:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
+``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
+to zero. The term 'tuner' means SDR receiver in this context.
+
+To change the radio frequency the
+:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
+
+
+.. _v4l2-tuner:
+
+.. flat-table:: struct v4l2_tuner
+ :header-rows: 0
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - :cspan:`1` Identifies the tuner, set by the application.
+
+ - .. row 2
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - :cspan:`1`
+
+ Name of the tuner, a NUL-terminated ASCII string. This information
+ is intended for the user.
+
+ - .. row 3
+
+ - __u32
+
+ - ``type``
+
+ - :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``capability``
+
+ - :cspan:`1`
+
+ Tuner capability flags, see :ref:`tuner-capability`. Audio flags
+ indicate the ability to decode audio subprograms. They will *not*
+ change, for example with the current video standard.
+
+ When the structure refers to a radio tuner the
+ ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
+ ``V4L2_TUNER_CAP_NORM`` flags can't be used.
+
+ If multiple frequency bands are supported, then ``capability`` is
+ the union of all ``capability`` fields of each struct
+ :ref:`v4l2_frequency_band <v4l2-frequency-band>`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``rangelow``
+
+ - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
+ if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
+ of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
+ is set, in units of 1 Hz. If multiple frequency bands are
+ supported, then ``rangelow`` is the lowest frequency of all the
+ frequency bands.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangehigh``
+
+ - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
+ or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
+ units of 62.5 Hz, or if the ``capability`` flag
+ ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
+ frequency bands are supported, then ``rangehigh`` is the highest
+ frequency of all the frequency bands.
+
+ - .. row 7
+
+ - __u32
+
+ - ``rxsubchans``
+
+ - :cspan:`1`
+
+ Some tuners or audio decoders can determine the received audio
+ subprograms by analyzing audio carriers, pilot tones or other
+ indicators. To pass this information drivers set flags defined in
+ :ref:`tuner-rxsubchans` in this field. For example:
+
+ - .. row 8
+
+ -
+ -
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - receiving mono audio
+
+ - .. row 9
+
+ -
+ -
+ - ``STEREO | SAP``
+
+ - receiving stereo audio and a secondary audio program
+
+ - .. row 10
+
+ -
+ -
+ - ``MONO | STEREO``
+
+ - receiving mono or stereo audio, the hardware cannot distinguish
+
+ - .. row 11
+
+ -
+ -
+ - ``LANG1 | LANG2``
+
+ - receiving bilingual audio
+
+ - .. row 12
+
+ -
+ -
+ - ``MONO | STEREO | LANG1 | LANG2``
+
+ - receiving mono, stereo or bilingual audio
+
+ - .. row 13
+
+ -
+ -
+ - :cspan:`1`
+
+ When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
+ ``_SAP`` flag is cleared in the ``capability`` field, the
+ corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
+
+ This field is valid only if this is the tuner of the current video
+ input, or when the structure refers to a radio tuner.
+
+ - .. row 14
+
+ - __u32
+
+ - ``audmode``
+
+ - :cspan:`1`
+
+ The selected audio mode, see :ref:`tuner-audmode` for valid
+ values. The audio mode does not affect audio subprogram detection,
+ and like a :ref:`control` it does not automatically
+ change unless the requested mode is invalid or unsupported. See
+ :ref:`tuner-matrix` for possible results when the selected and
+ received audio programs do not match.
+
+ Currently this is the only field of struct
+ :ref:`struct v4l2_tuner <v4l2-tuner>` applications can change.
+
+ - .. row 15
+
+ - __u32
+
+ - ``signal``
+
+ - :cspan:`1` The signal strength if known, ranging from 0 to
+ 65535. Higher values indicate a better signal.
+
+ - .. row 16
+
+ - __s32
+
+ - ``afc``
+
+ - :cspan:`1` Automatic frequency control: When the ``afc`` value
+ is negative, the frequency is too low, when positive too high.
+
+ - .. row 17
+
+ - __u32
+
+ - ``reserved``\ [4]
+
+ - :cspan:`1` Reserved for future extensions. Drivers and
+ applications must set the array to zero.
+
+
+
+.. _v4l2-tuner-type:
+
+.. flat-table:: enum v4l2_tuner_type
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_RADIO``
+
+ - 1
+
+ -
+
+ - .. row 2
+
+ - ``V4L2_TUNER_ANALOG_TV``
+
+ - 2
+
+ -
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SDR``
+
+ - 4
+
+ -
+
+ - .. row 4
+
+ - ``V4L2_TUNER_RF``
+
+ - 5
+
+ -
+
+
+
+.. _tuner-capability:
+
+.. flat-table:: Tuner and Modulator Capability Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_CAP_LOW``
+
+ - 0x0001
+
+ - When set, tuning frequencies are expressed in units of 62.5 Hz
+ instead of 62.5 kHz.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_CAP_NORM``
+
+ - 0x0002
+
+ - This is a multi-standard tuner; the video standard can or must be
+ switched. (B/G PAL tuners for example are typically not considered
+ multi-standard because the video standard is automatically
+ determined from the frequency band.) The set of supported video
+ standards is available from the struct
+ :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the
+ description of ioctl :ref:`VIDIOC_ENUMINPUT`
+ for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
+ capability.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
+
+ - 0x0004
+
+ - If set, then this tuner supports the hardware seek functionality
+ where the seek stops when it reaches the end of the frequency
+ range.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
+
+ - 0x0008
+
+ - If set, then this tuner supports the hardware seek functionality
+ where the seek wraps around when it reaches the end of the
+ frequency range.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_CAP_STEREO``
+
+ - 0x0010
+
+ - Stereo audio reception is supported.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_CAP_LANG1``
+
+ - 0x0040
+
+ - Reception of the primary language of a bilingual audio program is
+ supported. Bilingual audio is a feature of two-channel systems,
+ transmitting the primary language monaural on the main audio
+ carrier and a secondary language monaural on a second carrier.
+ Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
+
+ - .. row 7
+
+ - ``V4L2_TUNER_CAP_LANG2``
+
+ - 0x0020
+
+ - Reception of the secondary language of a bilingual audio program
+ is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
+ capability.
+
+ - .. row 8
+
+ - ``V4L2_TUNER_CAP_SAP``
+
+ - 0x0020
+
+ - Reception of a secondary audio program is supported. This is a
+ feature of the BTSC system which accompanies the NTSC video
+ standard. Two audio carriers are available for mono or stereo
+ transmissions of a primary language, and an independent third
+ carrier for a monaural secondary language. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
+
+ Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags
+ are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
+ supports the ``V4L2_STD_NTSC_M`` video standard.
+
+ - .. row 9
+
+ - ``V4L2_TUNER_CAP_RDS``
+
+ - 0x0080
+
+ - RDS capture is supported. This capability is only valid for radio
+ tuners.
+
+ - .. row 10
+
+ - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
+
+ - 0x0100
+
+ - The RDS data is passed as unparsed RDS blocks.
+
+ - .. row 11
+
+ - ``V4L2_TUNER_CAP_RDS_CONTROLS``
+
+ - 0x0200
+
+ - The RDS data is parsed by the hardware and set via controls.
+
+ - .. row 12
+
+ - ``V4L2_TUNER_CAP_FREQ_BANDS``
+
+ - 0x0400
+
+ - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
+ ioctl can be used to enumerate the available frequency bands.
+
+ - .. row 13
+
+ - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
+
+ - 0x0800
+
+ - The range to search when using the hardware seek functionality is
+ programmable, see
+ :ref:`VIDIOC_S_HW_FREQ_SEEK` for
+ details.
+
+ - .. row 14
+
+ - ``V4L2_TUNER_CAP_1HZ``
+
+ - 0x1000
+
+ - When set, tuning frequencies are expressed in units of 1 Hz
+ instead of 62.5 kHz.
+
+
+
+.. _tuner-rxsubchans:
+
+.. flat-table:: Tuner Audio Reception Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_SUB_MONO``
+
+ - 0x0001
+
+ - The tuner receives a mono audio signal.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_SUB_STEREO``
+
+ - 0x0002
+
+ - The tuner receives a stereo audio signal.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_SUB_LANG1``
+
+ - 0x0008
+
+ - The tuner receives the primary language of a bilingual audio
+ signal. Drivers must clear this flag when the current video
+ standard is ``V4L2_STD_NTSC_M``.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_SUB_LANG2``
+
+ - 0x0004
+
+ - The tuner receives the secondary language of a bilingual audio
+ signal (or a second audio program).
+
+ - .. row 5
+
+ - ``V4L2_TUNER_SUB_SAP``
+
+ - 0x0004
+
+ - The tuner receives a Second Audio Program. Note the
+ ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are
+ synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current
+ video standard is ``V4L2_STD_NTSC_M``.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_SUB_RDS``
+
+ - 0x0010
+
+ - The tuner receives an RDS channel.
+
+
+
+.. _tuner-audmode:
+
+.. flat-table:: Tuner Audio Modes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_TUNER_MODE_MONO``
+
+ - 0
+
+ - Play mono audio. When the tuner receives a stereo signal this a
+ down-mix of the left and right channel. When the tuner receives a
+ bilingual or SAP signal this mode selects the primary language.
+
+ - .. row 2
+
+ - ``V4L2_TUNER_MODE_STEREO``
+
+ - 1
+
+ - Play stereo audio. When the tuner receives bilingual audio it may
+ play different languages on the left and right channel or the
+ primary language is played on both channels.
+
+ Playing different languages in this mode is deprecated. New
+ drivers should do this only in ``MODE_LANG1_LANG2``.
+
+ When the tuner receives no stereo signal or does not support
+ stereo reception the driver shall fall back to ``MODE_MONO``.
+
+ - .. row 3
+
+ - ``V4L2_TUNER_MODE_LANG1``
+
+ - 3
+
+ - Play the primary language, mono or stereo. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
+
+ - .. row 4
+
+ - ``V4L2_TUNER_MODE_LANG2``
+
+ - 2
+
+ - Play the secondary language, mono. When the tuner receives no
+ bilingual audio or SAP, or their reception is not supported the
+ driver shall fall back to mono or stereo mode. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
+
+ - .. row 5
+
+ - ``V4L2_TUNER_MODE_SAP``
+
+ - 2
+
+ - Play the Second Audio Program. When the tuner receives no
+ bilingual audio or SAP, or their reception is not supported the
+ driver shall fall back to mono or stereo mode. Only
+ ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the
+ ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are
+ synonyms.
+
+ - .. row 6
+
+ - ``V4L2_TUNER_MODE_LANG1_LANG2``
+
+ - 4
+
+ - Play the primary language on the left channel, the secondary
+ language on the right channel. When the tuner receives no
+ bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
+ ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
+ mode.
+
+
+
+.. _tuner-matrix:
+
+.. flat-table:: Tuner Audio Matrix
+ :header-rows: 2
+ :stub-columns: 0
+
+
+ - .. row 1
+
+ -
+ - :cspan:`5` Selected ``V4L2_TUNER_MODE_``
+
+ - .. row 2
+
+ - Received ``V4L2_TUNER_SUB_``
+
+ - ``MONO``
+
+ - ``STEREO``
+
+ - ``LANG1``
+
+ - ``LANG2 = SAP``
+
+ - ``LANG1_LANG2``\ [1]_
+
+ - .. row 3
+
+ - ``MONO``
+
+ - Mono
+
+ - Mono/Mono
+
+ - Mono
+
+ - Mono
+
+ - Mono/Mono
+
+ - .. row 4
+
+ - ``MONO | SAP``
+
+ - Mono
+
+ - Mono/Mono
+
+ - Mono
+
+ - SAP
+
+ - Mono/SAP (preferred) or Mono/Mono
+
+ - .. row 5
+
+ - ``STEREO``
+
+ - L+R
+
+ - L/R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - L/R (preferred) or L+R/L+R
+
+ - .. row 6
+
+ - ``STEREO | SAP``
+
+ - L+R
+
+ - L/R
+
+ - Stereo L/R (preferred) or Mono L+R
+
+ - SAP
+
+ - L+R/SAP (preferred) or L/R or L+R/L+R
+
+ - .. row 7
+
+ - ``LANG1 | LANG2``
+
+ - Language 1
+
+ - Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1
+
+ - Language 1
+
+ - Language 2
+
+ - Lang1/Lang2 (preferred) or Lang1/Lang1
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of
+ bounds.
+
+.. [1]
+ This mode has been added in Linux 2.6.17 and may not be supported by
+ older drivers.
+
+.. [2]
+ Playback of both languages in ``MODE_STEREO`` is deprecated. In the
+ future drivers should produce only the primary language in this mode.
+ Applications should request ``MODE_LANG1_LANG2`` to record both
+ languages or a stereo signal.
diff --git a/Documentation/media/uapi/v4l/vidioc-log-status.rst b/Documentation/media/uapi/v4l/vidioc-log-status.rst
new file mode 100644
index 000000000000..66fc352c0ffa
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-log-status.rst
@@ -0,0 +1,46 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_LOG_STATUS:
+
+***********************
+ioctl VIDIOC_LOG_STATUS
+***********************
+
+Name
+====
+
+VIDIOC_LOG_STATUS - Log driver status information
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request )
+
+
+Arguments
+=========
+
+
+
+Description
+===========
+
+As the video/audio devices become more complicated it becomes harder to
+debug problems. When this ioctl is called the driver will output the
+current device status to the kernel log. This is particular useful when
+dealing with problems like no sound, no video and incorrectly tuned
+channels. Also many modern devices autodetect video and audio standards
+and this ioctl will report what the device thinks what the standard is.
+Mismatches may give an indication where the problem is.
+
+This ioctl is optional and not all drivers support it. It was introduced
+in Linux 2.6.15.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-overlay.rst b/Documentation/media/uapi/v4l/vidioc-overlay.rst
new file mode 100644
index 000000000000..191dbc144ef7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-overlay.rst
@@ -0,0 +1,55 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_OVERLAY:
+
+********************
+ioctl VIDIOC_OVERLAY
+********************
+
+Name
+====
+
+VIDIOC_OVERLAY - Start or stop video overlay
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, const int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_OVERLAY
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is part of the :ref:`video overlay <overlay>` I/O method.
+Applications call :ref:`VIDIOC_OVERLAY` to start or stop the overlay. It
+takes a pointer to an integer which must be set to zero by the
+application to stop overlay, to one to start.
+
+Drivers do not support :ref:`VIDIOC_STREAMON` or
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` with
+``V4L2_BUF_TYPE_VIDEO_OVERLAY``.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The overlay parameters have not been set up. See :ref:`overlay`
+ for the necessary steps.
diff --git a/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst
new file mode 100644
index 000000000000..79076dff46fd
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-prepare-buf.rst
@@ -0,0 +1,62 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_PREPARE_BUF:
+
+************************
+ioctl VIDIOC_PREPARE_BUF
+************************
+
+Name
+====
+
+VIDIOC_PREPARE_BUF - Prepare a buffer for I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_PREPARE_BUF
+
+``argp``
+
+
+Description
+===========
+
+Applications can optionally call the :ref:`VIDIOC_PREPARE_BUF` ioctl to
+pass ownership of the buffer to the driver before actually enqueuing it,
+using the :ref:`VIDIOC_QBUF` ioctl, and to prepare it for future I/O. Such
+preparations may include cache invalidation or cleaning. Performing them
+in advance saves time during the actual I/O. In case such cache
+operations are not required, the application can use one of
+``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` and
+``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` flags to skip the respective step.
+
+The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
+:ref:`buffer`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ File I/O is in progress.
+
+EINVAL
+ The buffer ``type`` is not supported, or the ``index`` is out of
+ bounds, or no buffers have been allocated yet, or the ``userptr`` or
+ ``length`` are invalid.
diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
new file mode 100644
index 000000000000..9870d243131a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
@@ -0,0 +1,150 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QBUF:
+
+*******************************
+ioctl VIDIOC_QBUF, VIDIOC_DQBUF
+*******************************
+
+Name
+====
+
+VIDIOC_QBUF - VIDIOC_DQBUF - Exchange a buffer with the driver
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QBUF, VIDIOC_DQBUF
+
+``argp``
+
+
+Description
+===========
+
+Applications call the ``VIDIOC_QBUF`` ioctl to enqueue an empty
+(capturing) or filled (output) buffer in the driver's incoming queue.
+The semantics depend on the selected I/O method.
+
+To enqueue a buffer applications set the ``type`` field of a struct
+:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
+previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
+and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+Applications must also set the ``index`` field. Valid index numbers
+range from zero to the number of buffers allocated with
+:ref:`VIDIOC_REQBUFS` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. The contents of the struct :ref:`struct v4l2_buffer <v4l2-buffer>` returned
+by a :ref:`VIDIOC_QUERYBUF` ioctl will do as well.
+When the buffer is intended for output (``type`` is
+``V4L2_BUF_TYPE_VIDEO_OUTPUT``, ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE``,
+or ``V4L2_BUF_TYPE_VBI_OUTPUT``) applications must also initialize the
+``bytesused``, ``field`` and ``timestamp`` fields, see :ref:`buffer`
+for details. Applications must also set ``flags`` to 0. The
+``reserved2`` and ``reserved`` fields must be set to 0. When using the
+:ref:`multi-planar API <planar-apis>`, the ``m.planes`` field must
+contain a userspace pointer to a filled-in array of struct
+:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field must be set
+to the number of elements in that array.
+
+To enqueue a :ref:`memory mapped <mmap>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_MMAP``. When ``VIDIOC_QBUF`` is called
+with a pointer to this structure the driver sets the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears
+the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an
+EINVAL error code.
+
+To enqueue a :ref:`user pointer <userp>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
+the address of the buffer and ``length`` to its size. When the
+multi-planar API is used, ``m.userptr`` and ``length`` members of the
+passed array of struct :ref:`v4l2_plane <v4l2-plane>` have to be used
+instead. When ``VIDIOC_QBUF`` is called with a pointer to this structure
+the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
+``flags`` field, or it returns an error code. This ioctl locks the
+memory pages of the buffer in physical memory, they cannot be swapped
+out to disk. Buffers remain locked until dequeued, until the
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
+:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
+device is closed.
+
+To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the
+``memory`` field to ``V4L2_MEMORY_DMABUF`` and the ``m.fd`` field to a
+file descriptor associated with a DMABUF buffer. When the multi-planar
+API is used the ``m.fd`` fields of the passed array of struct
+:ref:`v4l2_plane <v4l2-plane>` have to be used instead. When
+``VIDIOC_QBUF`` is called with a pointer to this structure the driver
+sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the
+``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the
+``flags`` field, or it returns an error code. This ioctl locks the
+buffer. Locking a buffer means passing it to a driver for a hardware
+access (usually DMA). If an application accesses (reads/writes) a locked
+buffer then the result is undefined. Buffers remain locked until
+dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or
+:ref:`VIDIOC_REQBUFS` ioctl is called, or until the
+device is closed.
+
+Applications call the ``VIDIOC_DQBUF`` ioctl to dequeue a filled
+(capturing) or displayed (output) buffer from the driver's outgoing
+queue. They just set the ``type``, ``memory`` and ``reserved`` fields of
+a struct :ref:`v4l2_buffer <v4l2-buffer>` as above, when
+``VIDIOC_DQBUF`` is called with a pointer to this structure the driver
+fills the remaining fields or returns an error code. The driver may also
+set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a
+non-critical (recoverable) streaming error. In such case the application
+may continue as normal, but should be aware that data in the dequeued
+buffer might be corrupted. When using the multi-planar API, the planes
+array must be passed in as well.
+
+By default ``VIDIOC_DQBUF`` blocks when no buffer is in the outgoing
+queue. When the ``O_NONBLOCK`` flag was given to the
+:ref:`open() <func-open>` function, ``VIDIOC_DQBUF`` returns
+immediately with an ``EAGAIN`` error code when no buffer is available.
+
+The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
+:ref:`buffer`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EAGAIN
+ Non-blocking I/O has been selected using ``O_NONBLOCK`` and no
+ buffer was in the outgoing queue.
+
+EINVAL
+ The buffer ``type`` is not supported, or the ``index`` is out of
+ bounds, or no buffers have been allocated yet, or the ``userptr`` or
+ ``length`` are invalid.
+
+EIO
+ ``VIDIOC_DQBUF`` failed due to an internal error. Can also indicate
+ temporary problems like signal loss. Note the driver might dequeue
+ an (empty) buffer despite returning an error, or even stop
+ capturing. Reusing such buffer may be unsafe though and its details
+ (e.g. ``index``) may not be returned either. It is recommended that
+ drivers indicate recoverable errors by setting the
+ ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the
+ application should be able to safely reuse the buffer and continue
+ streaming.
+
+EPIPE
+ ``VIDIOC_DQBUF`` returns this on an empty capture queue for mem2mem
+ codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already
+ dequeued and no new buffers are expected to become available.
diff --git a/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst
new file mode 100644
index 000000000000..338b80df5b9b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst
@@ -0,0 +1,83 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERY_DV_TIMINGS:
+
+*****************************
+ioctl VIDIOC_QUERY_DV_TIMINGS
+*****************************
+
+Name
+====
+
+VIDIOC_QUERY_DV_TIMINGS - VIDIOC_SUBDEV_QUERY_DV_TIMINGS - Sense the DV preset received by the current input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_dv_timings *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERY_DV_TIMINGS, VIDIOC_SUBDEV_QUERY_DV_TIMINGS
+
+``argp``
+
+
+Description
+===========
+
+The hardware may be able to detect the current DV timings automatically,
+similar to sensing the video standard. To do so, applications call
+:ref:`VIDIOC_QUERY_DV_TIMINGS` with a pointer to a struct
+:ref:`v4l2_dv_timings <v4l2-dv-timings>`. Once the hardware detects
+the timings, it will fill in the timings structure.
+
+Please note that drivers shall *not* switch timings automatically if new
+timings are detected. Instead, drivers should send the
+``V4L2_EVENT_SOURCE_CHANGE`` event (if they support this) and expect
+that userspace will take action by calling :ref:`VIDIOC_QUERY_DV_TIMINGS`.
+The reason is that new timings usually mean different buffer sizes as
+well, and you cannot change buffer sizes on the fly. In general,
+applications that receive the Source Change event will have to call
+:ref:`VIDIOC_QUERY_DV_TIMINGS`, and if the detected timings are valid they
+will have to stop streaming, set the new timings, allocate new buffers
+and start streaming again.
+
+If the timings could not be detected because there was no signal, then
+ENOLINK is returned. If a signal was detected, but it was unstable and
+the receiver could not lock to the signal, then ``ENOLCK`` is returned. If
+the receiver could lock to the signal, but the format is unsupported
+(e.g. because the pixelclock is out of range of the hardware
+capabilities), then the driver fills in whatever timings it could find
+and returns ``ERANGE``. In that case the application can call
+:ref:`VIDIOC_DV_TIMINGS_CAP` to compare the
+found timings with the hardware's capabilities in order to give more
+precise feedback to the user.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+ENODATA
+ Digital video timings are not supported for this input or output.
+
+ENOLINK
+ No timings could be detected because no signal was found.
+
+ENOLCK
+ The signal was unstable and the hardware could not lock on to it.
+
+ERANGE
+ Timings were found, but they are out of range of the hardware
+ capabilities.
diff --git a/Documentation/media/uapi/v4l/vidioc-querybuf.rst b/Documentation/media/uapi/v4l/vidioc-querybuf.rst
new file mode 100644
index 000000000000..32af6f7b5060
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-querybuf.rst
@@ -0,0 +1,81 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYBUF:
+
+*********************
+ioctl VIDIOC_QUERYBUF
+*********************
+
+Name
+====
+
+VIDIOC_QUERYBUF - Query the status of a buffer
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_buffer *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYBUF
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is part of the :ref:`streaming <mmap>` I/O method. It can
+be used to query the status of a buffer at any time after buffers have
+been allocated with the :ref:`VIDIOC_REQBUFS` ioctl.
+
+Applications set the ``type`` field of a struct
+:ref:`v4l2_buffer <v4l2-buffer>` to the same buffer type as was
+previously used with struct :ref:`v4l2_format <v4l2-format>` ``type``
+and struct :ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``,
+and the ``index`` field. Valid index numbers range from zero to the
+number of buffers allocated with
+:ref:`VIDIOC_REQBUFS` (struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``count``) minus
+one. The ``reserved`` and ``reserved2`` fields must be set to 0. When
+using the :ref:`multi-planar API <planar-apis>`, the ``m.planes``
+field must contain a userspace pointer to an array of struct
+:ref:`v4l2_plane <v4l2-plane>` and the ``length`` field has to be set
+to the number of elements in that array. After calling
+:ref:`VIDIOC_QUERYBUF` with a pointer to this structure drivers return an
+error code or fill the rest of the structure.
+
+In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``,
+``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and
+``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``memory`` field will be
+set to the current I/O method. For the single-planar API, the
+``m.offset`` contains the offset of the buffer from the start of the
+device memory, the ``length`` field its size. For the multi-planar API,
+fields ``m.mem_offset`` and ``length`` in the ``m.planes`` array
+elements will be used instead and the ``length`` field of struct
+:ref:`v4l2_buffer <v4l2-buffer>` is set to the number of filled-in
+array elements. The driver may or may not set the remaining fields and
+flags, they are meaningless in this context.
+
+The :ref:`struct v4l2_buffer <v4l2-buffer>` structure is specified in
+:ref:`buffer`.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The buffer ``type`` is not supported, or the ``index`` is out of
+ bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-querycap.rst b/Documentation/media/uapi/v4l/vidioc-querycap.rst
new file mode 100644
index 000000000000..f0271f834ac1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-querycap.rst
@@ -0,0 +1,434 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYCAP:
+
+*********************
+ioctl VIDIOC_QUERYCAP
+*********************
+
+Name
+====
+
+VIDIOC_QUERYCAP - Query device capabilities
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_capability *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYCAP
+
+``argp``
+
+
+Description
+===========
+
+All V4L2 devices support the ``VIDIOC_QUERYCAP`` ioctl. It is used to
+identify kernel devices compatible with this specification and to obtain
+information about driver and hardware capabilities. The ioctl takes a
+pointer to a struct :ref:`v4l2_capability <v4l2-capability>` which is
+filled by the driver. When the driver is not compatible with this
+specification the ioctl returns an ``EINVAL`` error code.
+
+
+.. _v4l2-capability:
+
+.. flat-table:: struct v4l2_capability
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u8
+
+ - ``driver``\ [16]
+
+ - Name of the driver, a unique NUL-terminated ASCII string. For
+ example: "bttv". Driver specific applications can use this
+ information to verify the driver identity. It is also useful to
+ work around known bugs, or to identify drivers in error reports.
+
+ Storing strings in fixed sized arrays is bad practice but
+ unavoidable here. Drivers and applications should take precautions
+ to never read or write beyond the end of the array and to make
+ sure the strings are properly NUL-terminated.
+
+ - .. row 2
+
+ - __u8
+
+ - ``card``\ [32]
+
+ - Name of the device, a NUL-terminated UTF-8 string. For example:
+ "Yoyodyne TV/FM". One driver may support different brands or
+ models of video hardware. This information is intended for users,
+ for example in a menu of available devices. Since multiple TV
+ cards of the same brand may be installed which are supported by
+ the same driver, this name should be combined with the character
+ device file name (e. g. ``/dev/video2``) or the ``bus_info``
+ string to avoid ambiguities.
+
+ - .. row 3
+
+ - __u8
+
+ - ``bus_info``\ [32]
+
+ - Location of the device in the system, a NUL-terminated ASCII
+ string. For example: "PCI:0000:05:06.0". This information is
+ intended for users, to distinguish multiple identical devices. If
+ no such information is available the field must simply count the
+ devices controlled by the driver ("platform:vivi-000"). The
+ bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI
+ Express boards, "usb-" for USB devices, "I2C:" for i2c devices,
+ "ISA:" for ISA devices, "parport" for parallel port devices and
+ "platform:" for platform devices.
+
+ - .. row 4
+
+ - __u32
+
+ - ``version``
+
+ - Version number of the driver.
+
+ Starting with kernel 3.1, the version reported is provided by the
+ V4L2 subsystem following the kernel numbering scheme. However, it
+ may not always return the same version as the kernel if, for
+ example, a stable or distribution-modified kernel uses the V4L2
+ stack from a newer kernel.
+
+ The version number is formatted using the ``KERNEL_VERSION()``
+ macro:
+
+ - .. row 5
+
+ - :cspan:`2`
+
+
+ .. code-block:: c
+
+ #define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
+
+ __u32 version = KERNEL_VERSION(0, 8, 1);
+
+ printf ("Version: %u.%u.%u\\n",
+ (version >> 16) & 0xFF,
+ (version >> 8) & 0xFF,
+ version & 0xFF);
+
+ - .. row 6
+
+ - __u32
+
+ - ``capabilities``
+
+ - Available capabilities of the physical device as a whole, see
+ :ref:`device-capabilities`. The same physical device can export
+ multiple devices in /dev (e.g. /dev/videoX, /dev/vbiY and
+ /dev/radioZ). The ``capabilities`` field should contain a union of
+ all capabilities available around the several V4L2 devices
+ exported to userspace. For all those devices the ``capabilities``
+ field returns the same set of capabilities. This allows
+ applications to open just one of the devices (typically the video
+ device) and discover whether video, vbi and/or radio are also
+ supported.
+
+ - .. row 7
+
+ - __u32
+
+ - ``device_caps``
+
+ - Device capabilities of the opened device, see
+ :ref:`device-capabilities`. Should contain the available
+ capabilities of that specific device node. So, for example,
+ ``device_caps`` of a radio device will only contain radio related
+ capabilities and no video or vbi capabilities. This field is only
+ set if the ``capabilities`` field contains the
+ ``V4L2_CAP_DEVICE_CAPS`` capability. Only the ``capabilities``
+ field can have the ``V4L2_CAP_DEVICE_CAPS`` capability,
+ ``device_caps`` will never set ``V4L2_CAP_DEVICE_CAPS``.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [3]
+
+ - Reserved for future extensions. Drivers must set this array to
+ zero.
+
+
+
+.. _device-capabilities:
+
+.. flat-table:: Device Capabilities Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CAP_VIDEO_CAPTURE``
+
+ - 0x00000001
+
+ - The device supports the single-planar API through the
+ :ref:`Video Capture <capture>` interface.
+
+ - .. row 2
+
+ - ``V4L2_CAP_VIDEO_CAPTURE_MPLANE``
+
+ - 0x00001000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the :ref:`Video Capture <capture>` interface.
+
+ - .. row 3
+
+ - ``V4L2_CAP_VIDEO_OUTPUT``
+
+ - 0x00000002
+
+ - The device supports the single-planar API through the
+ :ref:`Video Output <output>` interface.
+
+ - .. row 4
+
+ - ``V4L2_CAP_VIDEO_OUTPUT_MPLANE``
+
+ - 0x00002000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the :ref:`Video Output <output>` interface.
+
+ - .. row 5
+
+ - ``V4L2_CAP_VIDEO_M2M``
+
+ - 0x00004000
+
+ - The device supports the single-planar API through the Video
+ Memory-To-Memory interface.
+
+ - .. row 6
+
+ - ``V4L2_CAP_VIDEO_M2M_MPLANE``
+
+ - 0x00008000
+
+ - The device supports the :ref:`multi-planar API <planar-apis>`
+ through the Video Memory-To-Memory interface.
+
+ - .. row 7
+
+ - ``V4L2_CAP_VIDEO_OVERLAY``
+
+ - 0x00000004
+
+ - The device supports the :ref:`Video Overlay <overlay>`
+ interface. A video overlay device typically stores captured images
+ directly in the video memory of a graphics card, with hardware
+ clipping and scaling.
+
+ - .. row 8
+
+ - ``V4L2_CAP_VBI_CAPTURE``
+
+ - 0x00000010
+
+ - The device supports the :ref:`Raw VBI Capture <raw-vbi>`
+ interface, providing Teletext and Closed Caption data.
+
+ - .. row 9
+
+ - ``V4L2_CAP_VBI_OUTPUT``
+
+ - 0x00000020
+
+ - The device supports the :ref:`Raw VBI Output <raw-vbi>`
+ interface.
+
+ - .. row 10
+
+ - ``V4L2_CAP_SLICED_VBI_CAPTURE``
+
+ - 0x00000040
+
+ - The device supports the :ref:`Sliced VBI Capture <sliced>`
+ interface.
+
+ - .. row 11
+
+ - ``V4L2_CAP_SLICED_VBI_OUTPUT``
+
+ - 0x00000080
+
+ - The device supports the :ref:`Sliced VBI Output <sliced>`
+ interface.
+
+ - .. row 12
+
+ - ``V4L2_CAP_RDS_CAPTURE``
+
+ - 0x00000100
+
+ - The device supports the :ref:`RDS <rds>` capture interface.
+
+ - .. row 13
+
+ - ``V4L2_CAP_VIDEO_OUTPUT_OVERLAY``
+
+ - 0x00000200
+
+ - The device supports the :ref:`Video Output Overlay <osd>` (OSD)
+ interface. Unlike the *Video Overlay* interface, this is a
+ secondary function of video output devices and overlays an image
+ onto an outgoing video signal. When the driver sets this flag, it
+ must clear the ``V4L2_CAP_VIDEO_OVERLAY`` flag and vice
+ versa. [1]_
+
+ - .. row 14
+
+ - ``V4L2_CAP_HW_FREQ_SEEK``
+
+ - 0x00000400
+
+ - The device supports the
+ :ref:`VIDIOC_S_HW_FREQ_SEEK` ioctl
+ for hardware frequency seeking.
+
+ - .. row 15
+
+ - ``V4L2_CAP_RDS_OUTPUT``
+
+ - 0x00000800
+
+ - The device supports the :ref:`RDS <rds>` output interface.
+
+ - .. row 16
+
+ - ``V4L2_CAP_TUNER``
+
+ - 0x00010000
+
+ - The device has some sort of tuner to receive RF-modulated video
+ signals. For more information about tuner programming see
+ :ref:`tuner`.
+
+ - .. row 17
+
+ - ``V4L2_CAP_AUDIO``
+
+ - 0x00020000
+
+ - The device has audio inputs or outputs. It may or may not support
+ audio recording or playback, in PCM or compressed formats. PCM
+ audio support must be implemented as ALSA or OSS interface. For
+ more information on audio inputs and outputs see :ref:`audio`.
+
+ - .. row 18
+
+ - ``V4L2_CAP_RADIO``
+
+ - 0x00040000
+
+ - This is a radio receiver.
+
+ - .. row 19
+
+ - ``V4L2_CAP_MODULATOR``
+
+ - 0x00080000
+
+ - The device has some sort of modulator to emit RF-modulated
+ video/audio signals. For more information about modulator
+ programming see :ref:`tuner`.
+
+ - .. row 20
+
+ - ``V4L2_CAP_SDR_CAPTURE``
+
+ - 0x00100000
+
+ - The device supports the :ref:`SDR Capture <sdr>` interface.
+
+ - .. row 21
+
+ - ``V4L2_CAP_EXT_PIX_FORMAT``
+
+ - 0x00200000
+
+ - The device supports the struct
+ :ref:`v4l2_pix_format <v4l2-pix-format>` extended fields.
+
+ - .. row 22
+
+ - ``V4L2_CAP_SDR_OUTPUT``
+
+ - 0x00400000
+
+ - The device supports the :ref:`SDR Output <sdr>` interface.
+
+ - .. row 23
+
+ - ``V4L2_CAP_READWRITE``
+
+ - 0x01000000
+
+ - The device supports the :ref:`read() <rw>` and/or
+ :ref:`write() <rw>` I/O methods.
+
+ - .. row 24
+
+ - ``V4L2_CAP_ASYNCIO``
+
+ - 0x02000000
+
+ - The device supports the :ref:`asynchronous <async>` I/O methods.
+
+ - .. row 25
+
+ - ``V4L2_CAP_STREAMING``
+
+ - 0x04000000
+
+ - The device supports the :ref:`streaming <mmap>` I/O method.
+
+ - .. row 26
+
+ - ``V4L2_CAP_DEVICE_CAPS``
+
+ - 0x80000000
+
+ - The driver fills the ``device_caps`` field. This capability can
+ only appear in the ``capabilities`` field and never in the
+ ``device_caps`` field.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+.. [1]
+ The struct :ref:`v4l2_framebuffer <v4l2-framebuffer>` lacks an
+ enum :ref:`v4l2_buf_type <v4l2-buf-type>` field, therefore the
+ type of overlay is implied by the driver capabilities.
diff --git a/Documentation/media/uapi/v4l/vidioc-queryctrl.rst b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
new file mode 100644
index 000000000000..0f27e712eec9
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-queryctrl.rst
@@ -0,0 +1,780 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYCTRL:
+
+*******************************************************************
+ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU
+*******************************************************************
+
+Name
+====
+
+VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_queryctrl *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_query_ext_ctrl *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_querymenu *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU
+
+``argp``
+
+
+Description
+===========
+
+To query the attributes of a control applications set the ``id`` field
+of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the
+``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver
+fills the rest of the structure or returns an ``EINVAL`` error code when the
+``id`` is invalid.
+
+It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL``
+with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and
+exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in
+this range is not supported. Further applications can enumerate private
+controls, which are not defined in this specification, by starting at
+``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver
+returns ``EINVAL``.
+
+In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag
+in the ``flags`` field this control is permanently disabled and should
+be ignored by the application. [1]_
+
+When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the
+driver returns the next supported non-compound control, or ``EINVAL`` if
+there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag
+can be specified to enumerate all compound controls (i.e. controls with
+type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words
+controls that contain more than one value). Specify both
+``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in
+order to enumerate all controls, compound or not. Drivers which do not
+support these flags yet always return ``EINVAL``.
+
+The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better
+support controls that can use compound types, and to expose additional
+control information that cannot be returned in struct
+:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full.
+
+``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as
+``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed
+as well.
+
+Additional information is required for menu controls: the names of the
+menu items. To query them applications set the ``id`` and ``index``
+fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the
+``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver
+fills the rest of the structure or returns an ``EINVAL`` error code when the
+``id`` or ``index`` is invalid. Menu items are enumerated by calling
+``VIDIOC_QUERYMENU`` with successive ``index`` values from struct
+:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``,
+inclusive. Note that it is possible for ``VIDIOC_QUERYMENU`` to return
+an ``EINVAL`` error code for some indices between ``minimum`` and
+``maximum``. In that case that particular menu item is not supported by
+this driver. Also note that the ``minimum`` value is not necessarily 0.
+
+See also the examples in :ref:`control`.
+
+
+.. _v4l2-queryctrl:
+
+.. flat-table:: struct v4l2_queryctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application. See
+ :ref:`control-id` for predefined IDs. When the ID is ORed with
+ V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and
+ returns the first control with a higher ID. Drivers which do not
+ support this flag yet always return an ``EINVAL`` error code.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of control, see :ref:`v4l2-ctrl-type`.
+
+ - .. row 3
+
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the control, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 4
+
+ - __s32
+
+ - ``minimum``
+
+ - Minimum value, inclusive. This field gives a lower bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the minimum value is to be used for each possible control type.
+ Note that this a signed 32-bit value.
+
+ - .. row 5
+
+ - __s32
+
+ - ``maximum``
+
+ - Maximum value, inclusive. This field gives an upper bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the maximum value is to be used for each possible control type.
+ Note that this a signed 32-bit value.
+
+ - .. row 6
+
+ - __s32
+
+ - ``step``
+
+ - This field gives a step size for the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
+ to be used for each possible control type. Note that this an
+ unsigned 32-bit value.
+
+ Generally drivers should not scale hardware control values. It may
+ be necessary for example when the ``name`` or ``id`` imply a
+ particular unit and the hardware actually accepts only multiples
+ of said unit. If so, drivers must take care values are properly
+ rounded when scaling, such that errors will not accumulate on
+ repeated read-write cycles.
+
+ This field gives the smallest change of an integer control
+ actually affecting hardware. Often the information is needed when
+ the user can change controls by keyboard or GUI buttons, rather
+ than a slider. When for example a hardware register accepts values
+ 0-511 and the driver reports 0-65535, step should be 128.
+
+ Note that although signed, the step value is supposed to be always
+ positive.
+
+ - .. row 7
+
+ - __s32
+
+ - ``default_value``
+
+ - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``,
+ ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid
+ for other types of controls. Note that drivers reset controls to
+ their default value only when the driver is first loaded, never
+ afterwards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - Control flags, see :ref:`control-flags`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-query-ext-ctrl:
+
+.. flat-table:: struct v4l2_query_ext_ctrl
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``id``
+
+ - Identifies the control, set by the application. See
+ :ref:`control-id` for predefined IDs. When the ID is ORed with
+ ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and
+ returns the first non-compound control with a higher ID. When the
+ ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears
+ the flag and returns the first compound control with a higher ID.
+ Set both to get the first control (compound or not) with a higher
+ ID.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of control, see :ref:`v4l2-ctrl-type`.
+
+ - .. row 3
+
+ - char
+
+ - ``name``\ [32]
+
+ - Name of the control, a NUL-terminated ASCII string. This
+ information is intended for the user.
+
+ - .. row 4
+
+ - __s64
+
+ - ``minimum``
+
+ - Minimum value, inclusive. This field gives a lower bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the minimum value is to be used for each possible control type.
+ Note that this a signed 64-bit value.
+
+ - .. row 5
+
+ - __s64
+
+ - ``maximum``
+
+ - Maximum value, inclusive. This field gives an upper bound for the
+ control. See enum :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how
+ the maximum value is to be used for each possible control type.
+ Note that this a signed 64-bit value.
+
+ - .. row 6
+
+ - __u64
+
+ - ``step``
+
+ - This field gives a step size for the control. See enum
+ :ref:`v4l2_ctrl_type <v4l2-ctrl-type>` how the step value is
+ to be used for each possible control type. Note that this an
+ unsigned 64-bit value.
+
+ Generally drivers should not scale hardware control values. It may
+ be necessary for example when the ``name`` or ``id`` imply a
+ particular unit and the hardware actually accepts only multiples
+ of said unit. If so, drivers must take care values are properly
+ rounded when scaling, such that errors will not accumulate on
+ repeated read-write cycles.
+
+ This field gives the smallest change of an integer control
+ actually affecting hardware. Often the information is needed when
+ the user can change controls by keyboard or GUI buttons, rather
+ than a slider. When for example a hardware register accepts values
+ 0-511 and the driver reports 0-65535, step should be 128.
+
+ - .. row 7
+
+ - __s64
+
+ - ``default_value``
+
+ - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``,
+ ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8``
+ or ``_U16`` control. Not valid for other types of controls. Note
+ that drivers reset controls to their default value only when the
+ driver is first loaded, never afterwards.
+
+ - .. row 8
+
+ - __u32
+
+ - ``flags``
+
+ - Control flags, see :ref:`control-flags`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``elem_size``
+
+ - The size in bytes of a single element of the array. Given a char
+ pointer ``p`` to a 3-dimensional array you can find the position
+ of cell ``(z, y, x)`` as follows:
+ ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``.
+ ``elem_size`` is always valid, also when the control isn't an
+ array. For string controls ``elem_size`` is equal to
+ ``maximum + 1``.
+
+ - .. row 10
+
+ - __u32
+
+ - ``elems``
+
+ - The number of elements in the N-dimensional array. If this control
+ is not an array, then ``elems`` is 1. The ``elems`` field can
+ never be 0.
+
+ - .. row 11
+
+ - __u32
+
+ - ``nr_of_dims``
+
+ - The number of dimension in the N-dimensional array. If this
+ control is not an array, then this field is 0.
+
+ - .. row 12
+
+ - __u32
+
+ - ``dims[V4L2_CTRL_MAX_DIMS]``
+
+ - The size of each dimension. The first ``nr_of_dims`` elements of
+ this array must be non-zero, all remaining elements must be zero.
+
+ - .. row 13
+
+ - __u32
+
+ - ``reserved``\ [32]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-querymenu:
+
+.. flat-table:: struct v4l2_querymenu
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2 1
+
+
+ - .. row 1
+
+ - __u32
+
+ -
+ - ``id``
+
+ - Identifies the control, set by the application from the respective
+ struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``.
+
+ - .. row 2
+
+ - __u32
+
+ -
+ - ``index``
+
+ - Index of the menu item, starting at zero, set by the application.
+
+ - .. row 3
+
+ - union
+
+ -
+ -
+ -
+
+ - .. row 4
+
+ -
+ - __u8
+
+ - ``name``\ [32]
+
+ - Name of the menu item, a NUL-terminated ASCII string. This
+ information is intended for the user. This field is valid for
+ ``V4L2_CTRL_FLAG_MENU`` type controls.
+
+ - .. row 5
+
+ -
+ - __s64
+
+ - ``value``
+
+ - Value of the integer menu item. This field is valid for
+ ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls.
+
+ - .. row 6
+
+ - __u32
+
+ -
+ - ``reserved``
+
+ - Reserved for future extensions. Drivers must set the array to
+ zero.
+
+
+
+.. _v4l2-ctrl-type:
+
+.. flat-table:: enum v4l2_ctrl_type
+ :header-rows: 1
+ :stub-columns: 0
+ :widths: 30 5 5 5 55
+
+
+ - .. row 1
+
+ - Type
+
+ - ``minimum``
+
+ - ``step``
+
+ - ``maximum``
+
+ - Description
+
+ - .. row 2
+
+ - ``V4L2_CTRL_TYPE_INTEGER``
+
+ - any
+
+ - any
+
+ - any
+
+ - An integer-valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_TYPE_BOOLEAN``
+
+ - 0
+
+ - 1
+
+ - 1
+
+ - A boolean-valued control. Zero corresponds to "disabled", and one
+ means "enabled".
+
+ - .. row 4
+
+ - ``V4L2_CTRL_TYPE_MENU``
+
+ - ≥ 0
+
+ - 1
+
+ - N-1
+
+ - The control has a menu of N choices. The names of the menu items
+ can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_TYPE_INTEGER_MENU``
+
+ - ≥ 0
+
+ - 1
+
+ - N-1
+
+ - The control has a menu of N choices. The values of the menu items
+ can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is
+ similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings,
+ the menu items are signed 64-bit integers.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_TYPE_BITMASK``
+
+ - 0
+
+ - n/a
+
+ - any
+
+ - A bitmask field. The maximum value is the set of bits that can be
+ used, all other bits are to be 0. The maximum value is interpreted
+ as a __u32, allowing the use of bit 31 in the bitmask.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_TYPE_BUTTON``
+
+ - 0
+
+ - 0
+
+ - 0
+
+ - A control which performs an action when set. Drivers must ignore
+ the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error
+ code on a ``VIDIOC_G_CTRL`` attempt.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_TYPE_INTEGER64``
+
+ - any
+
+ - any
+
+ - any
+
+ - A 64-bit integer valued control. Minimum, maximum and step size
+ cannot be queried using ``VIDIOC_QUERYCTRL``. Only
+ ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step
+ values, they should be interpreted as n/a when using
+ ``VIDIOC_QUERYCTRL``.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_TYPE_STRING``
+
+ - ≥ 0
+
+ - ≥ 1
+
+ - ≥ 0
+
+ - The minimum and maximum string lengths. The step size means that
+ the string must be (minimum + N * step) characters long for N ≥ 0.
+ These lengths do not include the terminating zero, so in order to
+ pass a string of length 8 to
+ :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to
+ set the ``size`` field of struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>` to 9. For
+ :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set
+ the ``size`` field to ``maximum`` + 1. Which character encoding is
+ used will depend on the string control itself and should be part
+ of the control documentation.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_TYPE_CTRL_CLASS``
+
+ - n/a
+
+ - n/a
+
+ - n/a
+
+ - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a
+ control ID equal to a control class code (see :ref:`ctrl-class`)
+ + 1, the ioctl returns the name of the control class and this
+ control type. Older drivers which do not support this feature
+ return an ``EINVAL`` error code.
+
+ - .. row 11
+
+ - ``V4L2_CTRL_TYPE_U8``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 8-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 12
+
+ - ``V4L2_CTRL_TYPE_U16``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 16-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+ - .. row 13
+
+ - ``V4L2_CTRL_TYPE_U32``
+
+ - any
+
+ - any
+
+ - any
+
+ - An unsigned 32-bit valued control ranging from minimum to maximum
+ inclusive. The step value indicates the increment between values.
+
+
+
+.. _control-flags:
+
+.. flat-table:: Control Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_CTRL_FLAG_DISABLED``
+
+ - 0x0001
+
+ - This control is permanently disabled and should be ignored by the
+ application. Any attempt to change the control will result in an
+ ``EINVAL`` error code.
+
+ - .. row 2
+
+ - ``V4L2_CTRL_FLAG_GRABBED``
+
+ - 0x0002
+
+ - This control is temporarily unchangeable, for example because
+ another application took over control of the respective resource.
+ Such controls may be displayed specially in a user interface.
+ Attempts to change the control may result in an ``EBUSY`` error code.
+
+ - .. row 3
+
+ - ``V4L2_CTRL_FLAG_READ_ONLY``
+
+ - 0x0004
+
+ - This control is permanently readable only. Any attempt to change
+ the control will result in an ``EINVAL`` error code.
+
+ - .. row 4
+
+ - ``V4L2_CTRL_FLAG_UPDATE``
+
+ - 0x0008
+
+ - A hint that changing this control may affect the value of other
+ controls within the same control class. Applications should update
+ their user interface accordingly.
+
+ - .. row 5
+
+ - ``V4L2_CTRL_FLAG_INACTIVE``
+
+ - 0x0010
+
+ - This control is not applicable to the current configuration and
+ should be displayed accordingly in a user interface. For example
+ the flag may be set on a MPEG audio level 2 bitrate control when
+ MPEG audio encoding level 1 was selected with another control.
+
+ - .. row 6
+
+ - ``V4L2_CTRL_FLAG_SLIDER``
+
+ - 0x0020
+
+ - A hint that this control is best represented as a slider-like
+ element in a user interface.
+
+ - .. row 7
+
+ - ``V4L2_CTRL_FLAG_WRITE_ONLY``
+
+ - 0x0040
+
+ - This control is permanently writable only. Any attempt to read the
+ control will result in an ``EACCES`` error code error code. This flag
+ is typically present for relative controls or action controls
+ where writing a value will cause the device to carry out a given
+ action (e. g. motor control) but no meaningful value can be
+ returned.
+
+ - .. row 8
+
+ - ``V4L2_CTRL_FLAG_VOLATILE``
+
+ - 0x0080
+
+ - This control is volatile, which means that the value of the
+ control changes continuously. A typical example would be the
+ current gain value if the device is in auto-gain mode. In such a
+ case the hardware calculates the gain value based on the lighting
+ conditions which can change over time. Note that setting a new
+ value for a volatile control will have no effect and no
+ ``V4L2_EVENT_CTRL_CH_VALUE`` will be sent, unless the
+ ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` flag (see below) is also set.
+ Otherwise the new value will just be ignored.
+
+ - .. row 9
+
+ - ``V4L2_CTRL_FLAG_HAS_PAYLOAD``
+
+ - 0x0100
+
+ - This control has a pointer type, so its value has to be accessed
+ using one of the pointer fields of struct
+ :ref:`v4l2_ext_control <v4l2-ext-control>`. This flag is set
+ for controls that are an array, string, or have a compound type.
+ In all cases you have to set a pointer to memory containing the
+ payload of the control.
+
+ - .. row 10
+
+ - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE``
+
+ - 0x0200
+
+ - The value provided to the control will be propagated to the driver
+ even if it remains constant. This is required when the control
+ represents an action on the hardware. For example: clearing an
+ error flag or triggering the flash. All the controls of the type
+ ``V4L2_CTRL_TYPE_BUTTON`` have this flag set.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is
+ invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id``
+ is invalid or ``index`` is out of range (less than ``minimum`` or
+ greater than ``maximum``) or this particular menu item is not
+ supported by the driver.
+
+EACCES
+ An attempt was made to read a write-only control.
+
+.. [1]
+ ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers
+ can skip predefined controls not supported by the hardware (although
+ returning ``EINVAL`` would do as well), or disable predefined and private
+ controls after hardware detection without the trouble of reordering
+ control arrays and indices (``EINVAL`` cannot be used to skip private
+ controls because it would prematurely end the enumeration).
diff --git a/Documentation/media/uapi/v4l/vidioc-querystd.rst b/Documentation/media/uapi/v4l/vidioc-querystd.rst
new file mode 100644
index 000000000000..5bf62775c740
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-querystd.rst
@@ -0,0 +1,66 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_QUERYSTD:
+
+*********************
+ioctl VIDIOC_QUERYSTD
+*********************
+
+Name
+====
+
+VIDIOC_QUERYSTD - Sense the video standard received by the current input
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, v4l2_std_id *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_QUERYSTD
+
+``argp``
+
+
+Description
+===========
+
+The hardware may be able to detect the current video standard
+automatically. To do so, applications call :ref:`VIDIOC_QUERYSTD` with a
+pointer to a :ref:`v4l2_std_id <v4l2-std-id>` type. The driver
+stores here a set of candidates, this can be a single flag or a set of
+supported standards if for example the hardware can only distinguish
+between 50 and 60 Hz systems. If no signal was detected, then the driver
+will return V4L2_STD_UNKNOWN. When detection is not possible or fails,
+the set must contain all standards supported by the current video input
+or output.
+
+Please note that drivers shall *not* switch the video standard
+automatically if a new video standard is detected. Instead, drivers
+should send the ``V4L2_EVENT_SOURCE_CHANGE`` event (if they support
+this) and expect that userspace will take action by calling
+:ref:`VIDIOC_QUERYSTD`. The reason is that a new video standard can mean
+different buffer sizes as well, and you cannot change buffer sizes on
+the fly. In general, applications that receive the Source Change event
+will have to call :ref:`VIDIOC_QUERYSTD`, and if the detected video
+standard is valid they will have to stop streaming, set the new
+standard, allocate new buffers and start streaming again.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+ENODATA
+ Standard video timings are not supported for this input or output.
diff --git a/Documentation/media/uapi/v4l/vidioc-reqbufs.rst b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst
new file mode 100644
index 000000000000..c25b0719c2ff
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-reqbufs.rst
@@ -0,0 +1,125 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_REQBUFS:
+
+********************
+ioctl VIDIOC_REQBUFS
+********************
+
+Name
+====
+
+VIDIOC_REQBUFS - Initiate Memory Mapping or User Pointer I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_requestbuffers *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_REQBUFS
+
+``argp``
+
+
+Description
+===========
+
+This ioctl is used to initiate :ref:`memory mapped <mmap>`,
+:ref:`user pointer <userp>` or :ref:`DMABUF <dmabuf>` based I/O.
+Memory mapped buffers are located in device memory and must be allocated
+with this ioctl before they can be mapped into the application's address
+space. User buffers are allocated by applications themselves, and this
+ioctl is merely used to switch the driver into user pointer I/O mode and
+to setup some internal structures. Similarly, DMABUF buffers are
+allocated by applications through a device driver, and this ioctl only
+configures the driver into DMABUF I/O mode without performing any direct
+allocation.
+
+To allocate device buffers applications initialize all fields of the
+:ref:`struct v4l2_requestbuffers <v4l2-requestbuffers>` structure. They set the ``type``
+field to the respective stream or buffer type, the ``count`` field to
+the desired number of buffers, ``memory`` must be set to the requested
+I/O method and the ``reserved`` array must be zeroed. When the ioctl is
+called with a pointer to this structure the driver will attempt to
+allocate the requested number of buffers and it stores the actual number
+allocated in the ``count`` field. It can be smaller than the number
+requested, even zero, when the driver runs out of free memory. A larger
+number is also possible when the driver requires more buffers to
+function correctly. For example video output requires at least two
+buffers, one displayed and one filled by the application.
+
+When the I/O method is not supported the ioctl returns an ``EINVAL`` error
+code.
+
+Applications can call :ref:`VIDIOC_REQBUFS` again to change the number of
+buffers, however this cannot succeed when any buffers are still mapped.
+A ``count`` value of zero frees all buffers, after aborting or finishing
+any DMA in progress, an implicit
+:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>`.
+
+
+.. _v4l2-requestbuffers:
+
+.. flat-table:: struct v4l2_requestbuffers
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``count``
+
+ - The number of buffers requested or granted.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - Type of the stream or buffers, this is the same as the struct
+ :ref:`v4l2_format <v4l2-format>` ``type`` field. See
+ :ref:`v4l2-buf-type` for valid values.
+
+ - .. row 3
+
+ - __u32
+
+ - ``memory``
+
+ - Applications set this field to ``V4L2_MEMORY_MMAP``,
+ ``V4L2_MEMORY_DMABUF`` or ``V4L2_MEMORY_USERPTR``. See
+ :ref:`v4l2-memory`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [2]
+
+ - A place holder for future extensions. Drivers and applications
+ must set the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The buffer type (``type`` field) or the requested I/O method
+ (``memory``) is not supported.
diff --git a/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst b/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst
new file mode 100644
index 000000000000..5fd332a5bfee
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst
@@ -0,0 +1,179 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_S_HW_FREQ_SEEK:
+
+***************************
+ioctl VIDIOC_S_HW_FREQ_SEEK
+***************************
+
+Name
+====
+
+VIDIOC_S_HW_FREQ_SEEK - Perform a hardware frequency seek
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_hw_freq_seek *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_S_HW_FREQ_SEEK
+
+``argp``
+
+
+Description
+===========
+
+Start a hardware frequency seek from the current frequency. To do this
+applications initialize the ``tuner``, ``type``, ``seek_upward``,
+``wrap_around``, ``spacing``, ``rangelow`` and ``rangehigh`` fields, and
+zero out the ``reserved`` array of a struct
+:ref:`v4l2_hw_freq_seek <v4l2-hw-freq-seek>` and call the
+``VIDIOC_S_HW_FREQ_SEEK`` ioctl with a pointer to this structure.
+
+The ``rangelow`` and ``rangehigh`` fields can be set to a non-zero value
+to tell the driver to search a specific band. If the struct
+:ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag set, these values must fall
+within one of the bands returned by
+:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
+``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` flag is not set, then these values
+must exactly match those of one of the bands returned by
+:ref:`VIDIOC_ENUM_FREQ_BANDS`. If the
+current frequency of the tuner does not fall within the selected band it
+will be clamped to fit in the band before the seek is started.
+
+If an error is returned, then the original frequency will be restored.
+
+This ioctl is supported if the ``V4L2_CAP_HW_FREQ_SEEK`` capability is
+set.
+
+If this ioctl is called from a non-blocking filehandle, then ``EAGAIN``
+error code is returned and no seek takes place.
+
+
+.. _v4l2-hw-freq-seek:
+
+.. flat-table:: struct v4l2_hw_freq_seek
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``tuner``
+
+ - The tuner index number. This is the same value as in the struct
+ :ref:`v4l2_input <v4l2-input>` ``tuner`` field and the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``index`` field.
+
+ - .. row 2
+
+ - __u32
+
+ - ``type``
+
+ - The tuner type. This is the same value as in the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``type`` field. See
+ :ref:`v4l2-tuner-type`
+
+ - .. row 3
+
+ - __u32
+
+ - ``seek_upward``
+
+ - If non-zero, seek upward from the current frequency, else seek
+ downward.
+
+ - .. row 4
+
+ - __u32
+
+ - ``wrap_around``
+
+ - If non-zero, wrap around when at the end of the frequency range,
+ else stop seeking. The struct :ref:`v4l2_tuner <v4l2-tuner>`
+ ``capability`` field will tell you what the hardware supports.
+
+ - .. row 5
+
+ - __u32
+
+ - ``spacing``
+
+ - If non-zero, defines the hardware seek resolution in Hz. The
+ driver selects the nearest value that is supported by the device.
+ If spacing is zero a reasonable default value is used.
+
+ - .. row 6
+
+ - __u32
+
+ - ``rangelow``
+
+ - If non-zero, the lowest tunable frequency of the band to search in
+ units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+ ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
+ struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
+ the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
+ ``rangelow`` is zero a reasonable default value is used.
+
+ - .. row 7
+
+ - __u32
+
+ - ``rangehigh``
+
+ - If non-zero, the highest tunable frequency of the band to search
+ in units of 62.5 kHz, or if the struct
+ :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has the
+ ``V4L2_TUNER_CAP_LOW`` flag set, in units of 62.5 Hz or if the
+ struct :ref:`v4l2_tuner <v4l2-tuner>` ``capability`` field has
+ the ``V4L2_TUNER_CAP_1HZ`` flag set, in units of 1 Hz. If
+ ``rangehigh`` is zero a reasonable default value is used.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Applications must set the array to
+ zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The ``tuner`` index is out of bounds, the ``wrap_around`` value is
+ not supported or one of the values in the ``type``, ``rangelow`` or
+ ``rangehigh`` fields is wrong.
+
+EAGAIN
+ Attempted to call ``VIDIOC_S_HW_FREQ_SEEK`` with the filehandle in
+ non-blocking mode.
+
+ENODATA
+ The hardware seek found no channels.
+
+EBUSY
+ Another hardware seek is already in progress.
diff --git a/Documentation/media/uapi/v4l/vidioc-streamon.rst b/Documentation/media/uapi/v4l/vidioc-streamon.rst
new file mode 100644
index 000000000000..e87500e608e1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-streamon.rst
@@ -0,0 +1,103 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_STREAMON:
+
+***************************************
+ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF
+***************************************
+
+Name
+====
+
+VIDIOC_STREAMON - VIDIOC_STREAMOFF - Start or stop streaming I/O
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, const int *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_STREAMON, VIDIOC_STREAMOFF
+
+``argp``
+
+
+Description
+===========
+
+The ``VIDIOC_STREAMON`` and ``VIDIOC_STREAMOFF`` ioctl start and stop
+the capture or output process during streaming
+(:ref:`memory mapping <mmap>`, :ref:`user pointer <userp>` or
+:ref:`DMABUF <dmabuf>`) I/O.
+
+Capture hardware is disabled and no input buffers are filled (if there
+are any empty buffers in the incoming queue) until ``VIDIOC_STREAMON``
+has been called. Output hardware is disabled and no video signal is
+produced until ``VIDIOC_STREAMON`` has been called. The ioctl will
+succeed when at least one output buffer is in the incoming queue.
+
+Memory-to-memory devices will not start until ``VIDIOC_STREAMON`` has
+been called for both the capture and output stream types.
+
+If ``VIDIOC_STREAMON`` fails then any already queued buffers will remain
+queued.
+
+The ``VIDIOC_STREAMOFF`` ioctl, apart of aborting or finishing any DMA
+in progress, unlocks any user pointer buffers locked in physical memory,
+and it removes all buffers from the incoming and outgoing queues. That
+means all images captured but not dequeued yet will be lost, likewise
+all images enqueued for output but not transmitted yet. I/O returns to
+the same state as after calling
+:ref:`VIDIOC_REQBUFS` and can be restarted
+accordingly.
+
+If buffers have been queued with :ref:`VIDIOC_QBUF` and
+``VIDIOC_STREAMOFF`` is called without ever having called
+``VIDIOC_STREAMON``, then those queued buffers will also be removed from
+the incoming queue and all are returned to the same state as after
+calling :ref:`VIDIOC_REQBUFS` and can be restarted
+accordingly.
+
+Both ioctls take a pointer to an integer, the desired buffer or stream
+type. This is the same as struct
+:ref:`v4l2_requestbuffers <v4l2-requestbuffers>` ``type``.
+
+If ``VIDIOC_STREAMON`` is called when streaming is already in progress,
+or if ``VIDIOC_STREAMOFF`` is called when streaming is already stopped,
+then 0 is returned. Nothing happens in the case of ``VIDIOC_STREAMON``,
+but ``VIDIOC_STREAMOFF`` will return queued buffers to their starting
+state as mentioned above.
+
+Note that applications can be preempted for unknown periods right before
+or after the ``VIDIOC_STREAMON`` or ``VIDIOC_STREAMOFF`` calls, there is
+no notion of starting or stopping "now". Buffer timestamps can be used
+to synchronize with other events.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The buffer ``type`` is not supported, or no buffers have been
+ allocated (memory mapping) or enqueued (output) yet.
+
+EPIPE
+ The driver implements
+ :ref:`pad-level format configuration <pad-level-formats>` and the
+ pipeline configuration is invalid.
+
+ENOLINK
+ The driver implements Media Controller interface and the pipeline
+ link configuration is invalid.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst
new file mode 100644
index 000000000000..0aa6482a91a6
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst
@@ -0,0 +1,153 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL:
+
+***************************************
+ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+***************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL - Enumerate frame intervals
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval_enum * argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL
+
+``argp``
+
+
+Description
+===========
+
+This ioctl lets applications enumerate available frame intervals on a
+given sub-device pad. Frame intervals only makes sense for sub-devices
+that can control the frame period on their own. This includes, for
+instance, image sensors and TV tuners.
+
+For the common use case of image sensors, the frame intervals available
+on the sub-device output pad depend on the frame format and size on the
+same pad. Applications must thus specify the desired format and size
+when enumerating frame intervals.
+
+To enumerate frame intervals applications initialize the ``index``,
+``pad``, ``which``, ``code``, ``width`` and ``height`` fields of struct
+:ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>`
+and call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL` ioctl with a pointer
+to this structure. Drivers fill the rest of the structure or return an
+EINVAL error code if one of the input fields is invalid. All frame
+intervals are enumerable by beginning at index zero and incrementing by
+one until ``EINVAL`` is returned.
+
+Available frame intervals may depend on the current 'try' formats at
+other pads of the sub-device, as well as on the current active links.
+See :ref:`VIDIOC_SUBDEV_G_FMT` for more
+information about the try formats.
+
+Sub-devices that support the frame interval enumeration ioctl should
+implemented it on a single pad only. Its behaviour when supported on
+multiple pads of the same sub-device is not defined.
+
+
+.. _v4l2-subdev-frame-interval-enum:
+
+.. flat-table:: struct v4l2_subdev_frame_interval_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``width``
+
+ - Frame width, in pixels.
+
+ - .. row 5
+
+ - __u32
+
+ - ``height``
+
+ - Frame height, in pixels.
+
+ - .. row 6
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``interval``
+
+ - Period, in seconds, between consecutive video frames.
+
+ - .. row 7
+
+ - __u32
+
+ - ``which``
+
+ - Frame intervals to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 8
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_interval_enum <v4l2-subdev-frame-interval-enum>`
+ ``pad`` references a non-existing pad, one of the ``code``,
+ ``width`` or ``height`` fields are invalid for the given pad or the
+ ``index`` field is out of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst
new file mode 100644
index 000000000000..7a5811b71b68
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst
@@ -0,0 +1,162 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_ENUM_FRAME_SIZE:
+
+***********************************
+ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+***********************************
+
+Name
+====
+
+VIDIOC_SUBDEV_ENUM_FRAME_SIZE - Enumerate media bus frame sizes
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_size_enum * argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_FRAME_SIZE
+
+``argp``
+
+
+Description
+===========
+
+This ioctl allows applications to enumerate all frame sizes supported by
+a sub-device on the given pad for the given media bus format. Supported
+formats can be retrieved with the
+:ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE`
+ioctl.
+
+To enumerate frame sizes applications initialize the ``pad``, ``which``
+, ``code`` and ``index`` fields of the struct
+:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
+call the :ref:`VIDIOC_SUBDEV_ENUM_FRAME_SIZE` ioctl with a pointer to the
+structure. Drivers fill the minimum and maximum frame sizes or return an
+EINVAL error code if one of the input parameters is invalid.
+
+Sub-devices that only support discrete frame sizes (such as most
+sensors) will return one or more frame sizes with identical minimum and
+maximum values.
+
+Not all possible sizes in given [minimum, maximum] ranges need to be
+supported. For instance, a scaler that uses a fixed-point scaling ratio
+might not be able to produce every frame size between the minimum and
+maximum values. Applications must use the
+:ref:`VIDIOC_SUBDEV_S_FMT <VIDIOC_SUBDEV_G_FMT>` ioctl to try the
+sub-device for an exact supported frame size.
+
+Available frame sizes may depend on the current 'try' formats at other
+pads of the sub-device, as well as on the current active links and the
+current values of V4L2 controls. See
+:ref:`VIDIOC_SUBDEV_G_FMT` for more
+information about try formats.
+
+
+.. _v4l2-subdev-frame-size-enum:
+
+.. flat-table:: struct v4l2_subdev_frame_size_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``min_width``
+
+ - Minimum frame width, in pixels.
+
+ - .. row 5
+
+ - __u32
+
+ - ``max_width``
+
+ - Maximum frame width, in pixels.
+
+ - .. row 6
+
+ - __u32
+
+ - ``min_height``
+
+ - Minimum frame height, in pixels.
+
+ - .. row 7
+
+ - __u32
+
+ - ``max_height``
+
+ - Maximum frame height, in pixels.
+
+ - .. row 8
+
+ - __u32
+
+ - ``which``
+
+ - Frame sizes to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 9
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_size_enum <v4l2-subdev-frame-size-enum>`
+ ``pad`` references a non-existing pad, the ``code`` is invalid for
+ the given pad or the ``index`` field is out of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst b/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst
new file mode 100644
index 000000000000..bc0531eb56fa
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst
@@ -0,0 +1,115 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_ENUM_MBUS_CODE:
+
+**********************************
+ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE
+**********************************
+
+Name
+====
+
+VIDIOC_SUBDEV_ENUM_MBUS_CODE - Enumerate media bus formats
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_mbus_code_enum * argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_ENUM_MBUS_CODE
+
+``argp``
+
+
+Description
+===========
+
+To enumerate media bus formats available at a given sub-device pad
+applications initialize the ``pad``, ``which`` and ``index`` fields of
+struct
+:ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>` and
+call the :ref:`VIDIOC_SUBDEV_ENUM_MBUS_CODE` ioctl with a pointer to this
+structure. Drivers fill the rest of the structure or return an ``EINVAL``
+error code if either the ``pad`` or ``index`` are invalid. All media bus
+formats are enumerable by beginning at index zero and incrementing by
+one until ``EINVAL`` is returned.
+
+Available media bus formats may depend on the current 'try' formats at
+other pads of the sub-device, as well as on the current active links.
+See :ref:`VIDIOC_SUBDEV_G_FMT` for more
+information about the try formats.
+
+
+.. _v4l2-subdev-mbus-code-enum:
+
+.. flat-table:: struct v4l2_subdev_mbus_code_enum
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - __u32
+
+ - ``index``
+
+ - Number of the format in the enumeration, set by the application.
+
+ - .. row 3
+
+ - __u32
+
+ - ``code``
+
+ - The media bus format code, as defined in
+ :ref:`v4l2-mbus-format`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``which``
+
+ - Media bus format codes to be enumerated, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 5
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_mbus_code_enum <v4l2-subdev-mbus-code-enum>`
+ ``pad`` references a non-existing pad, or the ``index`` field is out
+ of bounds.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
new file mode 100644
index 000000000000..690034a391d3
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst
@@ -0,0 +1,136 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_CROP:
+
+************************************************
+ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
+************************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_CROP - VIDIOC_SUBDEV_S_CROP - Get or set the crop rectangle on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_crop *argp )
+
+.. cpp:function:: int ioctl( int fd, int request, const struct v4l2_subdev_crop *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP
+
+``argp``
+
+
+Description
+===========
+
+ **Note**
+
+ This is an :ref:`obsolete` interface and may be removed
+ in the future. It is superseded by
+ :ref:`the selection API <VIDIOC_SUBDEV_G_SELECTION>`.
+
+To retrieve the current crop rectangle applications set the ``pad``
+field of a struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` to the
+desired pad number as reported by the media API and the ``which`` field
+to ``V4L2_SUBDEV_FORMAT_ACTIVE``. They then call the
+``VIDIOC_SUBDEV_G_CROP`` ioctl with a pointer to this structure. The
+driver fills the members of the ``rect`` field or returns ``EINVAL`` error
+code if the input arguments are invalid, or if cropping is not supported
+on the given pad.
+
+To change the current crop rectangle applications set both the ``pad``
+and ``which`` fields and all members of the ``rect`` field. They then
+call the ``VIDIOC_SUBDEV_S_CROP`` ioctl with a pointer to this
+structure. The driver verifies the requested crop rectangle, adjusts it
+based on the hardware capabilities and configures the device. Upon
+return the struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>`
+contains the current format as would be returned by a
+``VIDIOC_SUBDEV_G_CROP`` call.
+
+Applications can query the device capabilities by setting the ``which``
+to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' crop rectangles are not
+applied to the device by the driver, but are mangled exactly as active
+crop rectangles and stored in the sub-device file handle. Two
+applications querying the same sub-device would thus not interact with
+each other.
+
+Drivers must not return an error solely because the requested crop
+rectangle doesn't match the device capabilities. They must instead
+modify the rectangle to match what the hardware can provide. The
+modified format should be as close as possible to the original request.
+
+
+.. _v4l2-subdev-crop:
+
+.. flat-table:: struct v4l2_subdev_crop
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media framework.
+
+ - .. row 2
+
+ - __u32
+
+ - ``which``
+
+ - Crop rectangle to get or set, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``rect``
+
+ - Crop rectangle boundaries, in pixels.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The crop rectangle can't be changed because the pad is currently
+ busy. This can be caused, for instance, by an active video stream on
+ the pad. The ioctl must not be retried without performing another
+ action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_CROP``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_crop <v4l2-subdev-crop>` ``pad``
+ references a non-existing pad, the ``which`` field references a
+ non-existing format, or cropping is not supported on the given
+ subdev pad.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
new file mode 100644
index 000000000000..90e2a6635ebc
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst
@@ -0,0 +1,171 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_FMT:
+
+**********************************************
+ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+**********************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_FMT - VIDIOC_SUBDEV_S_FMT - Get or set the data format on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_format *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to negotiate the frame format at specific subdev
+pads in the image pipeline.
+
+To retrieve the current format applications set the ``pad`` field of a
+struct :ref:`v4l2_subdev_format <v4l2-subdev-format>` to the desired
+pad number as reported by the media API and the ``which`` field to
+``V4L2_SUBDEV_FORMAT_ACTIVE``. When they call the
+``VIDIOC_SUBDEV_G_FMT`` ioctl with a pointer to this structure the
+driver fills the members of the ``format`` field.
+
+To change the current format applications set both the ``pad`` and
+``which`` fields and all members of the ``format`` field. When they call
+the ``VIDIOC_SUBDEV_S_FMT`` ioctl with a pointer to this structure the
+driver verifies the requested format, adjusts it based on the hardware
+capabilities and configures the device. Upon return the struct
+:ref:`v4l2_subdev_format <v4l2-subdev-format>` contains the current
+format as would be returned by a ``VIDIOC_SUBDEV_G_FMT`` call.
+
+Applications can query the device capabilities by setting the ``which``
+to ``V4L2_SUBDEV_FORMAT_TRY``. When set, 'try' formats are not applied
+to the device by the driver, but are changed exactly as active formats
+and stored in the sub-device file handle. Two applications querying the
+same sub-device would thus not interact with each other.
+
+For instance, to try a format at the output pad of a sub-device,
+applications would first set the try format at the sub-device input with
+the ``VIDIOC_SUBDEV_S_FMT`` ioctl. They would then either retrieve the
+default format at the output pad with the ``VIDIOC_SUBDEV_G_FMT`` ioctl,
+or set the desired output pad format with the ``VIDIOC_SUBDEV_S_FMT``
+ioctl and check the returned value.
+
+Try formats do not depend on active formats, but can depend on the
+current links configuration or sub-device controls value. For instance,
+a low-pass noise filter might crop pixels at the frame boundaries,
+modifying its output frame size.
+
+Drivers must not return an error solely because the requested format
+doesn't match the device capabilities. They must instead modify the
+format to match what the hardware can provide. The modified format
+should be as close as possible to the original request.
+
+
+.. _v4l2-subdev-format:
+
+.. flat-table:: struct v4l2_subdev_format
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - __u32
+
+ - ``which``
+
+ - Format to modified, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 3
+
+ - struct :ref:`v4l2_mbus_framefmt <v4l2-mbus-framefmt>`
+
+ - ``format``
+
+ - Definition of an image format, see :ref:`v4l2-mbus-framefmt` for
+ details.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+
+.. _v4l2-subdev-format-whence:
+
+.. flat-table:: enum v4l2_subdev_format_whence
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - V4L2_SUBDEV_FORMAT_TRY
+
+ - 0
+
+ - Try formats, used for querying device capabilities.
+
+ - .. row 2
+
+ - V4L2_SUBDEV_FORMAT_ACTIVE
+
+ - 1
+
+ - Active formats, applied to the hardware.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The format can't be changed because the pad is currently busy. This
+ can be caused, for instance, by an active video stream on the pad.
+ The ioctl must not be retried without performing another action to
+ fix the problem first. Only returned by ``VIDIOC_SUBDEV_S_FMT``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_format <v4l2-subdev-format>`
+ ``pad`` references a non-existing pad, or the ``which`` field
+ references a non-existing format.
+
+
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
new file mode 100644
index 000000000000..d8a1cabbd272
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst
@@ -0,0 +1,122 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_FRAME_INTERVAL:
+
+********************************************************************
+ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL
+********************************************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_FRAME_INTERVAL - VIDIOC_SUBDEV_S_FRAME_INTERVAL - Get or set the frame interval on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_frame_interval *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_FRAME_INTERVAL,
+ VIDIOC_SUBDEV_S_FRAME_INTERVAL
+
+``argp``
+
+
+Description
+===========
+
+These ioctls are used to get and set the frame interval at specific
+subdev pads in the image pipeline. The frame interval only makes sense
+for sub-devices that can control the frame period on their own. This
+includes, for instance, image sensors and TV tuners. Sub-devices that
+don't support frame intervals must not implement these ioctls.
+
+To retrieve the current frame interval applications set the ``pad``
+field of a struct
+:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>` to
+the desired pad number as reported by the media controller API. When
+they call the ``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` ioctl with a pointer to
+this structure the driver fills the members of the ``interval`` field.
+
+To change the current frame interval applications set both the ``pad``
+field and all members of the ``interval`` field. When they call the
+``VIDIOC_SUBDEV_S_FRAME_INTERVAL`` ioctl with a pointer to this
+structure the driver verifies the requested interval, adjusts it based
+on the hardware capabilities and configures the device. Upon return the
+struct
+:ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
+contains the current frame interval as would be returned by a
+``VIDIOC_SUBDEV_G_FRAME_INTERVAL`` call.
+
+Drivers must not return an error solely because the requested interval
+doesn't match the device capabilities. They must instead modify the
+interval to match what the hardware can provide. The modified interval
+should be as close as possible to the original request.
+
+Sub-devices that support the frame interval ioctls should implement them
+on a single pad only. Their behaviour when supported on multiple pads of
+the same sub-device is not defined.
+
+
+.. _v4l2-subdev-frame-interval:
+
+.. flat-table:: struct v4l2_subdev_frame_interval
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media controller API.
+
+ - .. row 2
+
+ - struct :ref:`v4l2_fract <v4l2-fract>`
+
+ - ``interval``
+
+ - Period, in seconds, between consecutive video frames.
+
+ - .. row 3
+
+ - __u32
+
+ - ``reserved``\ [9]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The frame interval can't be changed because the pad is currently
+ busy. This can be caused, for instance, by an active video stream on
+ the pad. The ioctl must not be retried without performing another
+ action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_FRAME_INTERVAL``
+
+EINVAL
+ The struct
+ :ref:`v4l2_subdev_frame_interval <v4l2-subdev-frame-interval>`
+ ``pad`` references a non-existing pad, or the pad doesn't support
+ frame intervals.
diff --git a/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
new file mode 100644
index 000000000000..50838a4a429e
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst
@@ -0,0 +1,144 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBDEV_G_SELECTION:
+
+**********************************************************
+ioctl VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
+**********************************************************
+
+Name
+====
+
+VIDIOC_SUBDEV_G_SELECTION - VIDIOC_SUBDEV_S_SELECTION - Get or set selection rectangles on a subdev pad
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_subdev_selection *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBDEV_G_SELECTION, VIDIOC_SUBDEV_S_SELECTION
+
+``argp``
+
+
+Description
+===========
+
+The selections are used to configure various image processing
+functionality performed by the subdevs which affect the image size. This
+currently includes cropping, scaling and composition.
+
+The selection API replaces
+:ref:`the old subdev crop API <VIDIOC_SUBDEV_G_CROP>`. All the
+function of the crop API, and more, are supported by the selections API.
+
+See :ref:`subdev` for more information on how each selection target
+affects the image processing pipeline inside the subdevice.
+
+
+Types of selection targets
+--------------------------
+
+There are two types of selection targets: actual and bounds. The actual
+targets are the targets which configure the hardware. The BOUNDS target
+will return a rectangle that contain all possible actual rectangles.
+
+
+Discovering supported features
+------------------------------
+
+To discover which targets are supported, the user can perform
+``VIDIOC_SUBDEV_G_SELECTION`` on them. Any unsupported target will
+return ``EINVAL``.
+
+Selection targets and flags are documented in
+:ref:`v4l2-selections-common`.
+
+
+.. _v4l2-subdev-selection:
+
+.. flat-table:: struct v4l2_subdev_selection
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``which``
+
+ - Active or try selection, from enum
+ :ref:`v4l2_subdev_format_whence <v4l2-subdev-format-whence>`.
+
+ - .. row 2
+
+ - __u32
+
+ - ``pad``
+
+ - Pad number as reported by the media framework.
+
+ - .. row 3
+
+ - __u32
+
+ - ``target``
+
+ - Target selection rectangle. See :ref:`v4l2-selections-common`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``flags``
+
+ - Flags. See :ref:`v4l2-selection-flags`.
+
+ - .. row 5
+
+ - struct :ref:`v4l2_rect <v4l2-rect>`
+
+ - ``r``
+
+ - Selection rectangle, in pixels.
+
+ - .. row 6
+
+ - __u32
+
+ - ``reserved``\ [8]
+
+ - Reserved for future extensions. Applications and drivers must set
+ the array to zero.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
+
+EBUSY
+ The selection rectangle can't be changed because the pad is
+ currently busy. This can be caused, for instance, by an active video
+ stream on the pad. The ioctl must not be retried without performing
+ another action to fix the problem first. Only returned by
+ ``VIDIOC_SUBDEV_S_SELECTION``
+
+EINVAL
+ The struct :ref:`v4l2_subdev_selection <v4l2-subdev-selection>`
+ ``pad`` references a non-existing pad, the ``which`` field
+ references a non-existing format, or the selection target is not
+ supported on the given subdev pad.
diff --git a/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst
new file mode 100644
index 000000000000..a027f602de3d
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-subscribe-event.rst
@@ -0,0 +1,135 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _VIDIOC_SUBSCRIBE_EVENT:
+
+******************************************************
+ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
+******************************************************
+
+Name
+====
+
+VIDIOC_SUBSCRIBE_EVENT - VIDIOC_UNSUBSCRIBE_EVENT - Subscribe or unsubscribe event
+
+
+Synopsis
+========
+
+.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event_subscription *argp )
+
+
+Arguments
+=========
+
+``fd``
+ File descriptor returned by :ref:`open() <func-open>`.
+
+``request``
+ VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT
+
+``argp``
+
+
+Description
+===========
+
+Subscribe or unsubscribe V4L2 event. Subscribed events are dequeued by
+using the :ref:`VIDIOC_DQEVENT` ioctl.
+
+
+.. _v4l2-event-subscription:
+
+.. flat-table:: struct v4l2_event_subscription
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 1 2
+
+
+ - .. row 1
+
+ - __u32
+
+ - ``type``
+
+ - Type of the event, see :ref:`event-type`. Note that
+ ``V4L2_EVENT_ALL`` can be used with VIDIOC_UNSUBSCRIBE_EVENT for
+ unsubscribing all events at once.
+
+ - .. row 2
+
+ - __u32
+
+ - ``id``
+
+ - ID of the event source. If there is no ID associated with the
+ event source, then set this to 0. Whether or not an event needs an
+ ID depends on the event type.
+
+ - .. row 3
+
+ - __u32
+
+ - ``flags``
+
+ - Event flags, see :ref:`event-flags`.
+
+ - .. row 4
+
+ - __u32
+
+ - ``reserved``\ [5]
+
+ - Reserved for future extensions. Drivers and applications must set
+ the array to zero.
+
+
+
+.. _event-flags:
+
+.. flat-table:: Event Flags
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 3 1 4
+
+
+ - .. row 1
+
+ - ``V4L2_EVENT_SUB_FL_SEND_INITIAL``
+
+ - 0x0001
+
+ - When this event is subscribed an initial event will be sent
+ containing the current status. This only makes sense for events
+ that are triggered by a status change such as ``V4L2_EVENT_CTRL``.
+ Other events will ignore this flag.
+
+ - .. row 2
+
+ - ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK``
+
+ - 0x0002
+
+ - If set, then events directly caused by an ioctl will also be sent
+ to the filehandle that called that ioctl. For example, changing a
+ control using :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` will cause
+ a V4L2_EVENT_CTRL to be sent back to that same filehandle.
+ Normally such events are suppressed to prevent feedback loops
+ where an application changes a control to a one value and then
+ another, and then receives an event telling it that that control
+ has changed to the first value.
+
+ Since it can't tell whether that event was caused by another
+ application or by the :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>`
+ call it is hard to decide whether to set the control to the value
+ in the event, or ignore it.
+
+ Think carefully when you set this flag so you won't get into
+ situations like that.
+
+
+Return Value
+============
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes <gen-errors>` chapter.
diff --git a/Documentation/media/uapi/v4l/yuv-formats.rst b/Documentation/media/uapi/v4l/yuv-formats.rst
new file mode 100644
index 000000000000..3334ea445657
--- /dev/null
+++ b/Documentation/media/uapi/v4l/yuv-formats.rst
@@ -0,0 +1,55 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _yuv-formats:
+
+***********
+YUV Formats
+***********
+
+YUV is the format native to TV broadcast and composite video signals. It
+separates the brightness information (Y) from the color information (U
+and V or Cb and Cr). The color information consists of red and blue
+*color difference* signals, this way the green component can be
+reconstructed by subtracting from the brightness component. See
+:ref:`colorspaces` for conversion examples. YUV was chosen because
+early television would only transmit brightness information. To add
+color in a way compatible with existing receivers a new signal carrier
+was added to transmit the color difference signals. Secondary in the YUV
+format the U and V components usually have lower resolution than the Y
+component. This is an analog video compression technique taking
+advantage of a property of the human visual system, being more sensitive
+to brightness information.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ pixfmt-packed-yuv
+ pixfmt-grey
+ pixfmt-y10
+ pixfmt-y12
+ pixfmt-y10b
+ pixfmt-y16
+ pixfmt-y16-be
+ pixfmt-y8i
+ pixfmt-y12i
+ pixfmt-uv8
+ pixfmt-yuyv
+ pixfmt-uyvy
+ pixfmt-yvyu
+ pixfmt-vyuy
+ pixfmt-y41p
+ pixfmt-yuv420
+ pixfmt-yuv420m
+ pixfmt-yuv422m
+ pixfmt-yuv444m
+ pixfmt-yuv410
+ pixfmt-yuv422p
+ pixfmt-yuv411p
+ pixfmt-nv12
+ pixfmt-nv12m
+ pixfmt-nv12mt
+ pixfmt-nv16
+ pixfmt-nv16m
+ pixfmt-nv24
+ pixfmt-m420