aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/ABI/testing/sysfs-bus-media6
-rw-r--r--Documentation/DocBook/Makefile5
-rw-r--r--Documentation/DocBook/media-entities.tmpl59
-rw-r--r--Documentation/DocBook/media.tmpl3
-rw-r--r--Documentation/DocBook/v4l/bayer.pdfbin0 -> 12116 bytes
-rw-r--r--Documentation/DocBook/v4l/bayer.pngbin0 -> 9725 bytes
-rw-r--r--Documentation/DocBook/v4l/common.xml2
-rw-r--r--Documentation/DocBook/v4l/compat.xml26
-rw-r--r--Documentation/DocBook/v4l/dev-capture.xml13
-rw-r--r--Documentation/DocBook/v4l/dev-output.xml13
-rw-r--r--Documentation/DocBook/v4l/dev-subdev.xml313
-rw-r--r--Documentation/DocBook/v4l/func-mmap.xml10
-rw-r--r--Documentation/DocBook/v4l/func-munmap.xml3
-rw-r--r--Documentation/DocBook/v4l/io.xml283
-rw-r--r--Documentation/DocBook/v4l/lirc_device_interface.xml2
-rw-r--r--Documentation/DocBook/v4l/media-controller.xml89
-rw-r--r--Documentation/DocBook/v4l/media-func-close.xml59
-rw-r--r--Documentation/DocBook/v4l/media-func-ioctl.xml116
-rw-r--r--Documentation/DocBook/v4l/media-func-open.xml94
-rw-r--r--Documentation/DocBook/v4l/media-ioc-device-info.xml133
-rw-r--r--Documentation/DocBook/v4l/media-ioc-enum-entities.xml308
-rw-r--r--Documentation/DocBook/v4l/media-ioc-enum-links.xml207
-rw-r--r--Documentation/DocBook/v4l/media-ioc-setup-link.xml93
-rw-r--r--Documentation/DocBook/v4l/nv12mt.gifbin0 -> 2108 bytes
-rw-r--r--Documentation/DocBook/v4l/nv12mt_example.gifbin0 -> 6858 bytes
-rw-r--r--Documentation/DocBook/v4l/pipeline.pdfbin0 -> 20276 bytes
-rw-r--r--Documentation/DocBook/v4l/pipeline.pngbin0 -> 12130 bytes
-rw-r--r--Documentation/DocBook/v4l/pixfmt-nv12m.xml154
-rw-r--r--Documentation/DocBook/v4l/pixfmt-nv12mt.xml74
-rw-r--r--Documentation/DocBook/v4l/pixfmt-srggb12.xml90
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv420m.xml162
-rw-r--r--Documentation/DocBook/v4l/pixfmt.xml119
-rw-r--r--Documentation/DocBook/v4l/planar-apis.xml62
-rw-r--r--Documentation/DocBook/v4l/subdev-formats.xml2467
-rw-r--r--Documentation/DocBook/v4l/v4l2.xml30
-rw-r--r--Documentation/DocBook/v4l/videodev2.h.xml141
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-fmt.xml2
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-fmt.xml15
-rw-r--r--Documentation/DocBook/v4l/vidioc-qbuf.xml24
-rw-r--r--Documentation/DocBook/v4l/vidioc-querybuf.xml14
-rw-r--r--Documentation/DocBook/v4l/vidioc-querycap.xml18
-rw-r--r--Documentation/DocBook/v4l/vidioc-streamon.xml9
-rw-r--r--Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml152
-rw-r--r--Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml154
-rw-r--r--Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml119
-rw-r--r--Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml155
-rw-r--r--Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml180
-rw-r--r--Documentation/DocBook/v4l/vidioc-subdev-g-frame-interval.xml141
-rw-r--r--Documentation/dvb/get_dvb_firmware8
-rw-r--r--Documentation/dvb/lmedm04.txt16
-rw-r--r--Documentation/feature-removal-schedule.txt36
-rw-r--r--Documentation/ioctl/ioctl-number.txt1
-rw-r--r--Documentation/media-framework.txt353
-rw-r--r--Documentation/video4linux/README.ivtv3
-rw-r--r--Documentation/video4linux/gspca.txt10
-rw-r--r--Documentation/video4linux/omap3isp.txt278
-rw-r--r--Documentation/video4linux/v4l2-framework.txt267
57 files changed, 6905 insertions, 186 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-media b/Documentation/ABI/testing/sysfs-bus-media
new file mode 100644
index 000000000000..7057e574154a
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-media
@@ -0,0 +1,6 @@
1What: /sys/bus/media/devices/.../model
2Date: January 2011
3Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
4 linux-media@vger.kernel.org
5Description: Contains the device model name in UTF-8. The device version is
6 is not be appended to the model name.
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 8b6e00a71034..2deb069aedf1 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -53,7 +53,10 @@ MAN := $(patsubst %.xml, %.9, $(BOOKS))
53mandocs: $(MAN) 53mandocs: $(MAN)
54 54
55build_images = mkdir -p $(objtree)/Documentation/DocBook/media/ && \ 55build_images = mkdir -p $(objtree)/Documentation/DocBook/media/ && \
56 cp $(srctree)/Documentation/DocBook/dvb/*.png $(srctree)/Documentation/DocBook/v4l/*.gif $(objtree)/Documentation/DocBook/media/ 56 cp $(srctree)/Documentation/DocBook/dvb/*.png \
57 $(srctree)/Documentation/DocBook/v4l/*.gif \
58 $(srctree)/Documentation/DocBook/v4l/*.png \
59 $(objtree)/Documentation/DocBook/media/
57 60
58xmldoclinks: 61xmldoclinks:
59ifneq ($(objtree),$(srctree)) 62ifneq ($(objtree),$(srctree))
diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl
index be34dcbe0d90..5d259c632cdf 100644
--- a/Documentation/DocBook/media-entities.tmpl
+++ b/Documentation/DocBook/media-entities.tmpl
@@ -11,6 +11,10 @@
11<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>"> 11<!ENTITY func-select "<link linkend='func-select'><function>select()</function></link>">
12<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>"> 12<!ENTITY func-write "<link linkend='func-write'><function>write()</function></link>">
13 13
14<!ENTITY media-func-close "<link linkend='media-func-close'><function>close()</function></link>">
15<!ENTITY media-func-ioctl "<link linkend='media-func-ioctl'><function>ioctl()</function></link>">
16<!ENTITY media-func-open "<link linkend='media-func-open'><function>open()</function></link>">
17
14<!-- Ioctls --> 18<!-- Ioctls -->
15<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>"> 19<!ENTITY VIDIOC-CROPCAP "<link linkend='vidioc-cropcap'><constant>VIDIOC_CROPCAP</constant></link>">
16<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>"> 20<!ENTITY VIDIOC-DBG-G-CHIP-IDENT "<link linkend='vidioc-dbg-g-chip-ident'><constant>VIDIOC_DBG_G_CHIP_IDENT</constant></link>">
@@ -82,11 +86,24 @@
82<!ENTITY VIDIOC-S-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_S_PRIORITY</constant></link>"> 86<!ENTITY VIDIOC-S-PRIORITY "<link linkend='vidioc-g-priority'><constant>VIDIOC_S_PRIORITY</constant></link>">
83<!ENTITY VIDIOC-S-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_S_STD</constant></link>"> 87<!ENTITY VIDIOC-S-STD "<link linkend='vidioc-g-std'><constant>VIDIOC_S_STD</constant></link>">
84<!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>"> 88<!ENTITY VIDIOC-S-TUNER "<link linkend='vidioc-g-tuner'><constant>VIDIOC_S_TUNER</constant></link>">
89<!ENTITY VIDIOC-SUBDEV-ENUM-FRAME-SIZE "<link linkend='vidioc-subdev-enum-frame-size'><constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant></link>">
90<!ENTITY VIDIOC-SUBDEV-ENUM-MBUS-CODE "<link linkend='vidioc-subdev-enum-mbus-code'><constant>VIDIOC_SUBDEV_ENUM_MBUS_CODE</constant></link>">
91<!ENTITY VIDIOC-SUBDEV-G-CROP "<link linkend='vidioc-subdev-g-crop'><constant>VIDIOC_SUBDEV_G_CROP</constant></link>">
92<!ENTITY VIDIOC-SUBDEV-G-FMT "<link linkend='vidioc-subdev-g-fmt'><constant>VIDIOC_SUBDEV_G_FMT</constant></link>">
93<!ENTITY VIDIOC-SUBDEV-G-FRAME-INTERVAL "<link linkend='vidioc-subdev-g-frame-interval'><constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant></link>">
94<!ENTITY VIDIOC-SUBDEV-S-CROP "<link linkend='vidioc-subdev-g-crop'><constant>VIDIOC_SUBDEV_S_CROP</constant></link>">
95<!ENTITY VIDIOC-SUBDEV-S-FMT "<link linkend='vidioc-subdev-g-fmt'><constant>VIDIOC_SUBDEV_S_FMT</constant></link>">
96<!ENTITY VIDIOC-SUBDEV-S-FRAME-INTERVAL "<link linkend='vidioc-subdev-g-frame-interval'><constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant></link>">
85<!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>"> 97<!ENTITY VIDIOC-TRY-ENCODER-CMD "<link linkend='vidioc-encoder-cmd'><constant>VIDIOC_TRY_ENCODER_CMD</constant></link>">
86<!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>"> 98<!ENTITY VIDIOC-TRY-EXT-CTRLS "<link linkend='vidioc-g-ext-ctrls'><constant>VIDIOC_TRY_EXT_CTRLS</constant></link>">
87<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>"> 99<!ENTITY VIDIOC-TRY-FMT "<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>">
88<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>"> 100<!ENTITY VIDIOC-UNSUBSCRIBE-EVENT "<link linkend='vidioc-subscribe-event'><constant>VIDIOC_UNSUBSCRIBE_EVENT</constant></link>">
89 101
102<!ENTITY MEDIA-IOC-DEVICE-INFO "<link linkend='media-ioc-device-info'><constant>MEDIA_IOC_DEVICE_INFO</constant></link>">
103<!ENTITY MEDIA-IOC-ENUM-ENTITIES "<link linkend='media-ioc-enum-entities'><constant>MEDIA_IOC_ENUM_ENTITIES</constant></link>">
104<!ENTITY MEDIA-IOC-ENUM-LINKS "<link linkend='media-ioc-enum-links'><constant>MEDIA_IOC_ENUM_LINKS</constant></link>">
105<!ENTITY MEDIA-IOC-SETUP-LINK "<link linkend='media-ioc-setup-link'><constant>MEDIA_IOC_SETUP_LINK</constant></link>">
106
90<!-- Types --> 107<!-- Types -->
91<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>"> 108<!ENTITY v4l2-std-id "<link linkend='v4l2-std-id'>v4l2_std_id</link>">
92 109
@@ -98,6 +115,7 @@
98<!ENTITY v4l2-field "enum&nbsp;<link linkend='v4l2-field'>v4l2_field</link>"> 115<!ENTITY v4l2-field "enum&nbsp;<link linkend='v4l2-field'>v4l2_field</link>">
99<!ENTITY v4l2-frmivaltypes "enum&nbsp;<link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>"> 116<!ENTITY v4l2-frmivaltypes "enum&nbsp;<link linkend='v4l2-frmivaltypes'>v4l2_frmivaltypes</link>">
100<!ENTITY v4l2-frmsizetypes "enum&nbsp;<link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>"> 117<!ENTITY v4l2-frmsizetypes "enum&nbsp;<link linkend='v4l2-frmsizetypes'>v4l2_frmsizetypes</link>">
118<!ENTITY v4l2-mbus-pixelcode "enum&nbsp;<link linkend='v4l2-mbus-pixelcode'>v4l2_mbus_pixelcode</link>">
101<!ENTITY v4l2-memory "enum&nbsp;<link linkend='v4l2-memory'>v4l2_memory</link>"> 119<!ENTITY v4l2-memory "enum&nbsp;<link linkend='v4l2-memory'>v4l2_memory</link>">
102<!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>"> 120<!ENTITY v4l2-mpeg-audio-ac3-bitrate "enum&nbsp;<link linkend='v4l2-mpeg-audio-ac3-bitrate'>v4l2_mpeg_audio_ac3_bitrate</link>">
103<!ENTITY v4l2-mpeg-audio-crc "enum&nbsp;<link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>"> 121<!ENTITY v4l2-mpeg-audio-crc "enum&nbsp;<link linkend='v4l2-mpeg-audio-crc'>v4l2_mpeg_audio_crc</link>">
@@ -121,6 +139,7 @@
121<!ENTITY v4l2-mpeg-video-encoding "enum&nbsp;<link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>"> 139<!ENTITY v4l2-mpeg-video-encoding "enum&nbsp;<link linkend='v4l2-mpeg-video-encoding'>v4l2_mpeg_video_encoding</link>">
122<!ENTITY v4l2-power-line-frequency "enum&nbsp;<link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>"> 140<!ENTITY v4l2-power-line-frequency "enum&nbsp;<link linkend='v4l2-power-line-frequency'>v4l2_power_line_frequency</link>">
123<!ENTITY v4l2-priority "enum&nbsp;<link linkend='v4l2-priority'>v4l2_priority</link>"> 141<!ENTITY v4l2-priority "enum&nbsp;<link linkend='v4l2-priority'>v4l2_priority</link>">
142<!ENTITY v4l2-subdev-format-whence "enum&nbsp;<link linkend='v4l2-subdev-format-whence'>v4l2_subdev_format_whence</link>">
124<!ENTITY v4l2-tuner-type "enum&nbsp;<link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>"> 143<!ENTITY v4l2-tuner-type "enum&nbsp;<link linkend='v4l2-tuner-type'>v4l2_tuner_type</link>">
125<!ENTITY v4l2-preemphasis "enum&nbsp;<link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>"> 144<!ENTITY v4l2-preemphasis "enum&nbsp;<link linkend='v4l2-preemphasis'>v4l2_preemphasis</link>">
126 145
@@ -129,6 +148,7 @@
129<!ENTITY v4l2-audioout "struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link>"> 148<!ENTITY v4l2-audioout "struct&nbsp;<link linkend='v4l2-audioout'>v4l2_audioout</link>">
130<!ENTITY v4l2-bt-timings "struct&nbsp;<link linkend='v4l2-bt-timings'>v4l2_bt_timings</link>"> 149<!ENTITY v4l2-bt-timings "struct&nbsp;<link linkend='v4l2-bt-timings'>v4l2_bt_timings</link>">
131<!ENTITY v4l2-buffer "struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link>"> 150<!ENTITY v4l2-buffer "struct&nbsp;<link linkend='v4l2-buffer'>v4l2_buffer</link>">
151<!ENTITY v4l2-plane "struct&nbsp;<link linkend='v4l2-plane'>v4l2_plane</link>">
132<!ENTITY v4l2-capability "struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link>"> 152<!ENTITY v4l2-capability "struct&nbsp;<link linkend='v4l2-capability'>v4l2_capability</link>">
133<!ENTITY v4l2-captureparm "struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link>"> 153<!ENTITY v4l2-captureparm "struct&nbsp;<link linkend='v4l2-captureparm'>v4l2_captureparm</link>">
134<!ENTITY v4l2-clip "struct&nbsp;<link linkend='v4l2-clip'>v4l2_clip</link>"> 154<!ENTITY v4l2-clip "struct&nbsp;<link linkend='v4l2-clip'>v4l2_clip</link>">
@@ -162,11 +182,14 @@
162<!ENTITY v4l2-hw-freq-seek "struct&nbsp;<link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>"> 182<!ENTITY v4l2-hw-freq-seek "struct&nbsp;<link linkend='v4l2-hw-freq-seek'>v4l2_hw_freq_seek</link>">
163<!ENTITY v4l2-input "struct&nbsp;<link linkend='v4l2-input'>v4l2_input</link>"> 183<!ENTITY v4l2-input "struct&nbsp;<link linkend='v4l2-input'>v4l2_input</link>">
164<!ENTITY v4l2-jpegcompression "struct&nbsp;<link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>"> 184<!ENTITY v4l2-jpegcompression "struct&nbsp;<link linkend='v4l2-jpegcompression'>v4l2_jpegcompression</link>">
185<!ENTITY v4l2-mbus-framefmt "struct&nbsp;<link linkend='v4l2-mbus-framefmt'>v4l2_mbus_framefmt</link>">
165<!ENTITY v4l2-modulator "struct&nbsp;<link linkend='v4l2-modulator'>v4l2_modulator</link>"> 186<!ENTITY v4l2-modulator "struct&nbsp;<link linkend='v4l2-modulator'>v4l2_modulator</link>">
166<!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct&nbsp;<link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>"> 187<!ENTITY v4l2-mpeg-vbi-fmt-ivtv "struct&nbsp;<link linkend='v4l2-mpeg-vbi-fmt-ivtv'>v4l2_mpeg_vbi_fmt_ivtv</link>">
167<!ENTITY v4l2-output "struct&nbsp;<link linkend='v4l2-output'>v4l2_output</link>"> 188<!ENTITY v4l2-output "struct&nbsp;<link linkend='v4l2-output'>v4l2_output</link>">
168<!ENTITY v4l2-outputparm "struct&nbsp;<link linkend='v4l2-outputparm'>v4l2_outputparm</link>"> 189<!ENTITY v4l2-outputparm "struct&nbsp;<link linkend='v4l2-outputparm'>v4l2_outputparm</link>">
169<!ENTITY v4l2-pix-format "struct&nbsp;<link linkend='v4l2-pix-format'>v4l2_pix_format</link>"> 190<!ENTITY v4l2-pix-format "struct&nbsp;<link linkend='v4l2-pix-format'>v4l2_pix_format</link>">
191<!ENTITY v4l2-pix-format-mplane "struct&nbsp;<link linkend='v4l2-pix-format-mplane'>v4l2_pix_format_mplane</link>">
192<!ENTITY v4l2-plane-pix-format "struct&nbsp;<link linkend='v4l2-plane-pix-format'>v4l2_plane_pix_format</link>">
170<!ENTITY v4l2-queryctrl "struct&nbsp;<link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>"> 193<!ENTITY v4l2-queryctrl "struct&nbsp;<link linkend='v4l2-queryctrl'>v4l2_queryctrl</link>">
171<!ENTITY v4l2-querymenu "struct&nbsp;<link linkend='v4l2-querymenu'>v4l2_querymenu</link>"> 194<!ENTITY v4l2-querymenu "struct&nbsp;<link linkend='v4l2-querymenu'>v4l2_querymenu</link>">
172<!ENTITY v4l2-rect "struct&nbsp;<link linkend='v4l2-rect'>v4l2_rect</link>"> 195<!ENTITY v4l2-rect "struct&nbsp;<link linkend='v4l2-rect'>v4l2_rect</link>">
@@ -174,6 +197,12 @@
174<!ENTITY v4l2-sliced-vbi-cap "struct&nbsp;<link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>"> 197<!ENTITY v4l2-sliced-vbi-cap "struct&nbsp;<link linkend='v4l2-sliced-vbi-cap'>v4l2_sliced_vbi_cap</link>">
175<!ENTITY v4l2-sliced-vbi-data "struct&nbsp;<link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>"> 198<!ENTITY v4l2-sliced-vbi-data "struct&nbsp;<link linkend='v4l2-sliced-vbi-data'>v4l2_sliced_vbi_data</link>">
176<!ENTITY v4l2-sliced-vbi-format "struct&nbsp;<link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>"> 199<!ENTITY v4l2-sliced-vbi-format "struct&nbsp;<link linkend='v4l2-sliced-vbi-format'>v4l2_sliced_vbi_format</link>">
200<!ENTITY v4l2-subdev-frame-interval "struct&nbsp;<link linkend='v4l2-subdev-frame-interval'>v4l2_subdev_frame_interval</link>">
201<!ENTITY v4l2-subdev-frame-interval-enum "struct&nbsp;<link linkend='v4l2-subdev-frame-interval-enum'>v4l2_subdev_frame_interval_enum</link>">
202<!ENTITY v4l2-subdev-frame-size-enum "struct&nbsp;<link linkend='v4l2-subdev-frame-size-enum'>v4l2_subdev_frame_size_enum</link>">
203<!ENTITY v4l2-subdev-crop "struct&nbsp;<link linkend='v4l2-subdev-crop'>v4l2_subdev_crop</link>">
204<!ENTITY v4l2-subdev-format "struct&nbsp;<link linkend='v4l2-subdev-format'>v4l2_subdev_format</link>">
205<!ENTITY v4l2-subdev-mbus-code-enum "struct&nbsp;<link linkend='v4l2-subdev-mbus-code-enum'>v4l2_subdev_mbus_code_enum</link>">
177<!ENTITY v4l2-standard "struct&nbsp;<link linkend='v4l2-standard'>v4l2_standard</link>"> 206<!ENTITY v4l2-standard "struct&nbsp;<link linkend='v4l2-standard'>v4l2_standard</link>">
178<!ENTITY v4l2-streamparm "struct&nbsp;<link linkend='v4l2-streamparm'>v4l2_streamparm</link>"> 207<!ENTITY v4l2-streamparm "struct&nbsp;<link linkend='v4l2-streamparm'>v4l2_streamparm</link>">
179<!ENTITY v4l2-timecode "struct&nbsp;<link linkend='v4l2-timecode'>v4l2_timecode</link>"> 208<!ENTITY v4l2-timecode "struct&nbsp;<link linkend='v4l2-timecode'>v4l2_timecode</link>">
@@ -181,6 +210,12 @@
181<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>"> 210<!ENTITY v4l2-vbi-format "struct&nbsp;<link linkend='v4l2-vbi-format'>v4l2_vbi_format</link>">
182<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>"> 211<!ENTITY v4l2-window "struct&nbsp;<link linkend='v4l2-window'>v4l2_window</link>">
183 212
213<!ENTITY media-device-info "struct&nbsp;<link linkend='media-device-info'>media_device_info</link>">
214<!ENTITY media-entity-desc "struct&nbsp;<link linkend='media-entity-desc'>media_entity_desc</link>">
215<!ENTITY media-links-enum "struct&nbsp;<link linkend='media-links-enum'>media_links_enum</link>">
216<!ENTITY media-pad-desc "struct&nbsp;<link linkend='media-pad-desc'>media_pad_desc</link>">
217<!ENTITY media-link-desc "struct&nbsp;<link linkend='media-link-desc'>media_link_desc</link>">
218
184<!-- Error Codes --> 219<!-- Error Codes -->
185<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code"> 220<!ENTITY EACCES "<errorcode>EACCES</errorcode> error code">
186<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code"> 221<!ENTITY EAGAIN "<errorcode>EAGAIN</errorcode> error code">
@@ -197,11 +232,13 @@
197<!ENTITY ENXIO "<errorcode>ENXIO</errorcode> error code"> 232<!ENTITY ENXIO "<errorcode>ENXIO</errorcode> error code">
198<!ENTITY EMFILE "<errorcode>EMFILE</errorcode> error code"> 233<!ENTITY EMFILE "<errorcode>EMFILE</errorcode> error code">
199<!ENTITY EPERM "<errorcode>EPERM</errorcode> error code"> 234<!ENTITY EPERM "<errorcode>EPERM</errorcode> error code">
235<!ENTITY EPIPE "<errorcode>EPIPE</errorcode> error code">
200<!ENTITY ERANGE "<errorcode>ERANGE</errorcode> error code"> 236<!ENTITY ERANGE "<errorcode>ERANGE</errorcode> error code">
201 237
202<!-- Subsections --> 238<!-- Subsections -->
203<!ENTITY sub-biblio SYSTEM "v4l/biblio.xml"> 239<!ENTITY sub-biblio SYSTEM "v4l/biblio.xml">
204<!ENTITY sub-common SYSTEM "v4l/common.xml"> 240<!ENTITY sub-common SYSTEM "v4l/common.xml">
241<!ENTITY sub-planar-apis SYSTEM "v4l/planar-apis.xml">
205<!ENTITY sub-compat SYSTEM "v4l/compat.xml"> 242<!ENTITY sub-compat SYSTEM "v4l/compat.xml">
206<!ENTITY sub-controls SYSTEM "v4l/controls.xml"> 243<!ENTITY sub-controls SYSTEM "v4l/controls.xml">
207<!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml"> 244<!ENTITY sub-dev-capture SYSTEM "v4l/dev-capture.xml">
@@ -215,6 +252,7 @@
215<!ENTITY sub-dev-raw-vbi SYSTEM "v4l/dev-raw-vbi.xml"> 252<!ENTITY sub-dev-raw-vbi SYSTEM "v4l/dev-raw-vbi.xml">
216<!ENTITY sub-dev-rds SYSTEM "v4l/dev-rds.xml"> 253<!ENTITY sub-dev-rds SYSTEM "v4l/dev-rds.xml">
217<!ENTITY sub-dev-sliced-vbi SYSTEM "v4l/dev-sliced-vbi.xml"> 254<!ENTITY sub-dev-sliced-vbi SYSTEM "v4l/dev-sliced-vbi.xml">
255<!ENTITY sub-dev-subdev SYSTEM "v4l/dev-subdev.xml">
218<!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml"> 256<!ENTITY sub-dev-teletext SYSTEM "v4l/dev-teletext.xml">
219<!ENTITY sub-driver SYSTEM "v4l/driver.xml"> 257<!ENTITY sub-driver SYSTEM "v4l/driver.xml">
220<!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml"> 258<!ENTITY sub-libv4l SYSTEM "v4l/libv4l.xml">
@@ -233,6 +271,8 @@
233<!ENTITY sub-io SYSTEM "v4l/io.xml"> 271<!ENTITY sub-io SYSTEM "v4l/io.xml">
234<!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml"> 272<!ENTITY sub-grey SYSTEM "v4l/pixfmt-grey.xml">
235<!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml"> 273<!ENTITY sub-nv12 SYSTEM "v4l/pixfmt-nv12.xml">
274<!ENTITY sub-nv12m SYSTEM "v4l/pixfmt-nv12m.xml">
275<!ENTITY sub-nv12mt SYSTEM "v4l/pixfmt-nv12mt.xml">
236<!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml"> 276<!ENTITY sub-nv16 SYSTEM "v4l/pixfmt-nv16.xml">
237<!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> 277<!ENTITY sub-packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">
238<!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> 278<!ENTITY sub-packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
@@ -247,6 +287,7 @@
247<!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> 287<!ENTITY sub-yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">
248<!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> 288<!ENTITY sub-yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">
249<!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> 289<!ENTITY sub-yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">
290<!ENTITY sub-yuv420m SYSTEM "v4l/pixfmt-yuv420m.xml">
250<!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> 291<!ENTITY sub-yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">
251<!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> 292<!ENTITY sub-yuyv SYSTEM "v4l/pixfmt-yuyv.xml">
252<!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> 293<!ENTITY sub-yvyu SYSTEM "v4l/pixfmt-yvyu.xml">
@@ -298,6 +339,13 @@
298<!ENTITY sub-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml"> 339<!ENTITY sub-reqbufs SYSTEM "v4l/vidioc-reqbufs.xml">
299<!ENTITY sub-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml"> 340<!ENTITY sub-s-hw-freq-seek SYSTEM "v4l/vidioc-s-hw-freq-seek.xml">
300<!ENTITY sub-streamon SYSTEM "v4l/vidioc-streamon.xml"> 341<!ENTITY sub-streamon SYSTEM "v4l/vidioc-streamon.xml">
342<!ENTITY sub-subdev-enum-frame-interval SYSTEM "v4l/vidioc-subdev-enum-frame-interval.xml">
343<!ENTITY sub-subdev-enum-frame-size SYSTEM "v4l/vidioc-subdev-enum-frame-size.xml">
344<!ENTITY sub-subdev-enum-mbus-code SYSTEM "v4l/vidioc-subdev-enum-mbus-code.xml">
345<!ENTITY sub-subdev-formats SYSTEM "v4l/subdev-formats.xml">
346<!ENTITY sub-subdev-g-crop SYSTEM "v4l/vidioc-subdev-g-crop.xml">
347<!ENTITY sub-subdev-g-fmt SYSTEM "v4l/vidioc-subdev-g-fmt.xml">
348<!ENTITY sub-subdev-g-frame-interval SYSTEM "v4l/vidioc-subdev-g-frame-interval.xml">
301<!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml"> 349<!ENTITY sub-capture-c SYSTEM "v4l/capture.c.xml">
302<!ENTITY sub-keytable-c SYSTEM "v4l/keytable.c.xml"> 350<!ENTITY sub-keytable-c SYSTEM "v4l/keytable.c.xml">
303<!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml"> 351<!ENTITY sub-v4l2grab-c SYSTEM "v4l/v4l2grab.c.xml">
@@ -321,6 +369,15 @@
321<!ENTITY sub-media-entities SYSTEM "media-entities.tmpl"> 369<!ENTITY sub-media-entities SYSTEM "media-entities.tmpl">
322<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl"> 370<!ENTITY sub-media-indices SYSTEM "media-indices.tmpl">
323 371
372<!ENTITY sub-media-controller SYSTEM "v4l/media-controller.xml">
373<!ENTITY sub-media-open SYSTEM "v4l/media-func-open.xml">
374<!ENTITY sub-media-close SYSTEM "v4l/media-func-close.xml">
375<!ENTITY sub-media-ioctl SYSTEM "v4l/media-func-ioctl.xml">
376<!ENTITY sub-media-ioc-device-info SYSTEM "v4l/media-ioc-device-info.xml">
377<!ENTITY sub-media-ioc-enum-entities SYSTEM "v4l/media-ioc-enum-entities.xml">
378<!ENTITY sub-media-ioc-enum-links SYSTEM "v4l/media-ioc-enum-links.xml">
379<!ENTITY sub-media-ioc-setup-link SYSTEM "v4l/media-ioc-setup-link.xml">
380
324<!-- Function Reference --> 381<!-- Function Reference -->
325<!ENTITY close SYSTEM "v4l/func-close.xml"> 382<!ENTITY close SYSTEM "v4l/func-close.xml">
326<!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml"> 383<!ENTITY ioctl SYSTEM "v4l/func-ioctl.xml">
@@ -333,6 +390,7 @@
333<!ENTITY write SYSTEM "v4l/func-write.xml"> 390<!ENTITY write SYSTEM "v4l/func-write.xml">
334<!ENTITY grey SYSTEM "v4l/pixfmt-grey.xml"> 391<!ENTITY grey SYSTEM "v4l/pixfmt-grey.xml">
335<!ENTITY nv12 SYSTEM "v4l/pixfmt-nv12.xml"> 392<!ENTITY nv12 SYSTEM "v4l/pixfmt-nv12.xml">
393<!ENTITY nv12m SYSTEM "v4l/pixfmt-nv12m.xml">
336<!ENTITY nv16 SYSTEM "v4l/pixfmt-nv16.xml"> 394<!ENTITY nv16 SYSTEM "v4l/pixfmt-nv16.xml">
337<!ENTITY packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml"> 395<!ENTITY packed-rgb SYSTEM "v4l/pixfmt-packed-rgb.xml">
338<!ENTITY packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml"> 396<!ENTITY packed-yuv SYSTEM "v4l/pixfmt-packed-yuv.xml">
@@ -347,6 +405,7 @@
347<!ENTITY yuv410 SYSTEM "v4l/pixfmt-yuv410.xml"> 405<!ENTITY yuv410 SYSTEM "v4l/pixfmt-yuv410.xml">
348<!ENTITY yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml"> 406<!ENTITY yuv411p SYSTEM "v4l/pixfmt-yuv411p.xml">
349<!ENTITY yuv420 SYSTEM "v4l/pixfmt-yuv420.xml"> 407<!ENTITY yuv420 SYSTEM "v4l/pixfmt-yuv420.xml">
408<!ENTITY yuv420m SYSTEM "v4l/pixfmt-yuv420m.xml">
350<!ENTITY yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml"> 409<!ENTITY yuv422p SYSTEM "v4l/pixfmt-yuv422p.xml">
351<!ENTITY yuyv SYSTEM "v4l/pixfmt-yuyv.xml"> 410<!ENTITY yuyv SYSTEM "v4l/pixfmt-yuyv.xml">
352<!ENTITY yvyu SYSTEM "v4l/pixfmt-yvyu.xml"> 411<!ENTITY yvyu SYSTEM "v4l/pixfmt-yvyu.xml">
diff --git a/Documentation/DocBook/media.tmpl b/Documentation/DocBook/media.tmpl
index a99088aae1aa..88f2cc680cc2 100644
--- a/Documentation/DocBook/media.tmpl
+++ b/Documentation/DocBook/media.tmpl
@@ -106,6 +106,9 @@ Foundation. A copy of the license is included in the chapter entitled
106&sub-remote_controllers; 106&sub-remote_controllers;
107</chapter> 107</chapter>
108</part> 108</part>
109<part id="media_common">
110&sub-media-controller;
111</part>
109 112
110&sub-fdl-appendix; 113&sub-fdl-appendix;
111 114
diff --git a/Documentation/DocBook/v4l/bayer.pdf b/Documentation/DocBook/v4l/bayer.pdf
new file mode 100644
index 000000000000..905e60e6cd42
--- /dev/null
+++ b/Documentation/DocBook/v4l/bayer.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/bayer.png b/Documentation/DocBook/v4l/bayer.png
new file mode 100644
index 000000000000..9b15fb22e817
--- /dev/null
+++ b/Documentation/DocBook/v4l/bayer.png
Binary files differ
diff --git a/Documentation/DocBook/v4l/common.xml b/Documentation/DocBook/v4l/common.xml
index cea23e1c4fc6..dbab79c215c1 100644
--- a/Documentation/DocBook/v4l/common.xml
+++ b/Documentation/DocBook/v4l/common.xml
@@ -846,6 +846,8 @@ conversion routine or library for integration into applications.</para>
846 </section> 846 </section>
847 </section> 847 </section>
848 848
849 &sub-planar-apis;
850
849 <section id="crop"> 851 <section id="crop">
850 <title>Image Cropping, Insertion and Scaling</title> 852 <title>Image Cropping, Insertion and Scaling</title>
851 853
diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml
index c9ce61d981f5..9f7cd4f25792 100644
--- a/Documentation/DocBook/v4l/compat.xml
+++ b/Documentation/DocBook/v4l/compat.xml
@@ -1711,8 +1711,8 @@ ioctl would enumerate the available audio inputs. An ioctl to
1711determine the current audio input, if more than one combines with the 1711determine the current audio input, if more than one combines with the
1712current video input, did not exist. So 1712current video input, did not exist. So
1713<constant>VIDIOC_G_AUDIO</constant> was renamed to 1713<constant>VIDIOC_G_AUDIO</constant> was renamed to
1714<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl will be removed in 1714<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl was removed on
1715the future. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate 1715Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
1716audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio 1716audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
1717input.</para> 1717input.</para>
1718 <para>The same changes were made to &VIDIOC-G-AUDOUT; and 1718 <para>The same changes were made to &VIDIOC-G-AUDOUT; and
@@ -1726,7 +1726,7 @@ must be updated to successfully compile again.</para>
1726 <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with 1726 <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
1727write-read parameter. It was changed to write-only, while the write-read 1727write-read parameter. It was changed to write-only, while the write-read
1728version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old 1728version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
1729ioctl will be removed in the future. Until further the "videodev" 1729ioctl was removed on Kernel 2.6.39. Until further the "videodev"
1730kernel module will automatically translate to the new version, so drivers 1730kernel module will automatically translate to the new version, so drivers
1731must be recompiled, but not applications.</para> 1731must be recompiled, but not applications.</para>
1732 </listitem> 1732 </listitem>
@@ -1744,7 +1744,7 @@ surface can be seen.</para>
1744defined with write-only parameter, inconsistent with other ioctls 1744defined with write-only parameter, inconsistent with other ioctls
1745modifying their argument. They were changed to write-read, while a 1745modifying their argument. They were changed to write-read, while a
1746<constant>_OLD</constant> suffix was added to the write-only versions. 1746<constant>_OLD</constant> suffix was added to the write-only versions.
1747The old ioctls will be removed in the future. Drivers and 1747The old ioctls were removed on Kernel 2.6.39. Drivers and
1748applications assuming a constant parameter need an update.</para> 1748applications assuming a constant parameter need an update.</para>
1749 </listitem> 1749 </listitem>
1750 </orderedlist> 1750 </orderedlist>
@@ -1815,8 +1815,8 @@ yet to be addressed, for details see <xref
1815 <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined 1815 <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined
1816with read-only parameter. It is now defined as write-read ioctl, while 1816with read-only parameter. It is now defined as write-read ioctl, while
1817the read-only version was renamed to 1817the read-only version was renamed to
1818<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl will be removed 1818<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl was removed
1819in the future.</para> 1819on Kernel 2.6.39.</para>
1820 </listitem> 1820 </listitem>
1821 </orderedlist> 1821 </orderedlist>
1822 </section> 1822 </section>
@@ -2353,6 +2353,20 @@ that used it. It was originally scheduled for removal in 2.6.35.
2353 </listitem> 2353 </listitem>
2354 </orderedlist> 2354 </orderedlist>
2355 </section> 2355 </section>
2356 <section>
2357 <title>V4L2 in Linux 2.6.39</title>
2358 <orderedlist>
2359 <listitem>
2360 <para>The old VIDIOC_*_OLD symbols and V4L1 support were removed.</para>
2361 </listitem>
2362 <listitem>
2363 <para>Multi-planar API added. Does not affect the compatibility of
2364 current drivers and applications. See
2365 <link linkend="planar-apis">multi-planar API</link>
2366 for details.</para>
2367 </listitem>
2368 </orderedlist>
2369 </section>
2356 2370
2357 <section id="other"> 2371 <section id="other">
2358 <title>Relation of V4L2 to other Linux multimedia APIs</title> 2372 <title>Relation of V4L2 to other Linux multimedia APIs</title>
diff --git a/Documentation/DocBook/v4l/dev-capture.xml b/Documentation/DocBook/v4l/dev-capture.xml
index 32807e43f170..2237c661f26a 100644
--- a/Documentation/DocBook/v4l/dev-capture.xml
+++ b/Documentation/DocBook/v4l/dev-capture.xml
@@ -18,7 +18,8 @@ files are used for video output devices.</para>
18 <title>Querying Capabilities</title> 18 <title>Querying Capabilities</title>
19 19
20 <para>Devices supporting the video capture interface set the 20 <para>Devices supporting the video capture interface set the
21<constant>V4L2_CAP_VIDEO_CAPTURE</constant> flag in the 21<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or
22<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the
22<structfield>capabilities</structfield> field of &v4l2-capability; 23<structfield>capabilities</structfield> field of &v4l2-capability;
23returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions 24returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
24they may also support the <link linkend="overlay">video overlay</link> 25they may also support the <link linkend="overlay">video overlay</link>
@@ -64,9 +65,11 @@ linkend="crop" />.</para>
64 65
65 <para>To query the current image format applications set the 66 <para>To query the current image format applications set the
66<structfield>type</structfield> field of a &v4l2-format; to 67<structfield>type</structfield> field of a &v4l2-format; to
67<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the 68<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
69<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the
68&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill 70&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
69the &v4l2-pix-format; <structfield>pix</structfield> member of the 71the &v4l2-pix-format; <structfield>pix</structfield> or the
72&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
70<structfield>fmt</structfield> union.</para> 73<structfield>fmt</structfield> union.</para>
71 74
72 <para>To request different parameters applications set the 75 <para>To request different parameters applications set the
@@ -84,8 +87,8 @@ adjust the parameters and finally return the actual parameters as
84without disabling I/O or possibly time consuming hardware 87without disabling I/O or possibly time consuming hardware
85preparations.</para> 88preparations.</para>
86 89
87 <para>The contents of &v4l2-pix-format; are discussed in <xref 90 <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
88linkend="pixfmt" />. See also the specification of the 91are discussed in <xref linkend="pixfmt" />. See also the specification of the
89<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> 92<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
90and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video 93and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
91capture devices must implement both the 94capture devices must implement both the
diff --git a/Documentation/DocBook/v4l/dev-output.xml b/Documentation/DocBook/v4l/dev-output.xml
index 63c3c20e5a72..919e22c53854 100644
--- a/Documentation/DocBook/v4l/dev-output.xml
+++ b/Documentation/DocBook/v4l/dev-output.xml
@@ -17,7 +17,8 @@ files are used for video capture devices.</para>
17 <title>Querying Capabilities</title> 17 <title>Querying Capabilities</title>
18 18
19 <para>Devices supporting the video output interface set the 19 <para>Devices supporting the video output interface set the
20<constant>V4L2_CAP_VIDEO_OUTPUT</constant> flag in the 20<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
21<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
21<structfield>capabilities</structfield> field of &v4l2-capability; 22<structfield>capabilities</structfield> field of &v4l2-capability;
22returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions 23returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
23they may also support the <link linkend="raw-vbi">raw VBI 24they may also support the <link linkend="raw-vbi">raw VBI
@@ -60,9 +61,11 @@ linkend="crop" />.</para>
60 61
61 <para>To query the current image format applications set the 62 <para>To query the current image format applications set the
62<structfield>type</structfield> field of a &v4l2-format; to 63<structfield>type</structfield> field of a &v4l2-format; to
63<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and call the 64<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
65<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
64&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill 66&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
65the &v4l2-pix-format; <structfield>pix</structfield> member of the 67the &v4l2-pix-format; <structfield>pix</structfield> or the
68&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
66<structfield>fmt</structfield> union.</para> 69<structfield>fmt</structfield> union.</para>
67 70
68 <para>To request different parameters applications set the 71 <para>To request different parameters applications set the
@@ -80,8 +83,8 @@ adjust the parameters and finally return the actual parameters as
80without disabling I/O or possibly time consuming hardware 83without disabling I/O or possibly time consuming hardware
81preparations.</para> 84preparations.</para>
82 85
83 <para>The contents of &v4l2-pix-format; are discussed in <xref 86 <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
84linkend="pixfmt" />. See also the specification of the 87are discussed in <xref linkend="pixfmt" />. See also the specification of the
85<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant> 88<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
86and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video 89and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
87output devices must implement both the 90output devices must implement both the
diff --git a/Documentation/DocBook/v4l/dev-subdev.xml b/Documentation/DocBook/v4l/dev-subdev.xml
new file mode 100644
index 000000000000..21caff6d159b
--- /dev/null
+++ b/Documentation/DocBook/v4l/dev-subdev.xml
@@ -0,0 +1,313 @@
1 <title>Sub-device Interface</title>
2
3 <note>
4 <title>Experimental</title>
5 <para>This is an <link linkend="experimental">experimental</link>
6 interface and may change in the future.</para>
7 </note>
8
9 <para>The complex nature of V4L2 devices, where hardware is often made of
10 several integrated circuits that need to interact with each other in a
11 controlled way, leads to complex V4L2 drivers. The drivers usually reflect
12 the hardware model in software, and model the different hardware components
13 as software blocks called sub-devices.</para>
14
15 <para>V4L2 sub-devices are usually kernel-only objects. If the V4L2 driver
16 implements the media device API, they will automatically inherit from media
17 entities. Applications will be able to enumerate the sub-devices and discover
18 the hardware topology using the media entities, pads and links enumeration
19 API.</para>
20
21 <para>In addition to make sub-devices discoverable, drivers can also choose
22 to make them directly configurable by applications. When both the sub-device
23 driver and the V4L2 device driver support this, sub-devices will feature a
24 character device node on which ioctls can be called to
25 <itemizedlist>
26 <listitem><para>query, read and write sub-devices controls</para></listitem>
27 <listitem><para>subscribe and unsubscribe to events and retrieve them</para></listitem>
28 <listitem><para>negotiate image formats on individual pads</para></listitem>
29 </itemizedlist>
30 </para>
31
32 <para>Sub-device character device nodes, conventionally named
33 <filename>/dev/v4l-subdev*</filename>, use major number 81.</para>
34
35 <section>
36 <title>Controls</title>
37 <para>Most V4L2 controls are implemented by sub-device hardware. Drivers
38 usually merge all controls and expose them through video device nodes.
39 Applications can control all sub-devices through a single interface.</para>
40
41 <para>Complex devices sometimes implement the same control in different
42 pieces of hardware. This situation is common in embedded platforms, where
43 both sensors and image processing hardware implement identical functions,
44 such as contrast adjustment, white balance or faulty pixels correction. As
45 the V4L2 controls API doesn't support several identical controls in a single
46 device, all but one of the identical controls are hidden.</para>
47
48 <para>Applications can access those hidden controls through the sub-device
49 node with the V4L2 control API described in <xref linkend="control" />. The
50 ioctls behave identically as when issued on V4L2 device nodes, with the
51 exception that they deal only with controls implemented in the sub-device.
52 </para>
53
54 <para>Depending on the driver, those controls might also be exposed through
55 one (or several) V4L2 device nodes.</para>
56 </section>
57
58 <section>
59 <title>Events</title>
60 <para>V4L2 sub-devices can notify applications of events as described in
61 <xref linkend="event" />. The API behaves identically as when used on V4L2
62 device nodes, with the exception that it only deals with events generated by
63 the sub-device. Depending on the driver, those events might also be reported
64 on one (or several) V4L2 device nodes.</para>
65 </section>
66
67 <section id="pad-level-formats">
68 <title>Pad-level Formats</title>
69
70 <warning><para>Pad-level formats are only applicable to very complex device that
71 need to expose low-level format configuration to user space. Generic V4L2
72 applications do <emphasis>not</emphasis> need to use the API described in
73 this section.</para></warning>
74
75 <note><para>For the purpose of this section, the term
76 <wordasword>format</wordasword> means the combination of media bus data
77 format, frame width and frame height.</para></note>
78
79 <para>Image formats are typically negotiated on video capture and output
80 devices using the <link linkend="crop">cropping and scaling</link> ioctls.
81 The driver is responsible for configuring every block in the video pipeline
82 according to the requested format at the pipeline input and/or
83 output.</para>
84
85 <para>For complex devices, such as often found in embedded systems,
86 identical image sizes at the output of a pipeline can be achieved using
87 different hardware configurations. One such example is shown on
88 <xref linkend="pipeline-scaling" />, where
89 image scaling can be performed on both the video sensor and the host image
90 processing hardware.</para>
91
92 <figure id="pipeline-scaling">
93 <title>Image Format Negotation on Pipelines</title>
94 <mediaobject>
95 <imageobject>
96 <imagedata fileref="pipeline.pdf" format="PS" />
97 </imageobject>
98 <imageobject>
99 <imagedata fileref="pipeline.png" format="PNG" />
100 </imageobject>
101 <textobject>
102 <phrase>High quality and high speed pipeline configuration</phrase>
103 </textobject>
104 </mediaobject>
105 </figure>
106
107 <para>The sensor scaler is usually of less quality than the host scaler, but
108 scaling on the sensor is required to achieve higher frame rates. Depending
109 on the use case (quality vs. speed), the pipeline must be configured
110 differently. Applications need to configure the formats at every point in
111 the pipeline explicitly.</para>
112
113 <para>Drivers that implement the <link linkend="media-controller-intro">media
114 API</link> can expose pad-level image format configuration to applications.
115 When they do, applications can use the &VIDIOC-SUBDEV-G-FMT; and
116 &VIDIOC-SUBDEV-S-FMT; ioctls. to negotiate formats on a per-pad basis.</para>
117
118 <para>Applications are responsible for configuring coherent parameters on
119 the whole pipeline and making sure that connected pads have compatible
120 formats. The pipeline is checked for formats mismatch at &VIDIOC-STREAMON;
121 time, and an &EPIPE; is then returned if the configuration is
122 invalid.</para>
123
124 <para>Pad-level image format configuration support can be tested by calling
125 the &VIDIOC-SUBDEV-G-FMT; ioctl on pad 0. If the driver returns an &EINVAL;
126 pad-level format configuration is not supported by the sub-device.</para>
127
128 <section>
129 <title>Format Negotiation</title>
130
131 <para>Acceptable formats on pads can (and usually do) depend on a number
132 of external parameters, such as formats on other pads, active links, or
133 even controls. Finding a combination of formats on all pads in a video
134 pipeline, acceptable to both application and driver, can't rely on formats
135 enumeration only. A format negotiation mechanism is required.</para>
136
137 <para>Central to the format negotiation mechanism are the get/set format
138 operations. When called with the <structfield>which</structfield> argument
139 set to <constant>V4L2_SUBDEV_FORMAT_TRY</constant>, the
140 &VIDIOC-SUBDEV-G-FMT; and &VIDIOC-SUBDEV-S-FMT; ioctls operate on a set of
141 formats parameters that are not connected to the hardware configuration.
142 Modifying those 'try' formats leaves the device state untouched (this
143 applies to both the software state stored in the driver and the hardware
144 state stored in the device itself).</para>
145
146 <para>While not kept as part of the device state, try formats are stored
147 in the sub-device file handles. A &VIDIOC-SUBDEV-G-FMT; call will return
148 the last try format set <emphasis>on the same sub-device file
149 handle</emphasis>. Several applications querying the same sub-device at
150 the same time will thus not interact with each other.</para>
151
152 <para>To find out whether a particular format is supported by the device,
153 applications use the &VIDIOC-SUBDEV-S-FMT; ioctl. Drivers verify and, if
154 needed, change the requested <structfield>format</structfield> based on
155 device requirements and return the possibly modified value. Applications
156 can then choose to try a different format or accept the returned value and
157 continue.</para>
158
159 <para>Formats returned by the driver during a negotiation iteration are
160 guaranteed to be supported by the device. In particular, drivers guarantee
161 that a returned format will not be further changed if passed to an
162 &VIDIOC-SUBDEV-S-FMT; call as-is (as long as external parameters, such as
163 formats on other pads or links' configuration are not changed).</para>
164
165 <para>Drivers automatically propagate formats inside sub-devices. When a
166 try or active format is set on a pad, corresponding formats on other pads
167 of the same sub-device can be modified by the driver. Drivers are free to
168 modify formats as required by the device. However, they should comply with
169 the following rules when possible:
170 <itemizedlist>
171 <listitem><para>Formats should be propagated from sink pads to source pads.
172 Modifying a format on a source pad should not modify the format on any
173 sink pad.</para></listitem>
174 <listitem><para>Sub-devices that scale frames using variable scaling factors
175 should reset the scale factors to default values when sink pads formats
176 are modified. If the 1:1 scaling ratio is supported, this means that
177 source pads formats should be reset to the sink pads formats.</para></listitem>
178 </itemizedlist>
179 </para>
180
181 <para>Formats are not propagated across links, as that would involve
182 propagating them from one sub-device file handle to another. Applications
183 must then take care to configure both ends of every link explicitly with
184 compatible formats. Identical formats on the two ends of a link are
185 guaranteed to be compatible. Drivers are free to accept different formats
186 matching device requirements as being compatible.</para>
187
188 <para><xref linkend="sample-pipeline-config" />
189 shows a sample configuration sequence for the pipeline described in
190 <xref linkend="pipeline-scaling" /> (table
191 columns list entity names and pad numbers).</para>
192
193 <table pgwide="0" frame="none" id="sample-pipeline-config">
194 <title>Sample Pipeline Configuration</title>
195 <tgroup cols="3">
196 <colspec colname="what"/>
197 <colspec colname="sensor-0" />
198 <colspec colname="frontend-0" />
199 <colspec colname="frontend-1" />
200 <colspec colname="scaler-0" />
201 <colspec colname="scaler-1" />
202 <thead>
203 <row>
204 <entry></entry>
205 <entry>Sensor/0</entry>
206 <entry>Frontend/0</entry>
207 <entry>Frontend/1</entry>
208 <entry>Scaler/0</entry>
209 <entry>Scaler/1</entry>
210 </row>
211 </thead>
212 <tbody valign="top">
213 <row>
214 <entry>Initial state</entry>
215 <entry>2048x1536</entry>
216 <entry>-</entry>
217 <entry>-</entry>
218 <entry>-</entry>
219 <entry>-</entry>
220 </row>
221 <row>
222 <entry>Configure frontend input</entry>
223 <entry>2048x1536</entry>
224 <entry><emphasis>2048x1536</emphasis></entry>
225 <entry><emphasis>2046x1534</emphasis></entry>
226 <entry>-</entry>
227 <entry>-</entry>
228 </row>
229 <row>
230 <entry>Configure scaler input</entry>
231 <entry>2048x1536</entry>
232 <entry>2048x1536</entry>
233 <entry>2046x1534</entry>
234 <entry><emphasis>2046x1534</emphasis></entry>
235 <entry><emphasis>2046x1534</emphasis></entry>
236 </row>
237 <row>
238 <entry>Configure scaler output</entry>
239 <entry>2048x1536</entry>
240 <entry>2048x1536</entry>
241 <entry>2046x1534</entry>
242 <entry>2046x1534</entry>
243 <entry><emphasis>1280x960</emphasis></entry>
244 </row>
245 </tbody>
246 </tgroup>
247 </table>
248
249 <para>
250 <orderedlist>
251 <listitem><para>Initial state. The sensor output is set to its native 3MP
252 resolution. Resolutions on the host frontend and scaler input and output
253 pads are undefined.</para></listitem>
254 <listitem><para>The application configures the frontend input pad resolution to
255 2048x1536. The driver propagates the format to the frontend output pad.
256 Note that the propagated output format can be different, as in this case,
257 than the input format, as the hardware might need to crop pixels (for
258 instance when converting a Bayer filter pattern to RGB or YUV).</para></listitem>
259 <listitem><para>The application configures the scaler input pad resolution to
260 2046x1534 to match the frontend output resolution. The driver propagates
261 the format to the scaler output pad.</para></listitem>
262 <listitem><para>The application configures the scaler output pad resolution to
263 1280x960.</para></listitem>
264 </orderedlist>
265 </para>
266
267 <para>When satisfied with the try results, applications can set the active
268 formats by setting the <structfield>which</structfield> argument to
269 <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. Active formats are changed
270 exactly as try formats by drivers. To avoid modifying the hardware state
271 during format negotiation, applications should negotiate try formats first
272 and then modify the active settings using the try formats returned during
273 the last negotiation iteration. This guarantees that the active format
274 will be applied as-is by the driver without being modified.
275 </para>
276 </section>
277
278 <section>
279 <title>Cropping and scaling</title>
280
281 <para>Many sub-devices support cropping frames on their input or output
282 pads (or possible even on both). Cropping is used to select the area of
283 interest in an image, typically on a video sensor or video decoder. It can
284 also be used as part of digital zoom implementations to select the area of
285 the image that will be scaled up.</para>
286
287 <para>Crop settings are defined by a crop rectangle and represented in a
288 &v4l2-rect; by the coordinates of the top left corner and the rectangle
289 size. Both the coordinates and sizes are expressed in pixels.</para>
290
291 <para>The crop rectangle is retrieved and set using the
292 &VIDIOC-SUBDEV-G-CROP; and &VIDIOC-SUBDEV-S-CROP; ioctls. Like for pad
293 formats, drivers store try and active crop rectangles. The format
294 negotiation mechanism applies to crop settings as well.</para>
295
296 <para>On input pads, cropping is applied relatively to the current pad
297 format. The pad format represents the image size as received by the
298 sub-device from the previous block in the pipeline, and the crop rectangle
299 represents the sub-image that will be transmitted further inside the
300 sub-device for processing. The crop rectangle be entirely containted
301 inside the input image size.</para>
302
303 <para>Input crop rectangle are reset to their default value when the input
304 image format is modified. Drivers should use the input image size as the
305 crop rectangle default value, but hardware requirements may prevent this.
306 </para>
307
308 <para>Cropping behaviour on output pads is not defined.</para>
309
310 </section>
311 </section>
312
313 &sub-subdev-formats;
diff --git a/Documentation/DocBook/v4l/func-mmap.xml b/Documentation/DocBook/v4l/func-mmap.xml
index 2e2fc3933aea..786732b64bbd 100644
--- a/Documentation/DocBook/v4l/func-mmap.xml
+++ b/Documentation/DocBook/v4l/func-mmap.xml
@@ -45,7 +45,10 @@ just specify a <constant>NULL</constant> pointer here.</para>
45 <listitem> 45 <listitem>
46 <para>Length of the memory area to map. This must be the 46 <para>Length of the memory area to map. This must be the
47same value as returned by the driver in the &v4l2-buffer; 47same value as returned by the driver in the &v4l2-buffer;
48<structfield>length</structfield> field.</para> 48<structfield>length</structfield> field for the
49single-planar API, and the same value as returned by the driver
50in the &v4l2-plane; <structfield>length</structfield> field for the
51multi-planar API.</para>
49 </listitem> 52 </listitem>
50 </varlistentry> 53 </varlistentry>
51 <varlistentry> 54 <varlistentry>
@@ -106,7 +109,10 @@ flag.</para>
106 <listitem> 109 <listitem>
107 <para>Offset of the buffer in device memory. This must be the 110 <para>Offset of the buffer in device memory. This must be the
108same value as returned by the driver in the &v4l2-buffer; 111same value as returned by the driver in the &v4l2-buffer;
109<structfield>m</structfield> union <structfield>offset</structfield> field.</para> 112<structfield>m</structfield> union <structfield>offset</structfield> field for
113the single-planar API, and the same value as returned by the driver
114in the &v4l2-plane; <structfield>m</structfield> union
115<structfield>mem_offset</structfield> field for the multi-planar API.</para>
110 </listitem> 116 </listitem>
111 </varlistentry> 117 </varlistentry>
112 </variablelist> 118 </variablelist>
diff --git a/Documentation/DocBook/v4l/func-munmap.xml b/Documentation/DocBook/v4l/func-munmap.xml
index 502ed49323b0..e2c4190f9bb6 100644
--- a/Documentation/DocBook/v4l/func-munmap.xml
+++ b/Documentation/DocBook/v4l/func-munmap.xml
@@ -37,7 +37,8 @@
37 <para>Length of the mapped buffer. This must be the same 37 <para>Length of the mapped buffer. This must be the same
38value as given to <function>mmap()</function> and returned by the 38value as given to <function>mmap()</function> and returned by the
39driver in the &v4l2-buffer; <structfield>length</structfield> 39driver in the &v4l2-buffer; <structfield>length</structfield>
40field.</para> 40field for the single-planar API and in the &v4l2-plane;
41<structfield>length</structfield> field for the multi-planar API.</para>
41 </listitem> 42 </listitem>
42 </varlistentry> 43 </varlistentry>
43 </variablelist> 44 </variablelist>
diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml
index d424886beda0..227e7ac45a06 100644
--- a/Documentation/DocBook/v4l/io.xml
+++ b/Documentation/DocBook/v4l/io.xml
@@ -121,18 +121,22 @@ mapped.</para>
121 <para>Before applications can access the buffers they must map 121 <para>Before applications can access the buffers they must map
122them into their address space with the &func-mmap; function. The 122them into their address space with the &func-mmap; function. The
123location of the buffers in device memory can be determined with the 123location of the buffers in device memory can be determined with the
124&VIDIOC-QUERYBUF; ioctl. The <structfield>m.offset</structfield> and 124&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
125<structfield>length</structfield> returned in a &v4l2-buffer; are 125<structfield>m.offset</structfield> and <structfield>length</structfield>
126passed as sixth and second parameter to the 126returned in a &v4l2-buffer; are passed as sixth and second parameter to the
127<function>mmap()</function> function. The offset and length values 127<function>mmap()</function> function. When using the multi-planar API,
128must not be modified. Remember the buffers are allocated in physical 128struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
129memory, as opposed to virtual memory which can be swapped out to disk. 129containing its own <structfield>m.offset</structfield> and
130Applications should free the buffers as soon as possible with the 130<structfield>length</structfield>. When using the multi-planar API, every
131&func-munmap; function.</para> 131plane of every buffer has to be mapped separately, so the number of
132calls to &func-mmap; should be equal to number of buffers times number of
133planes in each buffer. The offset and length values must not be modified.
134Remember, the buffers are allocated in physical memory, as opposed to virtual
135memory, which can be swapped out to disk. Applications should free the buffers
136as soon as possible with the &func-munmap; function.</para>
132 137
133 <example> 138 <example>
134 <title>Mapping buffers</title> 139 <title>Mapping buffers in the single-planar API</title>
135
136 <programlisting> 140 <programlisting>
137&v4l2-requestbuffers; reqbuf; 141&v4l2-requestbuffers; reqbuf;
138struct { 142struct {
@@ -141,63 +145,145 @@ struct {
141} *buffers; 145} *buffers;
142unsigned int i; 146unsigned int i;
143 147
144memset (&amp;reqbuf, 0, sizeof (reqbuf)); 148memset(&amp;reqbuf, 0, sizeof(reqbuf));
145reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; 149reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
146reqbuf.memory = V4L2_MEMORY_MMAP; 150reqbuf.memory = V4L2_MEMORY_MMAP;
147reqbuf.count = 20; 151reqbuf.count = 20;
148 152
149if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) { 153if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) {
150 if (errno == EINVAL) 154 if (errno == EINVAL)
151 printf ("Video capturing or mmap-streaming is not supported\n"); 155 printf("Video capturing or mmap-streaming is not supported\n");
152 else 156 else
153 perror ("VIDIOC_REQBUFS"); 157 perror("VIDIOC_REQBUFS");
154 158
155 exit (EXIT_FAILURE); 159 exit(EXIT_FAILURE);
156} 160}
157 161
158/* We want at least five buffers. */ 162/* We want at least five buffers. */
159 163
160if (reqbuf.count &lt; 5) { 164if (reqbuf.count &lt; 5) {
161 /* You may need to free the buffers here. */ 165 /* You may need to free the buffers here. */
162 printf ("Not enough buffer memory\n"); 166 printf("Not enough buffer memory\n");
163 exit (EXIT_FAILURE); 167 exit(EXIT_FAILURE);
164} 168}
165 169
166buffers = calloc (reqbuf.count, sizeof (*buffers)); 170buffers = calloc(reqbuf.count, sizeof(*buffers));
167assert (buffers != NULL); 171assert(buffers != NULL);
168 172
169for (i = 0; i &lt; reqbuf.count; i++) { 173for (i = 0; i &lt; reqbuf.count; i++) {
170 &v4l2-buffer; buffer; 174 &v4l2-buffer; buffer;
171 175
172 memset (&amp;buffer, 0, sizeof (buffer)); 176 memset(&amp;buffer, 0, sizeof(buffer));
173 buffer.type = reqbuf.type; 177 buffer.type = reqbuf.type;
174 buffer.memory = V4L2_MEMORY_MMAP; 178 buffer.memory = V4L2_MEMORY_MMAP;
175 buffer.index = i; 179 buffer.index = i;
176 180
177 if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) { 181 if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) {
178 perror ("VIDIOC_QUERYBUF"); 182 perror("VIDIOC_QUERYBUF");
179 exit (EXIT_FAILURE); 183 exit(EXIT_FAILURE);
180 } 184 }
181 185
182 buffers[i].length = buffer.length; /* remember for munmap() */ 186 buffers[i].length = buffer.length; /* remember for munmap() */
183 187
184 buffers[i].start = mmap (NULL, buffer.length, 188 buffers[i].start = mmap(NULL, buffer.length,
185 PROT_READ | PROT_WRITE, /* recommended */ 189 PROT_READ | PROT_WRITE, /* recommended */
186 MAP_SHARED, /* recommended */ 190 MAP_SHARED, /* recommended */
187 fd, buffer.m.offset); 191 fd, buffer.m.offset);
188 192
189 if (MAP_FAILED == buffers[i].start) { 193 if (MAP_FAILED == buffers[i].start) {
190 /* If you do not exit here you should unmap() and free() 194 /* If you do not exit here you should unmap() and free()
191 the buffers mapped so far. */ 195 the buffers mapped so far. */
192 perror ("mmap"); 196 perror("mmap");
193 exit (EXIT_FAILURE); 197 exit(EXIT_FAILURE);
198 }
199}
200
201/* Cleanup. */
202
203for (i = 0; i &lt; reqbuf.count; i++)
204 munmap(buffers[i].start, buffers[i].length);
205 </programlisting>
206 </example>
207
208 <example>
209 <title>Mapping buffers in the multi-planar API</title>
210 <programlisting>
211&v4l2-requestbuffers; reqbuf;
212/* Our current format uses 3 planes per buffer */
213#define FMT_NUM_PLANES = 3;
214
215struct {
216 void *start[FMT_NUM_PLANES];
217 size_t length[FMT_NUM_PLANES];
218} *buffers;
219unsigned int i, j;
220
221memset(&amp;reqbuf, 0, sizeof(reqbuf));
222reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE;
223reqbuf.memory = V4L2_MEMORY_MMAP;
224reqbuf.count = 20;
225
226if (ioctl(fd, &VIDIOC-REQBUFS;, &amp;reqbuf) &lt; 0) {
227 if (errno == EINVAL)
228 printf("Video capturing or mmap-streaming is not supported\n");
229 else
230 perror("VIDIOC_REQBUFS");
231
232 exit(EXIT_FAILURE);
233}
234
235/* We want at least five buffers. */
236
237if (reqbuf.count &lt; 5) {
238 /* You may need to free the buffers here. */
239 printf("Not enough buffer memory\n");
240 exit(EXIT_FAILURE);
241}
242
243buffers = calloc(reqbuf.count, sizeof(*buffers));
244assert(buffers != NULL);
245
246for (i = 0; i &lt; reqbuf.count; i++) {
247 &v4l2-buffer; buffer;
248 &v4l2-plane; planes[FMT_NUM_PLANES];
249
250 memset(&amp;buffer, 0, sizeof(buffer));
251 buffer.type = reqbuf.type;
252 buffer.memory = V4L2_MEMORY_MMAP;
253 buffer.index = i;
254 /* length in struct v4l2_buffer in multi-planar API stores the size
255 * of planes array. */
256 buffer.length = FMT_NUM_PLANES;
257 buffer.m.planes = planes;
258
259 if (ioctl(fd, &VIDIOC-QUERYBUF;, &amp;buffer) &lt; 0) {
260 perror("VIDIOC_QUERYBUF");
261 exit(EXIT_FAILURE);
262 }
263
264 /* Every plane has to be mapped separately */
265 for (j = 0; j &lt; FMT_NUM_PLANES; j++) {
266 buffers[i].length[j] = buffer.m.planes[j].length; /* remember for munmap() */
267
268 buffers[i].start[j] = mmap(NULL, buffer.m.planes[j].length,
269 PROT_READ | PROT_WRITE, /* recommended */
270 MAP_SHARED, /* recommended */
271 fd, buffer.m.planes[j].m.offset);
272
273 if (MAP_FAILED == buffers[i].start[j]) {
274 /* If you do not exit here you should unmap() and free()
275 the buffers and planes mapped so far. */
276 perror("mmap");
277 exit(EXIT_FAILURE);
278 }
194 } 279 }
195} 280}
196 281
197/* Cleanup. */ 282/* Cleanup. */
198 283
199for (i = 0; i &lt; reqbuf.count; i++) 284for (i = 0; i &lt; reqbuf.count; i++)
200 munmap (buffers[i].start, buffers[i].length); 285 for (j = 0; j &lt; FMT_NUM_PLANES; j++)
286 munmap(buffers[i].start[j], buffers[i].length[j]);
201 </programlisting> 287 </programlisting>
202 </example> 288 </example>
203 289
@@ -286,13 +372,13 @@ pointer method (not only memory mapping) is supported must be
286determined by calling the &VIDIOC-REQBUFS; ioctl.</para> 372determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
287 373
288 <para>This I/O method combines advantages of the read/write and 374 <para>This I/O method combines advantages of the read/write and
289memory mapping methods. Buffers are allocated by the application 375memory mapping methods. Buffers (planes) are allocated by the application
290itself, and can reside for example in virtual or shared memory. Only 376itself, and can reside for example in virtual or shared memory. Only
291pointers to data are exchanged, these pointers and meta-information 377pointers to data are exchanged, these pointers and meta-information
292are passed in &v4l2-buffer;. The driver must be switched 378are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
293into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the 379The driver must be switched into user pointer I/O mode by calling the
294desired buffer type. No buffers are allocated beforehands, 380&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
295consequently they are not indexed and cannot be queried like mapped 381beforehand, consequently they are not indexed and cannot be queried like mapped
296buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para> 382buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
297 383
298 <example> 384 <example>
@@ -316,7 +402,7 @@ if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
316 </programlisting> 402 </programlisting>
317 </example> 403 </example>
318 404
319 <para>Buffer addresses and sizes are passed on the fly with the 405 <para>Buffer (plane) addresses and sizes are passed on the fly with the
320&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled, 406&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
321applications can pass different addresses and sizes at each 407applications can pass different addresses and sizes at each
322<constant>VIDIOC_QBUF</constant> call. If required by the hardware the 408<constant>VIDIOC_QBUF</constant> call. If required by the hardware the
@@ -396,11 +482,18 @@ rest should be evident.</para>
396 <title>Buffers</title> 482 <title>Buffers</title>
397 483
398 <para>A buffer contains data exchanged by application and 484 <para>A buffer contains data exchanged by application and
399driver using one of the Streaming I/O methods. Only pointers to 485driver using one of the Streaming I/O methods. In the multi-planar API, the
400buffers are exchanged, the data itself is not copied. These pointers, 486data is held in planes, while the buffer structure acts as a container
401together with meta-information like timestamps or field parity, are 487for the planes. Only pointers to buffers (planes) are exchanged, the data
402stored in a struct <structname>v4l2_buffer</structname>, argument to 488itself is not copied. These pointers, together with meta-information like
403the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para> 489timestamps or field parity, are stored in a struct
490<structname>v4l2_buffer</structname>, argument to
491the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.
492In the multi-planar API, some plane-specific members of struct
493<structname>v4l2_buffer</structname>, such as pointers and sizes for each
494plane, are stored in struct <structname>v4l2_plane</structname> instead.
495In that case, struct <structname>v4l2_buffer</structname> contains an array of
496plane structures.</para>
404 497
405 <para>Nominally timestamps refer to the first data byte transmitted. 498 <para>Nominally timestamps refer to the first data byte transmitted.
406In practice however the wide range of hardware covered by the V4L2 API 499In practice however the wide range of hardware covered by the V4L2 API
@@ -551,26 +644,40 @@ in accordance with the selected I/O method.</entry>
551 <entry></entry> 644 <entry></entry>
552 <entry>__u32</entry> 645 <entry>__u32</entry>
553 <entry><structfield>offset</structfield></entry> 646 <entry><structfield>offset</structfield></entry>
554 <entry>When <structfield>memory</structfield> is 647 <entry>For the single-planar API and when
555<constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer 648<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
556from the start of the device memory. The value is returned by the 649is the offset of the buffer from the start of the device memory. The value is
557driver and apart of serving as parameter to the &func-mmap; function 650returned by the driver and apart of serving as parameter to the &func-mmap;
558not useful for applications. See <xref linkend="mmap" /> for details.</entry> 651function not useful for applications. See <xref linkend="mmap" /> for details
652 </entry>
559 </row> 653 </row>
560 <row> 654 <row>
561 <entry></entry> 655 <entry></entry>
562 <entry>unsigned long</entry> 656 <entry>unsigned long</entry>
563 <entry><structfield>userptr</structfield></entry> 657 <entry><structfield>userptr</structfield></entry>
564 <entry>When <structfield>memory</structfield> is 658 <entry>For the single-planar API and when
565<constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the 659<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
566buffer (casted to unsigned long type) in virtual memory, set by the 660this is a pointer to the buffer (casted to unsigned long type) in virtual
567application. See <xref linkend="userp" /> for details.</entry> 661memory, set by the application. See <xref linkend="userp" /> for details.
662 </entry>
663 </row>
664 <row>
665 <entry></entry>
666 <entry>struct v4l2_plane</entry>
667 <entry><structfield>*planes</structfield></entry>
668 <entry>When using the multi-planar API, contains a userspace pointer
669 to an array of &v4l2-plane;. The size of the array should be put
670 in the <structfield>length</structfield> field of this
671 <structname>v4l2_buffer</structname> structure.</entry>
568 </row> 672 </row>
569 <row> 673 <row>
570 <entry>__u32</entry> 674 <entry>__u32</entry>
571 <entry><structfield>length</structfield></entry> 675 <entry><structfield>length</structfield></entry>
572 <entry></entry> 676 <entry></entry>
573 <entry>Size of the buffer (not the payload) in bytes.</entry> 677 <entry>Size of the buffer (not the payload) in bytes for the
678 single-planar API. For the multi-planar API should contain the
679 number of elements in the <structfield>planes</structfield> array.
680 </entry>
574 </row> 681 </row>
575 <row> 682 <row>
576 <entry>__u32</entry> 683 <entry>__u32</entry>
@@ -596,6 +703,66 @@ should set this to 0.</entry>
596 </tgroup> 703 </tgroup>
597 </table> 704 </table>
598 705
706 <table frame="none" pgwide="1" id="v4l2-plane">
707 <title>struct <structname>v4l2_plane</structname></title>
708 <tgroup cols="4">
709 &cs-ustr;
710 <tbody valign="top">
711 <row>
712 <entry>__u32</entry>
713 <entry><structfield>bytesused</structfield></entry>
714 <entry></entry>
715 <entry>The number of bytes occupied by data in the plane
716 (its payload).</entry>
717 </row>
718 <row>
719 <entry>__u32</entry>
720 <entry><structfield>length</structfield></entry>
721 <entry></entry>
722 <entry>Size in bytes of the plane (not its payload).</entry>
723 </row>
724 <row>
725 <entry>union</entry>
726 <entry><structfield>m</structfield></entry>
727 <entry></entry>
728 <entry></entry>
729 </row>
730 <row>
731 <entry></entry>
732 <entry>__u32</entry>
733 <entry><structfield>mem_offset</structfield></entry>
734 <entry>When the memory type in the containing &v4l2-buffer; is
735 <constant>V4L2_MEMORY_MMAP</constant>, this is the value that
736 should be passed to &func-mmap;, similar to the
737 <structfield>offset</structfield> field in &v4l2-buffer;.</entry>
738 </row>
739 <row>
740 <entry></entry>
741 <entry>__unsigned long</entry>
742 <entry><structfield>userptr</structfield></entry>
743 <entry>When the memory type in the containing &v4l2-buffer; is
744 <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace
745 pointer to the memory allocated for this plane by an application.
746 </entry>
747 </row>
748 <row>
749 <entry>__u32</entry>
750 <entry><structfield>data_offset</structfield></entry>
751 <entry></entry>
752 <entry>Offset in bytes to video data in the plane, if applicable.
753 </entry>
754 </row>
755 <row>
756 <entry>__u32</entry>
757 <entry><structfield>reserved[11]</structfield></entry>
758 <entry></entry>
759 <entry>Reserved for future use. Should be zeroed by an
760 application.</entry>
761 </row>
762 </tbody>
763 </tgroup>
764 </table>
765
599 <table frame="none" pgwide="1" id="v4l2-buf-type"> 766 <table frame="none" pgwide="1" id="v4l2-buf-type">
600 <title>enum v4l2_buf_type</title> 767 <title>enum v4l2_buf_type</title>
601 <tgroup cols="3"> 768 <tgroup cols="3">
@@ -604,13 +771,27 @@ should set this to 0.</entry>
604 <row> 771 <row>
605 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry> 772 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
606 <entry>1</entry> 773 <entry>1</entry>
607 <entry>Buffer of a video capture stream, see <xref 774 <entry>Buffer of a single-planar video capture stream, see <xref
775 linkend="capture" />.</entry>
776 </row>
777 <row>
778 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>
779 </entry>
780 <entry>9</entry>
781 <entry>Buffer of a multi-planar video capture stream, see <xref
608 linkend="capture" />.</entry> 782 linkend="capture" />.</entry>
609 </row> 783 </row>
610 <row> 784 <row>
611 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry> 785 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
612 <entry>2</entry> 786 <entry>2</entry>
613 <entry>Buffer of a video output stream, see <xref 787 <entry>Buffer of a single-planar video output stream, see <xref
788 linkend="output" />.</entry>
789 </row>
790 <row>
791 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>
792 </entry>
793 <entry>10</entry>
794 <entry>Buffer of a multi-planar video output stream, see <xref
614 linkend="output" />.</entry> 795 linkend="output" />.</entry>
615 </row> 796 </row>
616 <row> 797 <row>
diff --git a/Documentation/DocBook/v4l/lirc_device_interface.xml b/Documentation/DocBook/v4l/lirc_device_interface.xml
index 68134c0ab4d1..0e0453f39e73 100644
--- a/Documentation/DocBook/v4l/lirc_device_interface.xml
+++ b/Documentation/DocBook/v4l/lirc_device_interface.xml
@@ -45,7 +45,7 @@ describing an IR signal are read from the chardev.</para>
45<para>The data written to the chardev is a pulse/space sequence of integer 45<para>The data written to the chardev is a pulse/space sequence of integer
46values. Pulses and spaces are only marked implicitly by their position. The 46values. Pulses and spaces are only marked implicitly by their position. The
47data must start and end with a pulse, therefore, the data must always include 47data must start and end with a pulse, therefore, the data must always include
48an unevent number of samples. The write function must block until the data has 48an uneven number of samples. The write function must block until the data has
49been transmitted by the hardware.</para> 49been transmitted by the hardware.</para>
50</section> 50</section>
51 51
diff --git a/Documentation/DocBook/v4l/media-controller.xml b/Documentation/DocBook/v4l/media-controller.xml
new file mode 100644
index 000000000000..2dc25e1d4089
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-controller.xml
@@ -0,0 +1,89 @@
1<partinfo>
2 <authorgroup>
3 <author>
4 <firstname>Laurent</firstname>
5 <surname>Pinchart</surname>
6 <affiliation><address><email>laurent.pinchart@ideasonboard.com</email></address></affiliation>
7 <contrib>Initial version.</contrib>
8 </author>
9 </authorgroup>
10 <copyright>
11 <year>2010</year>
12 <holder>Laurent Pinchart</holder>
13 </copyright>
14
15 <revhistory>
16 <!-- Put document revisions here, newest first. -->
17 <revision>
18 <revnumber>1.0.0</revnumber>
19 <date>2010-11-10</date>
20 <authorinitials>lp</authorinitials>
21 <revremark>Initial revision</revremark>
22 </revision>
23 </revhistory>
24</partinfo>
25
26<title>Media Controller API</title>
27
28<chapter id="media_controller">
29 <title>Media Controller</title>
30
31 <section id="media-controller-intro">
32 <title>Introduction</title>
33 <para>Media devices increasingly handle multiple related functions. Many USB
34 cameras include microphones, video capture hardware can also output video,
35 or SoC camera interfaces also perform memory-to-memory operations similar to
36 video codecs.</para>
37 <para>Independent functions, even when implemented in the same hardware, can
38 be modelled as separate devices. A USB camera with a microphone will be
39 presented to userspace applications as V4L2 and ALSA capture devices. The
40 devices' relationships (when using a webcam, end-users shouldn't have to
41 manually select the associated USB microphone), while not made available
42 directly to applications by the drivers, can usually be retrieved from
43 sysfs.</para>
44 <para>With more and more advanced SoC devices being introduced, the current
45 approach will not scale. Device topologies are getting increasingly complex
46 and can't always be represented by a tree structure. Hardware blocks are
47 shared between different functions, creating dependencies between seemingly
48 unrelated devices.</para>
49 <para>Kernel abstraction APIs such as V4L2 and ALSA provide means for
50 applications to access hardware parameters. As newer hardware expose an
51 increasingly high number of those parameters, drivers need to guess what
52 applications really require based on limited information, thereby
53 implementing policies that belong to userspace.</para>
54 <para>The media controller API aims at solving those problems.</para>
55 </section>
56
57 <section id="media-controller-model">
58 <title>Media device model</title>
59 <para>Discovering a device internal topology, and configuring it at runtime,
60 is one of the goals of the media controller API. To achieve this, hardware
61 devices are modelled as an oriented graph of building blocks called entities
62 connected through pads.</para>
63 <para>An entity is a basic media hardware or software building block. It can
64 correspond to a large variety of logical blocks such as physical hardware
65 devices (CMOS sensor for instance), logical hardware devices (a building
66 block in a System-on-Chip image processing pipeline), DMA channels or
67 physical connectors.</para>
68 <para>A pad is a connection endpoint through which an entity can interact
69 with other entities. Data (not restricted to video) produced by an entity
70 flows from the entity's output to one or more entity inputs. Pads should not
71 be confused with physical pins at chip boundaries.</para>
72 <para>A link is a point-to-point oriented connection between two pads,
73 either on the same entity or on different entities. Data flows from a source
74 pad to a sink pad.</para>
75 </section>
76</chapter>
77
78<appendix id="media-user-func">
79 <title>Function Reference</title>
80 <!-- Keep this alphabetically sorted. -->
81 &sub-media-open;
82 &sub-media-close;
83 &sub-media-ioctl;
84 <!-- All ioctls go here. -->
85 &sub-media-ioc-device-info;
86 &sub-media-ioc-enum-entities;
87 &sub-media-ioc-enum-links;
88 &sub-media-ioc-setup-link;
89</appendix>
diff --git a/Documentation/DocBook/v4l/media-func-close.xml b/Documentation/DocBook/v4l/media-func-close.xml
new file mode 100644
index 000000000000..be149c802aeb
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-func-close.xml
@@ -0,0 +1,59 @@
1<refentry id="media-func-close">
2 <refmeta>
3 <refentrytitle>media close()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>media-close</refname>
9 <refpurpose>Close a media device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>close</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 </funcprototype>
19 </funcsynopsis>
20 </refsynopsisdiv>
21
22 <refsect1>
23 <title>Arguments</title>
24
25 <variablelist>
26 <varlistentry>
27 <term><parameter>fd</parameter></term>
28 <listitem>
29 <para>&fd;</para>
30 </listitem>
31 </varlistentry>
32 </variablelist>
33 </refsect1>
34
35 <refsect1>
36 <title>Description</title>
37
38 <para>Closes the media device. Resources associated with the file descriptor
39 are freed. The device configuration remain unchanged.</para>
40 </refsect1>
41
42 <refsect1>
43 <title>Return Value</title>
44
45 <para><function>close</function> returns 0 on success. On error, -1 is
46 returned, and <varname>errno</varname> is set appropriately. Possible error
47 codes are:</para>
48
49 <variablelist>
50 <varlistentry>
51 <term><errorcode>EBADF</errorcode></term>
52 <listitem>
53 <para><parameter>fd</parameter> is not a valid open file descriptor.
54 </para>
55 </listitem>
56 </varlistentry>
57 </variablelist>
58 </refsect1>
59</refentry>
diff --git a/Documentation/DocBook/v4l/media-func-ioctl.xml b/Documentation/DocBook/v4l/media-func-ioctl.xml
new file mode 100644
index 000000000000..bda8604de15c
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-func-ioctl.xml
@@ -0,0 +1,116 @@
1<refentry id="media-func-ioctl">
2 <refmeta>
3 <refentrytitle>media ioctl()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>media-ioctl</refname>
9 <refpurpose>Control a media device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>void *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>Media ioctl request code as defined in the media.h header file,
38 for example MEDIA_IOC_SETUP_LINK.</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para>Pointer to a request-specific structure.</para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52 <para>The <function>ioctl()</function> function manipulates media device
53 parameters. The argument <parameter>fd</parameter> must be an open file
54 descriptor.</para>
55 <para>The ioctl <parameter>request</parameter> code specifies the media
56 function to be called. It has encoded in it whether the argument is an
57 input, output or read/write parameter, and the size of the argument
58 <parameter>argp</parameter> in bytes.</para>
59 <para>Macros and structures definitions specifying media ioctl requests and
60 their parameters are located in the media.h header file. All media ioctl
61 requests, their respective function and parameters are specified in
62 <xref linkend="media-user-func" />.</para>
63 </refsect1>
64
65 <refsect1>
66 <title>Return Value</title>
67
68 <para><function>ioctl()</function> returns <returnvalue>0</returnvalue> on
69 success. On failure, <returnvalue>-1</returnvalue> is returned, and the
70 <varname>errno</varname> variable is set appropriately. Generic error codes
71 are listed below, and request-specific error codes are listed in the
72 individual requests descriptions.</para>
73 <para>When an ioctl that takes an output or read/write parameter fails,
74 the parameter remains unmodified.</para>
75
76 <variablelist>
77 <varlistentry>
78 <term><errorcode>EBADF</errorcode></term>
79 <listitem>
80 <para><parameter>fd</parameter> is not a valid open file descriptor.
81 </para>
82 </listitem>
83 </varlistentry>
84 <varlistentry>
85 <term><errorcode>EFAULT</errorcode></term>
86 <listitem>
87 <para><parameter>argp</parameter> references an inaccessible memory
88 area.</para>
89 </listitem>
90 </varlistentry>
91 <varlistentry>
92 <term><errorcode>EINVAL</errorcode></term>
93 <listitem>
94 <para>The <parameter>request</parameter> or the data pointed to by
95 <parameter>argp</parameter> is not valid. This is a very common error
96 code, see the individual ioctl requests listed in
97 <xref linkend="media-user-func" /> for actual causes.</para>
98 </listitem>
99 </varlistentry>
100 <varlistentry>
101 <term><errorcode>ENOMEM</errorcode></term>
102 <listitem>
103 <para>Insufficient kernel memory was available to complete the
104 request.</para>
105 </listitem>
106 </varlistentry>
107 <varlistentry>
108 <term><errorcode>ENOTTY</errorcode></term>
109 <listitem>
110 <para><parameter>fd</parameter> is not associated with a character
111 special device.</para>
112 </listitem>
113 </varlistentry>
114 </variablelist>
115 </refsect1>
116</refentry>
diff --git a/Documentation/DocBook/v4l/media-func-open.xml b/Documentation/DocBook/v4l/media-func-open.xml
new file mode 100644
index 000000000000..f7df034dc9ed
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-func-open.xml
@@ -0,0 +1,94 @@
1<refentry id="media-func-open">
2 <refmeta>
3 <refentrytitle>media open()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>media-open</refname>
9 <refpurpose>Open a media device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>open</function></funcdef>
17 <paramdef>const char *<parameter>device_name</parameter></paramdef>
18 <paramdef>int <parameter>flags</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>device_name</parameter></term>
29 <listitem>
30 <para>Device to be opened.</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>flags</parameter></term>
35 <listitem>
36 <para>Open flags. Access mode must be either <constant>O_RDONLY</constant>
37 or <constant>O_RDWR</constant>. Other flags have no effect.</para>
38 </listitem>
39 </varlistentry>
40 </variablelist>
41 </refsect1>
42 <refsect1>
43 <title>Description</title>
44 <para>To open a media device applications call <function>open()</function>
45 with the desired device name. The function has no side effects; the device
46 configuration remain unchanged.</para>
47 <para>When the device is opened in read-only mode, attemps to modify its
48 configuration will result in an error, and <varname>errno</varname> will be
49 set to <errorcode>EBADF</errorcode>.</para>
50 </refsect1>
51 <refsect1>
52 <title>Return Value</title>
53
54 <para><function>open</function> returns the new file descriptor on success.
55 On error, -1 is returned, and <varname>errno</varname> is set appropriately.
56 Possible error codes are:</para>
57
58 <variablelist>
59 <varlistentry>
60 <term><errorcode>EACCES</errorcode></term>
61 <listitem>
62 <para>The requested access to the file is not allowed.</para>
63 </listitem>
64 </varlistentry>
65 <varlistentry>
66 <term><errorcode>EMFILE</errorcode></term>
67 <listitem>
68 <para>The process already has the maximum number of files open.
69 </para>
70 </listitem>
71 </varlistentry>
72 <varlistentry>
73 <term><errorcode>ENFILE</errorcode></term>
74 <listitem>
75 <para>The system limit on the total number of open files has been
76 reached.</para>
77 </listitem>
78 </varlistentry>
79 <varlistentry>
80 <term><errorcode>ENOMEM</errorcode></term>
81 <listitem>
82 <para>Insufficient kernel memory was available.</para>
83 </listitem>
84 </varlistentry>
85 <varlistentry>
86 <term><errorcode>ENXIO</errorcode></term>
87 <listitem>
88 <para>No device corresponding to this device special file exists.
89 </para>
90 </listitem>
91 </varlistentry>
92 </variablelist>
93 </refsect1>
94</refentry>
diff --git a/Documentation/DocBook/v4l/media-ioc-device-info.xml b/Documentation/DocBook/v4l/media-ioc-device-info.xml
new file mode 100644
index 000000000000..1f3237351bba
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-ioc-device-info.xml
@@ -0,0 +1,133 @@
1<refentry id="media-ioc-device-info">
2 <refmeta>
3 <refentrytitle>ioctl MEDIA_IOC_DEVICE_INFO</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>MEDIA_IOC_DEVICE_INFO</refname>
9 <refpurpose>Query device information</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct media_device_info *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>File descriptor returned by
31 <link linkend='media-func-open'><function>open()</function></link>.</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>MEDIA_IOC_DEVICE_INFO</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <para>All media devices must support the <constant>MEDIA_IOC_DEVICE_INFO</constant>
53 ioctl. To query device information, applications call the ioctl with a
54 pointer to a &media-device-info;. The driver fills the structure and returns
55 the information to the application.
56 The ioctl never fails.</para>
57
58 <table pgwide="1" frame="none" id="media-device-info">
59 <title>struct <structname>media_device_info</structname></title>
60 <tgroup cols="3">
61 &cs-str;
62 <tbody valign="top">
63 <row>
64 <entry>char</entry>
65 <entry><structfield>driver</structfield>[16]</entry>
66 <entry><para>Name of the driver implementing the media API as a
67 NUL-terminated ASCII string. The driver version is stored in the
68 <structfield>driver_version</structfield> field.</para>
69 <para>Driver specific applications can use this information to
70 verify the driver identity. It is also useful to work around
71 known bugs, or to identify drivers in error reports.</para></entry>
72 </row>
73 <row>
74 <entry>char</entry>
75 <entry><structfield>model</structfield>[32]</entry>
76 <entry>Device model name as a NUL-terminated UTF-8 string. The
77 device version is stored in the <structfield>device_version</structfield>
78 field and is not be appended to the model name.</entry>
79 </row>
80 <row>
81 <entry>char</entry>
82 <entry><structfield>serial</structfield>[40]</entry>
83 <entry>Serial number as a NUL-terminated ASCII string.</entry>
84 </row>
85 <row>
86 <entry>char</entry>
87 <entry><structfield>bus_info</structfield>[32]</entry>
88 <entry>Location of the device in the system as a NUL-terminated
89 ASCII string. This includes the bus type name (PCI, USB, ...) and a
90 bus-specific identifier.</entry>
91 </row>
92 <row>
93 <entry>__u32</entry>
94 <entry><structfield>media_version</structfield></entry>
95 <entry>Media API version, formatted with the
96 <constant>KERNEL_VERSION()</constant> macro.</entry>
97 </row>
98 <row>
99 <entry>__u32</entry>
100 <entry><structfield>hw_revision</structfield></entry>
101 <entry>Hardware device revision in a driver-specific format.</entry>
102 </row>
103 <row>
104 <entry>__u32</entry>
105 <entry><structfield>media_version</structfield></entry>
106 <entry>Media device driver version, formatted with the
107 <constant>KERNEL_VERSION()</constant> macro. Together with the
108 <structfield>driver</structfield> field this identifies a particular
109 driver.</entry>
110 </row>
111 <row>
112 <entry>__u32</entry>
113 <entry><structfield>reserved</structfield>[31]</entry>
114 <entry>Reserved for future extensions. Drivers and applications must
115 set this array to zero.</entry>
116 </row>
117 </tbody>
118 </tgroup>
119 </table>
120 <para>The <structfield>serial</structfield> and <structfield>bus_info</structfield>
121 fields can be used to distinguish between multiple instances of otherwise
122 identical hardware. The serial number takes precedence when provided and can
123 be assumed to be unique. If the serial number is an empty string, the
124 <structfield>bus_info</structfield> field can be used instead. The
125 <structfield>bus_info</structfield> field is guaranteed to be unique, but
126 can vary across reboots or device unplug/replug.</para>
127 </refsect1>
128
129 <refsect1>
130 <title>Return value</title>
131 <para>This function doesn't return specific error codes.</para>
132 </refsect1>
133</refentry>
diff --git a/Documentation/DocBook/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/v4l/media-ioc-enum-entities.xml
new file mode 100644
index 000000000000..576b68b33f2c
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-ioc-enum-entities.xml
@@ -0,0 +1,308 @@
1<refentry id="media-ioc-enum-entities">
2 <refmeta>
3 <refentrytitle>ioctl MEDIA_IOC_ENUM_ENTITIES</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>MEDIA_IOC_ENUM_ENTITIES</refname>
9 <refpurpose>Enumerate entities and their properties</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct media_entity_desc *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>File descriptor returned by
31 <link linkend='media-func-open'><function>open()</function></link>.</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>MEDIA_IOC_ENUM_ENTITIES</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51 <para>To query the attributes of an entity, applications set the id field
52 of a &media-entity-desc; structure and call the MEDIA_IOC_ENUM_ENTITIES
53 ioctl with a pointer to this structure. The driver fills the rest of the
54 structure or returns an &EINVAL; when the id is invalid.</para>
55 <para>Entities can be enumerated by or'ing the id with the
56 <constant>MEDIA_ENT_ID_FLAG_NEXT</constant> flag. The driver will return
57 information about the entity with the smallest id strictly larger than the
58 requested one ('next entity'), or the &EINVAL; if there is none.</para>
59 <para>Entity IDs can be non-contiguous. Applications must
60 <emphasis>not</emphasis> try to enumerate entities by calling
61 MEDIA_IOC_ENUM_ENTITIES with increasing id's until they get an error.</para>
62 <para>Two or more entities that share a common non-zero
63 <structfield>group_id</structfield> value are considered as logically
64 grouped. Groups are used to report
65 <itemizedlist>
66 <listitem><para>ALSA, VBI and video nodes that carry the same media
67 stream</para></listitem>
68 <listitem><para>lens and flash controllers associated with a sensor</para></listitem>
69 </itemizedlist>
70 </para>
71
72 <table pgwide="1" frame="none" id="media-entity-desc">
73 <title>struct <structname>media_entity_desc</structname></title>
74 <tgroup cols="5">
75 <colspec colname="c1" />
76 <colspec colname="c2" />
77 <colspec colname="c3" />
78 <colspec colname="c4" />
79 <colspec colname="c5" />
80 <tbody valign="top">
81 <row>
82 <entry>__u32</entry>
83 <entry><structfield>id</structfield></entry>
84 <entry></entry>
85 <entry></entry>
86 <entry>Entity id, set by the application. When the id is or'ed with
87 <constant>MEDIA_ENT_ID_FLAG_NEXT</constant>, the driver clears the
88 flag and returns the first entity with a larger id.</entry>
89 </row>
90 <row>
91 <entry>char</entry>
92 <entry><structfield>name</structfield>[32]</entry>
93 <entry></entry>
94 <entry></entry>
95 <entry>Entity name as an UTF-8 NULL-terminated string.</entry>
96 </row>
97 <row>
98 <entry>__u32</entry>
99 <entry><structfield>type</structfield></entry>
100 <entry></entry>
101 <entry></entry>
102 <entry>Entity type, see <xref linkend="media-entity-type" /> for details.</entry>
103 </row>
104 <row>
105 <entry>__u32</entry>
106 <entry><structfield>revision</structfield></entry>
107 <entry></entry>
108 <entry></entry>
109 <entry>Entity revision in a driver/hardware specific format.</entry>
110 </row>
111 <row>
112 <entry>__u32</entry>
113 <entry><structfield>flags</structfield></entry>
114 <entry></entry>
115 <entry></entry>
116 <entry>Entity flags, see <xref linkend="media-entity-flag" /> for details.</entry>
117 </row>
118 <row>
119 <entry>__u32</entry>
120 <entry><structfield>group_id</structfield></entry>
121 <entry></entry>
122 <entry></entry>
123 <entry>Entity group ID</entry>
124 </row>
125 <row>
126 <entry>__u16</entry>
127 <entry><structfield>pads</structfield></entry>
128 <entry></entry>
129 <entry></entry>
130 <entry>Number of pads</entry>
131 </row>
132 <row>
133 <entry>__u16</entry>
134 <entry><structfield>links</structfield></entry>
135 <entry></entry>
136 <entry></entry>
137 <entry>Total number of outbound links. Inbound links are not counted
138 in this field.</entry>
139 </row>
140 <row>
141 <entry>union</entry>
142 </row>
143 <row>
144 <entry></entry>
145 <entry>struct</entry>
146 <entry><structfield>v4l</structfield></entry>
147 <entry></entry>
148 <entry>Valid for V4L sub-devices and nodes only.</entry>
149 </row>
150 <row>
151 <entry></entry>
152 <entry></entry>
153 <entry>__u32</entry>
154 <entry><structfield>major</structfield></entry>
155 <entry>V4L device node major number. For V4L sub-devices with no
156 device node, set by the driver to 0.</entry>
157 </row>
158 <row>
159 <entry></entry>
160 <entry></entry>
161 <entry>__u32</entry>
162 <entry><structfield>minor</structfield></entry>
163 <entry>V4L device node minor number. For V4L sub-devices with no
164 device node, set by the driver to 0.</entry>
165 </row>
166 <row>
167 <entry></entry>
168 <entry>struct</entry>
169 <entry><structfield>fb</structfield></entry>
170 <entry></entry>
171 <entry>Valid for frame buffer nodes only.</entry>
172 </row>
173 <row>
174 <entry></entry>
175 <entry></entry>
176 <entry>__u32</entry>
177 <entry><structfield>major</structfield></entry>
178 <entry>Frame buffer device node major number.</entry>
179 </row>
180 <row>
181 <entry></entry>
182 <entry></entry>
183 <entry>__u32</entry>
184 <entry><structfield>minor</structfield></entry>
185 <entry>Frame buffer device node minor number.</entry>
186 </row>
187 <row>
188 <entry></entry>
189 <entry>struct</entry>
190 <entry><structfield>alsa</structfield></entry>
191 <entry></entry>
192 <entry>Valid for ALSA devices only.</entry>
193 </row>
194 <row>
195 <entry></entry>
196 <entry></entry>
197 <entry>__u32</entry>
198 <entry><structfield>card</structfield></entry>
199 <entry>ALSA card number</entry>
200 </row>
201 <row>
202 <entry></entry>
203 <entry></entry>
204 <entry>__u32</entry>
205 <entry><structfield>device</structfield></entry>
206 <entry>ALSA device number</entry>
207 </row>
208 <row>
209 <entry></entry>
210 <entry></entry>
211 <entry>__u32</entry>
212 <entry><structfield>subdevice</structfield></entry>
213 <entry>ALSA sub-device number</entry>
214 </row>
215 <row>
216 <entry></entry>
217 <entry>int</entry>
218 <entry><structfield>dvb</structfield></entry>
219 <entry></entry>
220 <entry>DVB card number</entry>
221 </row>
222 <row>
223 <entry></entry>
224 <entry>__u8</entry>
225 <entry><structfield>raw</structfield>[180]</entry>
226 <entry></entry>
227 <entry></entry>
228 </row>
229 </tbody>
230 </tgroup>
231 </table>
232
233 <table frame="none" pgwide="1" id="media-entity-type">
234 <title>Media entity types</title>
235 <tgroup cols="2">
236 <colspec colname="c1"/>
237 <colspec colname="c2"/>
238 <tbody valign="top">
239 <row>
240 <entry><constant>MEDIA_ENT_T_DEVNODE</constant></entry>
241 <entry>Unknown device node</entry>
242 </row>
243 <row>
244 <entry><constant>MEDIA_ENT_T_DEVNODE_V4L</constant></entry>
245 <entry>V4L video, radio or vbi device node</entry>
246 </row>
247 <row>
248 <entry><constant>MEDIA_ENT_T_DEVNODE_FB</constant></entry>
249 <entry>Frame buffer device node</entry>
250 </row>
251 <row>
252 <entry><constant>MEDIA_ENT_T_DEVNODE_ALSA</constant></entry>
253 <entry>ALSA card</entry>
254 </row>
255 <row>
256 <entry><constant>MEDIA_ENT_T_DEVNODE_DVB</constant></entry>
257 <entry>DVB card</entry>
258 </row>
259 <row>
260 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV</constant></entry>
261 <entry>Unknown V4L sub-device</entry>
262 </row>
263 <row>
264 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_SENSOR</constant></entry>
265 <entry>Video sensor</entry>
266 </row>
267 <row>
268 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_FLASH</constant></entry>
269 <entry>Flash controller</entry>
270 </row>
271 <row>
272 <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry>
273 <entry>Lens controller</entry>
274 </row>
275 </tbody>
276 </tgroup>
277 </table>
278
279 <table frame="none" pgwide="1" id="media-entity-flag">
280 <title>Media entity flags</title>
281 <tgroup cols="2">
282 <colspec colname="c1"/>
283 <colspec colname="c2"/>
284 <tbody valign="top">
285 <row>
286 <entry><constant>MEDIA_ENT_FL_DEFAULT</constant></entry>
287 <entry>Default entity for its type. Used to discover the default
288 audio, VBI and video devices, the default camera sensor, ...</entry>
289 </row>
290 </tbody>
291 </tgroup>
292 </table>
293 </refsect1>
294
295 <refsect1>
296 &return-value;
297
298 <variablelist>
299 <varlistentry>
300 <term><errorcode>EINVAL</errorcode></term>
301 <listitem>
302 <para>The &media-entity-desc; <structfield>id</structfield> references
303 a non-existing entity.</para>
304 </listitem>
305 </varlistentry>
306 </variablelist>
307 </refsect1>
308</refentry>
diff --git a/Documentation/DocBook/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/v4l/media-ioc-enum-links.xml
new file mode 100644
index 000000000000..d2fc73ef8d56
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-ioc-enum-links.xml
@@ -0,0 +1,207 @@
1<refentry id="media-ioc-enum-links">
2 <refmeta>
3 <refentrytitle>ioctl MEDIA_IOC_ENUM_LINKS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>MEDIA_IOC_ENUM_LINKS</refname>
9 <refpurpose>Enumerate all pads and links for a given entity</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct media_links_enum *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>File descriptor returned by
31 <link linkend='media-func-open'><function>open()</function></link>.</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>MEDIA_IOC_ENUM_LINKS</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <para>To enumerate pads and/or links for a given entity, applications set
53 the entity field of a &media-links-enum; structure and initialize the
54 &media-pad-desc; and &media-link-desc; structure arrays pointed by the
55 <structfield>pads</structfield> and <structfield>links</structfield> fields.
56 They then call the MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this
57 structure.</para>
58 <para>If the <structfield>pads</structfield> field is not NULL, the driver
59 fills the <structfield>pads</structfield> array with information about the
60 entity's pads. The array must have enough room to store all the entity's
61 pads. The number of pads can be retrieved with the &MEDIA-IOC-ENUM-ENTITIES;
62 ioctl.</para>
63 <para>If the <structfield>links</structfield> field is not NULL, the driver
64 fills the <structfield>links</structfield> array with information about the
65 entity's outbound links. The array must have enough room to store all the
66 entity's outbound links. The number of outbound links can be retrieved with
67 the &MEDIA-IOC-ENUM-ENTITIES; ioctl.</para>
68 <para>Only forward links that originate at one of the entity's source pads
69 are returned during the enumeration process.</para>
70
71 <table pgwide="1" frame="none" id="media-links-enum">
72 <title>struct <structname>media_links_enum</structname></title>
73 <tgroup cols="3">
74 &cs-str;
75 <tbody valign="top">
76 <row>
77 <entry>__u32</entry>
78 <entry><structfield>entity</structfield></entry>
79 <entry>Entity id, set by the application.</entry>
80 </row>
81 <row>
82 <entry>struct &media-pad-desc;</entry>
83 <entry>*<structfield>pads</structfield></entry>
84 <entry>Pointer to a pads array allocated by the application. Ignored
85 if NULL.</entry>
86 </row>
87 <row>
88 <entry>struct &media-link-desc;</entry>
89 <entry>*<structfield>links</structfield></entry>
90 <entry>Pointer to a links array allocated by the application. Ignored
91 if NULL.</entry>
92 </row>
93 </tbody>
94 </tgroup>
95 </table>
96
97 <table pgwide="1" frame="none" id="media-pad-desc">
98 <title>struct <structname>media_pad_desc</structname></title>
99 <tgroup cols="3">
100 &cs-str;
101 <tbody valign="top">
102 <row>
103 <entry>__u32</entry>
104 <entry><structfield>entity</structfield></entry>
105 <entry>ID of the entity this pad belongs to.</entry>
106 </row>
107 <row>
108 <entry>__u16</entry>
109 <entry><structfield>index</structfield></entry>
110 <entry>0-based pad index.</entry>
111 </row>
112 <row>
113 <entry>__u32</entry>
114 <entry><structfield>flags</structfield></entry>
115 <entry>Pad flags, see <xref linkend="media-pad-flag" /> for more details.</entry>
116 </row>
117 </tbody>
118 </tgroup>
119 </table>
120
121 <table frame="none" pgwide="1" id="media-pad-flag">
122 <title>Media pad flags</title>
123 <tgroup cols="2">
124 <colspec colname="c1"/>
125 <colspec colname="c2"/>
126 <tbody valign="top">
127 <row>
128 <entry><constant>MEDIA_PAD_FL_SINK</constant></entry>
129 <entry>Input pad, relative to the entity. Input pads sink data and
130 are targets of links.</entry>
131 </row>
132 <row>
133 <entry><constant>MEDIA_PAD_FL_SOURCE</constant></entry>
134 <entry>Output pad, relative to the entity. Output pads source data
135 and are origins of links.</entry>
136 </row>
137 </tbody>
138 </tgroup>
139 </table>
140
141 <table pgwide="1" frame="none" id="media-link-desc">
142 <title>struct <structname>media_links_desc</structname></title>
143 <tgroup cols="3">
144 &cs-str;
145 <tbody valign="top">
146 <row>
147 <entry>struct &media-pad-desc;</entry>
148 <entry><structfield>source</structfield></entry>
149 <entry>Pad at the origin of this link.</entry>
150 </row>
151 <row>
152 <entry>struct &media-pad-desc;</entry>
153 <entry><structfield>sink</structfield></entry>
154 <entry>Pad at the target of this link.</entry>
155 </row>
156 <row>
157 <entry>__u32</entry>
158 <entry><structfield>flags</structfield></entry>
159 <entry>Link flags, see <xref linkend="media-link-flag" /> for more details.</entry>
160 </row>
161 </tbody>
162 </tgroup>
163 </table>
164
165 <table frame="none" pgwide="1" id="media-link-flag">
166 <title>Media link flags</title>
167 <tgroup cols="2">
168 <colspec colname="c1"/>
169 <colspec colname="c2"/>
170 <tbody valign="top">
171 <row>
172 <entry><constant>MEDIA_LNK_FL_ENABLED</constant></entry>
173 <entry>The link is enabled and can be used to transfer media data.
174 When two or more links target a sink pad, only one of them can be
175 enabled at a time.</entry>
176 </row>
177 <row>
178 <entry><constant>MEDIA_LNK_FL_IMMUTABLE</constant></entry>
179 <entry>The link enabled state can't be modified at runtime. An
180 immutable link is always enabled.</entry>
181 </row>
182 <row>
183 <entry><constant>MEDIA_LNK_FL_DYNAMIC</constant></entry>
184 <entry>The link enabled state can be modified during streaming. This
185 flag is set by drivers and is read-only for applications.</entry>
186 </row>
187 </tbody>
188 </tgroup>
189 </table>
190 <para>One and only one of <constant>MEDIA_PAD_FL_SINK</constant> and
191 <constant>MEDIA_PAD_FL_SOURCE</constant> must be set for every pad.</para>
192 </refsect1>
193
194 <refsect1>
195 &return-value;
196
197 <variablelist>
198 <varlistentry>
199 <term><errorcode>EINVAL</errorcode></term>
200 <listitem>
201 <para>The &media-links-enum; <structfield>id</structfield> references
202 a non-existing entity.</para>
203 </listitem>
204 </varlistentry>
205 </variablelist>
206 </refsect1>
207</refentry>
diff --git a/Documentation/DocBook/v4l/media-ioc-setup-link.xml b/Documentation/DocBook/v4l/media-ioc-setup-link.xml
new file mode 100644
index 000000000000..2331e76ded17
--- /dev/null
+++ b/Documentation/DocBook/v4l/media-ioc-setup-link.xml
@@ -0,0 +1,93 @@
1<refentry id="media-ioc-setup-link">
2 <refmeta>
3 <refentrytitle>ioctl MEDIA_IOC_SETUP_LINK</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>MEDIA_IOC_SETUP_LINK</refname>
9 <refpurpose>Modify the properties of a link</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct media_link_desc *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>File descriptor returned by
31 <link linkend='media-func-open'><function>open()</function></link>.</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>MEDIA_IOC_ENUM_LINKS</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <para>To change link properties applications fill a &media-link-desc; with
53 link identification information (source and sink pad) and the new requested
54 link flags. They then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to
55 that structure.</para>
56 <para>The only configurable property is the <constant>ENABLED</constant>
57 link flag to enable/disable a link. Links marked with the
58 <constant>IMMUTABLE</constant> link flag can not be enabled or disabled.
59 </para>
60 <para>Link configuration has no side effect on other links. If an enabled
61 link at the sink pad prevents the link from being enabled, the driver
62 returns with an &EBUSY;.</para>
63 <para>Only links marked with the <constant>DYNAMIC</constant> link flag can
64 be enabled/disabled while streaming media data. Attempting to enable or
65 disable a streaming non-dynamic link will return an &EBUSY;.</para>
66 <para>If the specified link can't be found the driver returns with an
67 &EINVAL;.</para>
68 </refsect1>
69
70 <refsect1>
71 &return-value;
72
73 <variablelist>
74 <varlistentry>
75 <term><errorcode>EBUSY</errorcode></term>
76 <listitem>
77 <para>The link properties can't be changed because the link is
78 currently busy. This can be caused, for instance, by an active media
79 stream (audio or video) on the link. The ioctl shouldn't be retried if
80 no other action is performed before to fix the problem.</para>
81 </listitem>
82 </varlistentry>
83 <varlistentry>
84 <term><errorcode>EINVAL</errorcode></term>
85 <listitem>
86 <para>The &media-link-desc; references a non-existing link, or the
87 link is immutable and an attempt to modify its configuration was made.
88 </para>
89 </listitem>
90 </varlistentry>
91 </variablelist>
92 </refsect1>
93</refentry>
diff --git a/Documentation/DocBook/v4l/nv12mt.gif b/Documentation/DocBook/v4l/nv12mt.gif
new file mode 100644
index 000000000000..ef2d4cf8367b
--- /dev/null
+++ b/Documentation/DocBook/v4l/nv12mt.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/nv12mt_example.gif b/Documentation/DocBook/v4l/nv12mt_example.gif
new file mode 100644
index 000000000000..df81d68108ee
--- /dev/null
+++ b/Documentation/DocBook/v4l/nv12mt_example.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/pipeline.pdf b/Documentation/DocBook/v4l/pipeline.pdf
new file mode 100644
index 000000000000..ee3e37f04b6a
--- /dev/null
+++ b/Documentation/DocBook/v4l/pipeline.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/pipeline.png b/Documentation/DocBook/v4l/pipeline.png
new file mode 100644
index 000000000000..f19b86c2c24d
--- /dev/null
+++ b/Documentation/DocBook/v4l/pipeline.png
Binary files differ
diff --git a/Documentation/DocBook/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/v4l/pixfmt-nv12m.xml
new file mode 100644
index 000000000000..c9e166d9ded8
--- /dev/null
+++ b/Documentation/DocBook/v4l/pixfmt-nv12m.xml
@@ -0,0 +1,154 @@
1 <refentry id="V4L2-PIX-FMT-NV12M">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_NV12M ('NV12M')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname> <constant>V4L2_PIX_FMT_NV12M</constant></refname>
8 <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> with planes
9 non contiguous in memory. </refpurpose>
10 </refnamediv>
11 <refsect1>
12 <title>Description</title>
13
14 <para>This is a multi-planar, two-plane version of the YUV 4:2:0 format.
15The three components are separated into two sub-images or planes.
16<constant>V4L2_PIX_FMT_NV12M</constant> differs from <constant>V4L2_PIX_FMT_NV12
17</constant> in that the two planes are non-contiguous in memory, i.e. the chroma
18plane do not necessarily immediately follows the luma plane.
19The luminance data occupies the first plane. The Y plane has one byte per pixel.
20In the second plane there is a chrominance data with alternating chroma samples.
21The CbCr plane is the same width, in bytes, as the Y plane (and of the image),
22but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example,
23Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
24Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
25Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. </para>
26
27 <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be
28used only in drivers and applications that support the multi-planar API,
29described in <xref linkend="planar-apis"/>. </para>
30
31 <para>If the Y plane has pad bytes after each row, then the
32CbCr plane has as many pad bytes after its rows.</para>
33
34 <example>
35 <title><constant>V4L2_PIX_FMT_NV12M</constant> 4 &times; 4 pixel image</title>
36
37 <formalpara>
38 <title>Byte Order.</title>
39 <para>Each cell is one byte.
40 <informaltable frame="none">
41 <tgroup cols="5" align="center">
42 <colspec align="left" colwidth="2*" />
43 <tbody valign="top">
44 <row>
45 <entry>start0&nbsp;+&nbsp;0:</entry>
46 <entry>Y'<subscript>00</subscript></entry>
47 <entry>Y'<subscript>01</subscript></entry>
48 <entry>Y'<subscript>02</subscript></entry>
49 <entry>Y'<subscript>03</subscript></entry>
50 </row>
51 <row>
52 <entry>start0&nbsp;+&nbsp;4:</entry>
53 <entry>Y'<subscript>10</subscript></entry>
54 <entry>Y'<subscript>11</subscript></entry>
55 <entry>Y'<subscript>12</subscript></entry>
56 <entry>Y'<subscript>13</subscript></entry>
57 </row>
58 <row>
59 <entry>start0&nbsp;+&nbsp;8:</entry>
60 <entry>Y'<subscript>20</subscript></entry>
61 <entry>Y'<subscript>21</subscript></entry>
62 <entry>Y'<subscript>22</subscript></entry>
63 <entry>Y'<subscript>23</subscript></entry>
64 </row>
65 <row>
66 <entry>start0&nbsp;+&nbsp;12:</entry>
67 <entry>Y'<subscript>30</subscript></entry>
68 <entry>Y'<subscript>31</subscript></entry>
69 <entry>Y'<subscript>32</subscript></entry>
70 <entry>Y'<subscript>33</subscript></entry>
71 </row>
72 <row>
73 <entry></entry>
74 </row>
75 <row>
76 <entry>start1&nbsp;+&nbsp;0:</entry>
77 <entry>Cb<subscript>00</subscript></entry>
78 <entry>Cr<subscript>00</subscript></entry>
79 <entry>Cb<subscript>01</subscript></entry>
80 <entry>Cr<subscript>01</subscript></entry>
81 </row>
82 <row>
83 <entry>start1&nbsp;+&nbsp;4:</entry>
84 <entry>Cb<subscript>10</subscript></entry>
85 <entry>Cr<subscript>10</subscript></entry>
86 <entry>Cb<subscript>11</subscript></entry>
87 <entry>Cr<subscript>11</subscript></entry>
88 </row>
89 </tbody>
90 </tgroup>
91 </informaltable>
92 </para>
93 </formalpara>
94
95 <formalpara>
96 <title>Color Sample Location.</title>
97 <para>
98 <informaltable frame="none">
99 <tgroup cols="7" align="center">
100 <tbody valign="top">
101 <row>
102 <entry></entry>
103 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
104 <entry>2</entry><entry></entry><entry>3</entry>
105 </row>
106 <row>
107 <entry>0</entry>
108 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
109 <entry>Y</entry><entry></entry><entry>Y</entry>
110 </row>
111 <row>
112 <entry></entry>
113 <entry></entry><entry>C</entry><entry></entry><entry></entry>
114 <entry></entry><entry>C</entry><entry></entry>
115 </row>
116 <row>
117 <entry>1</entry>
118 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
119 <entry>Y</entry><entry></entry><entry>Y</entry>
120 </row>
121 <row>
122 <entry></entry>
123 </row>
124 <row>
125 <entry>2</entry>
126 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
127 <entry>Y</entry><entry></entry><entry>Y</entry>
128 </row>
129 <row>
130 <entry></entry>
131 <entry></entry><entry>C</entry><entry></entry><entry></entry>
132 <entry></entry><entry>C</entry><entry></entry>
133 </row>
134 <row>
135 <entry>3</entry>
136 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
137 <entry>Y</entry><entry></entry><entry>Y</entry>
138 </row>
139 </tbody>
140 </tgroup>
141 </informaltable>
142 </para>
143 </formalpara>
144 </example>
145 </refsect1>
146 </refentry>
147
148 <!--
149Local Variables:
150mode: sgml
151sgml-parent-document: "pixfmt.sgml"
152indent-tabs-mode: nil
153End:
154 -->
diff --git a/Documentation/DocBook/v4l/pixfmt-nv12mt.xml b/Documentation/DocBook/v4l/pixfmt-nv12mt.xml
new file mode 100644
index 000000000000..7a2855a526c1
--- /dev/null
+++ b/Documentation/DocBook/v4l/pixfmt-nv12mt.xml
@@ -0,0 +1,74 @@
1 <refentry>
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_NV12MT ('TM12')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname id="V4L2-PIX-FMT-NV12MT"><constant>V4L2_PIX_FMT_NV12MT
8</constant></refname>
9 <refpurpose>Formats with &frac12; horizontal and vertical
10chroma resolution. This format has two planes - one for luminance and one for
11chrominance. Chroma samples are interleaved. The difference to
12<constant>V4L2_PIX_FMT_NV12</constant> is the memory layout. Pixels are
13grouped in macroblocks of 64x32 size. The order of macroblocks in memory is
14also not standard.
15 </refpurpose>
16 </refnamediv>
17 <refsect1>
18 <title>Description</title>
19
20 <para>This is the two-plane versions of the YUV 4:2:0 format where data
21is grouped into 64x32 macroblocks. The three components are separated into two
22sub-images or planes. The Y plane has one byte per pixel and pixels are grouped
23into 64x32 macroblocks. The CbCr plane has the same width, in bytes, as the Y
24plane (and the image), but is half as tall in pixels. The chroma plane is also
25grouped into 64x32 macroblocks.</para>
26 <para>Width of the buffer has to be aligned to the multiple of 128, and
27height alignment is 32. Every four adjactent buffers - two horizontally and two
28vertically are grouped together and are located in memory in Z or flipped Z
29order. </para>
30 <para>Layout of macroblocks in memory is presented in the following
31figure.</para>
32 <para><figure id="nv12mt">
33 <title><constant>V4L2_PIX_FMT_NV12MT</constant> macroblock Z shape
34memory layout</title>
35 <mediaobject>
36 <imageobject>
37 <imagedata fileref="nv12mt.gif" format="GIF" />
38 </imageobject>
39 </mediaobject>
40 </figure>
41 The requirement that width is multiple of 128 is implemented because,
42the Z shape cannot be cut in half horizontally. In case the vertical resolution
43of macroblocks is odd then the last row of macroblocks is arranged in a linear
44order. </para>
45 <para>In case of chroma the layout is identical. Cb and Cr samples are
46interleaved. Height of the buffer is aligned to 32.
47 </para>
48 <example>
49 <title>Memory layout of macroblocks in <constant>V4L2_PIX_FMT_NV12
50</constant> format pixel image - extreme case</title>
51 <para>
52 <figure id="nv12mt_ex">
53 <title>Example <constant>V4L2_PIX_FMT_NV12MT</constant> memory
54layout of macroblocks</title>
55 <mediaobject>
56 <imageobject>
57 <imagedata fileref="nv12mt_example.gif" format="GIF" />
58 </imageobject>
59 </mediaobject>
60 </figure>
61 Memory layout of macroblocks of <constant>V4L2_PIX_FMT_NV12MT
62</constant> format in most extreme case.
63 </para>
64 </example>
65 </refsect1>
66 </refentry>
67
68 <!--
69Local Variables:
70mode: sgml
71sgml-parent-document: "pixfmt.sgml"
72indent-tabs-mode: nil
73End:
74 -->
diff --git a/Documentation/DocBook/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/v4l/pixfmt-srggb12.xml
new file mode 100644
index 000000000000..9ba4fb690bc0
--- /dev/null
+++ b/Documentation/DocBook/v4l/pixfmt-srggb12.xml
@@ -0,0 +1,90 @@
1 <refentry>
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_SRGGB12 ('RG12'),
4 V4L2_PIX_FMT_SGRBG12 ('BA12'),
5 V4L2_PIX_FMT_SGBRG12 ('GB12'),
6 V4L2_PIX_FMT_SBGGR12 ('BG12'),
7 </refentrytitle>
8 &manvol;
9 </refmeta>
10 <refnamediv>
11 <refname id="V4L2-PIX-FMT-SRGGB12"><constant>V4L2_PIX_FMT_SRGGB12</constant></refname>
12 <refname id="V4L2-PIX-FMT-SGRBG12"><constant>V4L2_PIX_FMT_SGRBG12</constant></refname>
13 <refname id="V4L2-PIX-FMT-SGBRG12"><constant>V4L2_PIX_FMT_SGBRG12</constant></refname>
14 <refname id="V4L2-PIX-FMT-SBGGR12"><constant>V4L2_PIX_FMT_SBGGR12</constant></refname>
15 <refpurpose>12-bit Bayer formats expanded to 16 bits</refpurpose>
16 </refnamediv>
17 <refsect1>
18 <title>Description</title>
19
20 <para>The following four pixel formats are raw sRGB / Bayer formats with
2112 bits per colour. Each colour component is stored in a 16-bit word, with 6
22unused high bits filled with zeros. Each n-pixel row contains n/2 green samples
23and n/2 blue or red samples, with alternating red and blue rows. Bytes are
24stored in memory in little endian order. They are conventionally described
25as GRGR... BGBG..., RGRG... GBGB..., etc. Below is an example of one of these
26formats</para>
27
28 <example>
29 <title><constant>V4L2_PIX_FMT_SBGGR12</constant> 4 &times; 4
30pixel image</title>
31
32 <formalpara>
33 <title>Byte Order.</title>
34 <para>Each cell is one byte, high 6 bits in high bytes are 0.
35 <informaltable frame="none">
36 <tgroup cols="5" align="center">
37 <colspec align="left" colwidth="2*" />
38 <tbody valign="top">
39 <row>
40 <entry>start&nbsp;+&nbsp;0:</entry>
41 <entry>B<subscript>00low</subscript></entry>
42 <entry>B<subscript>00high</subscript></entry>
43 <entry>G<subscript>01low</subscript></entry>
44 <entry>G<subscript>01high</subscript></entry>
45 <entry>B<subscript>02low</subscript></entry>
46 <entry>B<subscript>02high</subscript></entry>
47 <entry>G<subscript>03low</subscript></entry>
48 <entry>G<subscript>03high</subscript></entry>
49 </row>
50 <row>
51 <entry>start&nbsp;+&nbsp;8:</entry>
52 <entry>G<subscript>10low</subscript></entry>
53 <entry>G<subscript>10high</subscript></entry>
54 <entry>R<subscript>11low</subscript></entry>
55 <entry>R<subscript>11high</subscript></entry>
56 <entry>G<subscript>12low</subscript></entry>
57 <entry>G<subscript>12high</subscript></entry>
58 <entry>R<subscript>13low</subscript></entry>
59 <entry>R<subscript>13high</subscript></entry>
60 </row>
61 <row>
62 <entry>start&nbsp;+&nbsp;16:</entry>
63 <entry>B<subscript>20low</subscript></entry>
64 <entry>B<subscript>20high</subscript></entry>
65 <entry>G<subscript>21low</subscript></entry>
66 <entry>G<subscript>21high</subscript></entry>
67 <entry>B<subscript>22low</subscript></entry>
68 <entry>B<subscript>22high</subscript></entry>
69 <entry>G<subscript>23low</subscript></entry>
70 <entry>G<subscript>23high</subscript></entry>
71 </row>
72 <row>
73 <entry>start&nbsp;+&nbsp;24:</entry>
74 <entry>G<subscript>30low</subscript></entry>
75 <entry>G<subscript>30high</subscript></entry>
76 <entry>R<subscript>31low</subscript></entry>
77 <entry>R<subscript>31high</subscript></entry>
78 <entry>G<subscript>32low</subscript></entry>
79 <entry>G<subscript>32high</subscript></entry>
80 <entry>R<subscript>33low</subscript></entry>
81 <entry>R<subscript>33high</subscript></entry>
82 </row>
83 </tbody>
84 </tgroup>
85 </informaltable>
86 </para>
87 </formalpara>
88 </example>
89 </refsect1>
90</refentry>
diff --git a/Documentation/DocBook/v4l/pixfmt-yuv420m.xml b/Documentation/DocBook/v4l/pixfmt-yuv420m.xml
new file mode 100644
index 000000000000..f5d8f57495c8
--- /dev/null
+++ b/Documentation/DocBook/v4l/pixfmt-yuv420m.xml
@@ -0,0 +1,162 @@
1 <refentry id="V4L2-PIX-FMT-YUV420M">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_YUV420M ('YU12M')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname> <constant>V4L2_PIX_FMT_YUV420M</constant></refname>
8 <refpurpose>Variation of <constant>V4L2_PIX_FMT_YUV420</constant>
9 with planes non contiguous in memory. </refpurpose>
10 </refnamediv>
11
12 <refsect1>
13 <title>Description</title>
14
15 <para>This is a multi-planar format, as opposed to a packed format.
16The three components are separated into three sub- images or planes.
17
18The Y plane is first. The Y plane has one byte per pixel. The Cb data
19constitutes the second plane which is half the width and half
20the height of the Y plane (and of the image). Each Cb belongs to four
21pixels, a two-by-two square of the image. For example,
22Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
23Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
24Y'<subscript>11</subscript>. The Cr data, just like the Cb plane, is
25in the third plane. </para>
26
27 <para>If the Y plane has pad bytes after each row, then the Cb
28and Cr planes have half as many pad bytes after their rows. In other
29words, two Cx rows (including padding) is exactly as long as one Y row
30(including padding).</para>
31
32 <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be
33used only in drivers and applications that support the multi-planar API,
34described in <xref linkend="planar-apis"/>. </para>
35
36 <example>
37 <title><constant>V4L2_PIX_FMT_YVU420M</constant> 4 &times; 4
38pixel image</title>
39
40 <formalpara>
41 <title>Byte Order.</title>
42 <para>Each cell is one byte.
43 <informaltable frame="none">
44 <tgroup cols="5" align="center">
45 <colspec align="left" colwidth="2*" />
46 <tbody valign="top">
47 <row>
48 <entry>start0&nbsp;+&nbsp;0:</entry>
49 <entry>Y'<subscript>00</subscript></entry>
50 <entry>Y'<subscript>01</subscript></entry>
51 <entry>Y'<subscript>02</subscript></entry>
52 <entry>Y'<subscript>03</subscript></entry>
53 </row>
54 <row>
55 <entry>start0&nbsp;+&nbsp;4:</entry>
56 <entry>Y'<subscript>10</subscript></entry>
57 <entry>Y'<subscript>11</subscript></entry>
58 <entry>Y'<subscript>12</subscript></entry>
59 <entry>Y'<subscript>13</subscript></entry>
60 </row>
61 <row>
62 <entry>start0&nbsp;+&nbsp;8:</entry>
63 <entry>Y'<subscript>20</subscript></entry>
64 <entry>Y'<subscript>21</subscript></entry>
65 <entry>Y'<subscript>22</subscript></entry>
66 <entry>Y'<subscript>23</subscript></entry>
67 </row>
68 <row>
69 <entry>start0&nbsp;+&nbsp;12:</entry>
70 <entry>Y'<subscript>30</subscript></entry>
71 <entry>Y'<subscript>31</subscript></entry>
72 <entry>Y'<subscript>32</subscript></entry>
73 <entry>Y'<subscript>33</subscript></entry>
74 </row>
75 <row><entry></entry></row>
76 <row>
77 <entry>start1&nbsp;+&nbsp;0:</entry>
78 <entry>Cb<subscript>00</subscript></entry>
79 <entry>Cb<subscript>01</subscript></entry>
80 </row>
81 <row>
82 <entry>start1&nbsp;+&nbsp;2:</entry>
83 <entry>Cb<subscript>10</subscript></entry>
84 <entry>Cb<subscript>11</subscript></entry>
85 </row>
86 <row><entry></entry></row>
87 <row>
88 <entry>start2&nbsp;+&nbsp;0:</entry>
89 <entry>Cr<subscript>00</subscript></entry>
90 <entry>Cr<subscript>01</subscript></entry>
91 </row>
92 <row>
93 <entry>start2&nbsp;+&nbsp;2:</entry>
94 <entry>Cr<subscript>10</subscript></entry>
95 <entry>Cr<subscript>11</subscript></entry>
96 </row>
97 </tbody>
98 </tgroup>
99 </informaltable>
100 </para>
101 </formalpara>
102
103 <formalpara>
104 <title>Color Sample Location.</title>
105 <para>
106 <informaltable frame="none">
107 <tgroup cols="7" align="center">
108 <tbody valign="top">
109 <row>
110 <entry></entry>
111 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
112 <entry>2</entry><entry></entry><entry>3</entry>
113 </row>
114 <row>
115 <entry>0</entry>
116 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
117 <entry>Y</entry><entry></entry><entry>Y</entry>
118 </row>
119 <row>
120 <entry></entry>
121 <entry></entry><entry>C</entry><entry></entry><entry></entry>
122 <entry></entry><entry>C</entry><entry></entry>
123 </row>
124 <row>
125 <entry>1</entry>
126 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
127 <entry>Y</entry><entry></entry><entry>Y</entry>
128 </row>
129 <row>
130 <entry></entry>
131 </row>
132 <row>
133 <entry>2</entry>
134 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
135 <entry>Y</entry><entry></entry><entry>Y</entry>
136 </row>
137 <row>
138 <entry></entry>
139 <entry></entry><entry>C</entry><entry></entry><entry></entry>
140 <entry></entry><entry>C</entry><entry></entry>
141 </row>
142 <row>
143 <entry>3</entry>
144 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
145 <entry>Y</entry><entry></entry><entry>Y</entry>
146 </row>
147 </tbody>
148 </tgroup>
149 </informaltable>
150 </para>
151 </formalpara>
152 </example>
153 </refsect1>
154 </refentry>
155
156 <!--
157Local Variables:
158mode: sgml
159sgml-parent-document: "pixfmt.sgml"
160indent-tabs-mode: nil
161End:
162 -->
diff --git a/Documentation/DocBook/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml
index cfffc88d7383..c6fdcbbd1b41 100644
--- a/Documentation/DocBook/v4l/pixfmt.xml
+++ b/Documentation/DocBook/v4l/pixfmt.xml
@@ -2,12 +2,16 @@
2 2
3 <para>The V4L2 API was primarily designed for devices exchanging 3 <para>The V4L2 API was primarily designed for devices exchanging
4image data with applications. The 4image data with applications. The
5<structname>v4l2_pix_format</structname> structure defines the format 5<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane
6and layout of an image in memory. Image formats are negotiated with 6</structname> structures define the format and layout of an image in memory.
7the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video 7The former is used with the single-planar API, while the latter is used with the
8multi-planar version (see <xref linkend="planar-apis"/>). Image formats are
9negotiated with the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
8capturing and output, for overlay frame buffer formats see also 10capturing and output, for overlay frame buffer formats see also
9&VIDIOC-G-FBUF;.)</para> 11&VIDIOC-G-FBUF;.)</para>
10 12
13<section>
14 <title>Single-planar format structure</title>
11 <table pgwide="1" frame="none" id="v4l2-pix-format"> 15 <table pgwide="1" frame="none" id="v4l2-pix-format">
12 <title>struct <structname>v4l2_pix_format</structname></title> 16 <title>struct <structname>v4l2_pix_format</structname></title>
13 <tgroup cols="3"> 17 <tgroup cols="3">
@@ -106,6 +110,98 @@ set this field to zero.</entry>
106 </tbody> 110 </tbody>
107 </tgroup> 111 </tgroup>
108 </table> 112 </table>
113</section>
114
115<section>
116 <title>Multi-planar format structures</title>
117 <para>The <structname>v4l2_plane_pix_format</structname> structures define
118 size and layout for each of the planes in a multi-planar format.
119 The <structname>v4l2_pix_format_mplane</structname> structure contains
120 information common to all planes (such as image width and height) and
121 an array of <structname>v4l2_plane_pix_format</structname> structures,
122 describing all planes of that format.</para>
123 <table pgwide="1" frame="none" id="v4l2-plane-pix-format">
124 <title>struct <structname>vl42_plane_pix_format</structname></title>
125 <tgroup cols="3">
126 &cs-str;
127 <tbody valign="top">
128 <row>
129 <entry>__u32</entry>
130 <entry><structfield>sizeimage</structfield></entry>
131 <entry>Maximum size in bytes required for image data in this plane.
132 </entry>
133 </row>
134 <row>
135 <entry>__u16</entry>
136 <entry><structfield>bytesperline</structfield></entry>
137 <entry>Distance in bytes between the leftmost pixels in two adjacent
138 lines.</entry>
139 </row>
140 <row>
141 <entry>__u16</entry>
142 <entry><structfield>reserved[7]</structfield></entry>
143 <entry>Reserved for future extensions. Should be zeroed by the
144 application.</entry>
145 </row>
146 </tbody>
147 </tgroup>
148 </table>
149 <table pgwide="1" frame="none" id="v4l2-pix-format-mplane">
150 <title>struct <structname>v4l2_pix_format_mplane</structname></title>
151 <tgroup cols="3">
152 &cs-str;
153 <tbody valign="top">
154 <row>
155 <entry>__u32</entry>
156 <entry><structfield>width</structfield></entry>
157 <entry>Image width in pixels.</entry>
158 </row>
159 <row>
160 <entry>__u32</entry>
161 <entry><structfield>height</structfield></entry>
162 <entry>Image height in pixels.</entry>
163 </row>
164 <row>
165 <entry>__u32</entry>
166 <entry><structfield>pixelformat</structfield></entry>
167 <entry>The pixel format. Both single- and multi-planar four character
168codes can be used.</entry>
169 </row>
170 <row>
171 <entry>&v4l2-field;</entry>
172 <entry><structfield>field</structfield></entry>
173 <entry>See &v4l2-pix-format;.</entry>
174 </row>
175 <row>
176 <entry>&v4l2-colorspace;</entry>
177 <entry><structfield>colorspace</structfield></entry>
178 <entry>See &v4l2-pix-format;.</entry>
179 </row>
180 <row>
181 <entry>&v4l2-plane-pix-format;</entry>
182 <entry><structfield>plane_fmt[VIDEO_MAX_PLANES]</structfield></entry>
183 <entry>An array of structures describing format of each plane this
184 pixel format consists of. The number of valid entries in this array
185 has to be put in the <structfield>num_planes</structfield>
186 field.</entry>
187 </row>
188 <row>
189 <entry>__u8</entry>
190 <entry><structfield>num_planes</structfield></entry>
191 <entry>Number of planes (i.e. separate memory buffers) for this format
192 and the number of valid entries in the
193 <structfield>plane_fmt</structfield> array.</entry>
194 </row>
195 <row>
196 <entry>__u8</entry>
197 <entry><structfield>reserved[11]</structfield></entry>
198 <entry>Reserved for future extensions. Should be zeroed by the
199 application.</entry>
200 </row>
201 </tbody>
202 </tgroup>
203 </table>
204</section>
109 205
110 <section> 206 <section>
111 <title>Standard Image Formats</title> 207 <title>Standard Image Formats</title>
@@ -142,11 +238,19 @@ leftmost pixel of the second row from the top, and so on. The last row
142has just as many pad bytes after it as the other rows.</para> 238has just as many pad bytes after it as the other rows.</para>
143 239
144 <para>In V4L2 each format has an identifier which looks like 240 <para>In V4L2 each format has an identifier which looks like
145<constant>PIX_FMT_XXX</constant>, defined in the <filename>videodev2.h</filename> 241<constant>PIX_FMT_XXX</constant>, defined in the <link
146header file. These identifiers 242linkend="videodev">videodev.h</link> header file. These identifiers
147represent <link linkend="v4l2-fourcc">four character codes</link> 243represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
148which are also listed below, however they are not the same as those 244which are also listed below, however they are not the same as those
149used in the Windows world.</para> 245used in the Windows world.</para>
246
247 <para>For some formats, data is stored in separate, discontiguous
248memory buffers. Those formats are identified by a separate set of FourCC codes
249and are referred to as "multi-planar formats". For example, a YUV422 frame is
250normally stored in one memory buffer, but it can also be placed in two or three
251separate buffers, with Y component in one buffer and CbCr components in another
252in the 2-planar version or with each component in its own buffer in the
2533-planar case. Those sub-buffers are referred to as "planes".</para>
150 </section> 254 </section>
151 255
152 <section id="colorspaces"> 256 <section id="colorspaces">
@@ -599,10 +703,13 @@ information.</para>
599 &sub-vyuy; 703 &sub-vyuy;
600 &sub-y41p; 704 &sub-y41p;
601 &sub-yuv420; 705 &sub-yuv420;
706 &sub-yuv420m;
602 &sub-yuv410; 707 &sub-yuv410;
603 &sub-yuv422p; 708 &sub-yuv422p;
604 &sub-yuv411p; 709 &sub-yuv411p;
605 &sub-nv12; 710 &sub-nv12;
711 &sub-nv12m;
712 &sub-nv12mt;
606 &sub-nv16; 713 &sub-nv16;
607 </section> 714 </section>
608 715
diff --git a/Documentation/DocBook/v4l/planar-apis.xml b/Documentation/DocBook/v4l/planar-apis.xml
new file mode 100644
index 000000000000..878ce2040488
--- /dev/null
+++ b/Documentation/DocBook/v4l/planar-apis.xml
@@ -0,0 +1,62 @@
1<section id="planar-apis">
2 <title>Single- and multi-planar APIs</title>
3
4 <para>Some devices require data for each input or output video frame
5 to be placed in discontiguous memory buffers. In such cases, one
6 video frame has to be addressed using more than one memory address, i.e. one
7 pointer per "plane". A plane is a sub-buffer of the current frame. For
8 examples of such formats see <xref linkend="pixfmt" />.</para>
9
10 <para>Initially, V4L2 API did not support multi-planar buffers and a set of
11 extensions has been introduced to handle them. Those extensions constitute
12 what is being referred to as the "multi-planar API".</para>
13
14 <para>Some of the V4L2 API calls and structures are interpreted differently,
15 depending on whether single- or multi-planar API is being used. An application
16 can choose whether to use one or the other by passing a corresponding buffer
17 type to its ioctl calls. Multi-planar versions of buffer types are suffixed
18 with an `_MPLANE' string. For a list of available multi-planar buffer types
19 see &v4l2-buf-type;.
20 </para>
21
22 <section>
23 <title>Multi-planar formats</title>
24 <para>Multi-planar API introduces new multi-planar formats. Those formats
25 use a separate set of FourCC codes. It is important to distinguish between
26 the multi-planar API and a multi-planar format. Multi-planar API calls can
27 handle all single-planar formats as well (as long as they are passed in
28 multi-planar API structures), while the single-planar API cannot
29 handle multi-planar formats.</para>
30 </section>
31
32 <section>
33 <title>Calls that distinguish between single and multi-planar APIs</title>
34 <variablelist>
35 <varlistentry>
36 <term>&VIDIOC-QUERYCAP;</term>
37 <listitem><para>Two additional multi-planar capabilities are added. They can
38 be set together with non-multi-planar ones for devices that handle
39 both single- and multi-planar formats.</para></listitem>
40 </varlistentry>
41 <varlistentry>
42 <term>&VIDIOC-G-FMT;, &VIDIOC-S-FMT;, &VIDIOC-TRY-FMT;</term>
43 <listitem><para>New structures for describing multi-planar formats are added:
44 &v4l2-pix-format-mplane; and &v4l2-plane-pix-format;. Drivers may
45 define new multi-planar formats, which have distinct FourCC codes from
46 the existing single-planar ones.</para>
47 </listitem>
48 </varlistentry>
49 <varlistentry>
50 <term>&VIDIOC-QBUF;, &VIDIOC-DQBUF;, &VIDIOC-QUERYBUF;</term>
51 <listitem><para>A new &v4l2-plane; structure for describing planes is added.
52 Arrays of this structure are passed in the new
53 <structfield>m.planes</structfield> field of &v4l2-buffer;.</para>
54 </listitem>
55 </varlistentry>
56 <varlistentry>
57 <term>&VIDIOC-REQBUFS;</term>
58 <listitem><para>Will allocate multi-planar buffers as requested.</para></listitem>
59 </varlistentry>
60 </variablelist>
61 </section>
62</section>
diff --git a/Documentation/DocBook/v4l/subdev-formats.xml b/Documentation/DocBook/v4l/subdev-formats.xml
new file mode 100644
index 000000000000..7041127d6dfc
--- /dev/null
+++ b/Documentation/DocBook/v4l/subdev-formats.xml
@@ -0,0 +1,2467 @@
1<section id="v4l2-mbus-format">
2 <title>Media Bus Formats</title>
3
4 <table pgwide="1" frame="none" id="v4l2-mbus-framefmt">
5 <title>struct <structname>v4l2_mbus_framefmt</structname></title>
6 <tgroup cols="3">
7 &cs-str;
8 <tbody valign="top">
9 <row>
10 <entry>__u32</entry>
11 <entry><structfield>width</structfield></entry>
12 <entry>Image width, in pixels.</entry>
13 </row>
14 <row>
15 <entry>__u32</entry>
16 <entry><structfield>height</structfield></entry>
17 <entry>Image height, in pixels.</entry>
18 </row>
19 <row>
20 <entry>__u32</entry>
21 <entry><structfield>code</structfield></entry>
22 <entry>Format code, from &v4l2-mbus-pixelcode;.</entry>
23 </row>
24 <row>
25 <entry>__u32</entry>
26 <entry><structfield>field</structfield></entry>
27 <entry>Field order, from &v4l2-field;. See
28 <xref linkend="field-order" /> for details.</entry>
29 </row>
30 <row>
31 <entry>__u32</entry>
32 <entry><structfield>colorspace</structfield></entry>
33 <entry>Image colorspace, from &v4l2-colorspace;. See
34 <xref linkend="colorspaces" /> for details.</entry>
35 </row>
36 <row>
37 <entry>__u32</entry>
38 <entry><structfield>reserved</structfield>[7]</entry>
39 <entry>Reserved for future extensions. Applications and drivers must
40 set the array to zero.</entry>
41 </row>
42 </tbody>
43 </tgroup>
44 </table>
45
46 <section id="v4l2-mbus-pixelcode">
47 <title>Media Bus Pixel Codes</title>
48
49 <para>The media bus pixel codes describe image formats as flowing over
50 physical busses (both between separate physical components and inside SoC
51 devices). This should not be confused with the V4L2 pixel formats that
52 describe, using four character codes, image formats as stored in memory.
53 </para>
54
55 <para>While there is a relationship between image formats on busses and
56 image formats in memory (a raw Bayer image won't be magically converted to
57 JPEG just by storing it to memory), there is no one-to-one correspondance
58 between them.</para>
59
60 <section>
61 <title>Packed RGB Formats</title>
62
63 <para>Those formats transfer pixel data as red, green and blue components.
64 The format code is made of the following information.
65 <itemizedlist>
66 <listitem><para>The red, green and blue components order code, as encoded in a
67 pixel sample. Possible values are RGB and BGR.</para></listitem>
68 <listitem><para>The number of bits per component, for each component. The values
69 can be different for all components. Common values are 555 and 565.</para>
70 </listitem>
71 <listitem><para>The number of bus samples per pixel. Pixels that are wider than
72 the bus width must be transferred in multiple samples. Common values are
73 1 and 2.</para></listitem>
74 <listitem><para>The bus width.</para></listitem>
75 <listitem><para>For formats where the total number of bits per pixel is smaller
76 than the number of bus samples per pixel times the bus width, a padding
77 value stating if the bytes are padded in their most high order bits
78 (PADHI) or low order bits (PADLO).</para></listitem>
79 <listitem><para>For formats where the number of bus samples per pixel is larger
80 than 1, an endianness value stating if the pixel is transferred MSB first
81 (BE) or LSB first (LE).</para></listitem>
82 </itemizedlist>
83 </para>
84
85 <para>For instance, a format where pixels are encoded as 5-bits red, 5-bits
86 green and 5-bit blue values padded on the high bit, transferred as 2 8-bit
87 samples per pixel with the most significant bits (padding, red and half of
88 the green value) transferred first will be named
89 <constant>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</constant>.
90 </para>
91
92 <para>The following tables list existing packet RGB formats.</para>
93
94 <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-rgb">
95 <title>RGB formats</title>
96 <tgroup cols="11">
97 <colspec colname="id" align="left" />
98 <colspec colname="code" align="center"/>
99 <colspec colname="bit" />
100 <colspec colnum="4" colname="b07" align="center" />
101 <colspec colnum="5" colname="b06" align="center" />
102 <colspec colnum="6" colname="b05" align="center" />
103 <colspec colnum="7" colname="b04" align="center" />
104 <colspec colnum="8" colname="b03" align="center" />
105 <colspec colnum="9" colname="b02" align="center" />
106 <colspec colnum="10" colname="b01" align="center" />
107 <colspec colnum="11" colname="b00" align="center" />
108 <spanspec namest="b07" nameend="b00" spanname="b0" />
109 <thead>
110 <row>
111 <entry>Identifier</entry>
112 <entry>Code</entry>
113 <entry></entry>
114 <entry spanname="b0">Data organization</entry>
115 </row>
116 <row>
117 <entry></entry>
118 <entry></entry>
119 <entry>Bit</entry>
120 <entry>7</entry>
121 <entry>6</entry>
122 <entry>5</entry>
123 <entry>4</entry>
124 <entry>3</entry>
125 <entry>2</entry>
126 <entry>1</entry>
127 <entry>0</entry>
128 </row>
129 </thead>
130 <tbody valign="top">
131 <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-BE">
132 <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_BE</entry>
133 <entry>0x1001</entry>
134 <entry></entry>
135 <entry>0</entry>
136 <entry>0</entry>
137 <entry>0</entry>
138 <entry>0</entry>
139 <entry>r<subscript>3</subscript></entry>
140 <entry>r<subscript>2</subscript></entry>
141 <entry>r<subscript>1</subscript></entry>
142 <entry>r<subscript>0</subscript></entry>
143 </row>
144 <row>
145 <entry></entry>
146 <entry></entry>
147 <entry></entry>
148 <entry>g<subscript>3</subscript></entry>
149 <entry>g<subscript>2</subscript></entry>
150 <entry>g<subscript>1</subscript></entry>
151 <entry>g<subscript>0</subscript></entry>
152 <entry>b<subscript>3</subscript></entry>
153 <entry>b<subscript>2</subscript></entry>
154 <entry>b<subscript>1</subscript></entry>
155 <entry>b<subscript>0</subscript></entry>
156 </row>
157 <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-LE">
158 <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_LE</entry>
159 <entry>0x1002</entry>
160 <entry></entry>
161 <entry>g<subscript>3</subscript></entry>
162 <entry>g<subscript>2</subscript></entry>
163 <entry>g<subscript>1</subscript></entry>
164 <entry>g<subscript>0</subscript></entry>
165 <entry>b<subscript>3</subscript></entry>
166 <entry>b<subscript>2</subscript></entry>
167 <entry>b<subscript>1</subscript></entry>
168 <entry>b<subscript>0</subscript></entry>
169 </row>
170 <row>
171 <entry></entry>
172 <entry></entry>
173 <entry></entry>
174 <entry>0</entry>
175 <entry>0</entry>
176 <entry>0</entry>
177 <entry>0</entry>
178 <entry>r<subscript>3</subscript></entry>
179 <entry>r<subscript>2</subscript></entry>
180 <entry>r<subscript>1</subscript></entry>
181 <entry>r<subscript>0</subscript></entry>
182 </row>
183 <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-BE">
184 <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</entry>
185 <entry>0x1003</entry>
186 <entry></entry>
187 <entry>0</entry>
188 <entry>r<subscript>4</subscript></entry>
189 <entry>r<subscript>3</subscript></entry>
190 <entry>r<subscript>2</subscript></entry>
191 <entry>r<subscript>1</subscript></entry>
192 <entry>r<subscript>0</subscript></entry>
193 <entry>g<subscript>4</subscript></entry>
194 <entry>g<subscript>3</subscript></entry>
195 </row>
196 <row>
197 <entry></entry>
198 <entry></entry>
199 <entry></entry>
200 <entry>g<subscript>2</subscript></entry>
201 <entry>g<subscript>1</subscript></entry>
202 <entry>g<subscript>0</subscript></entry>
203 <entry>b<subscript>4</subscript></entry>
204 <entry>b<subscript>3</subscript></entry>
205 <entry>b<subscript>2</subscript></entry>
206 <entry>b<subscript>1</subscript></entry>
207 <entry>b<subscript>0</subscript></entry>
208 </row>
209 <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-LE">
210 <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_LE</entry>
211 <entry>0x1004</entry>
212 <entry></entry>
213 <entry>g<subscript>2</subscript></entry>
214 <entry>g<subscript>1</subscript></entry>
215 <entry>g<subscript>0</subscript></entry>
216 <entry>b<subscript>4</subscript></entry>
217 <entry>b<subscript>3</subscript></entry>
218 <entry>b<subscript>2</subscript></entry>
219 <entry>b<subscript>1</subscript></entry>
220 <entry>b<subscript>0</subscript></entry>
221 </row>
222 <row>
223 <entry></entry>
224 <entry></entry>
225 <entry></entry>
226 <entry>0</entry>
227 <entry>r<subscript>4</subscript></entry>
228 <entry>r<subscript>3</subscript></entry>
229 <entry>r<subscript>2</subscript></entry>
230 <entry>r<subscript>1</subscript></entry>
231 <entry>r<subscript>0</subscript></entry>
232 <entry>g<subscript>4</subscript></entry>
233 <entry>g<subscript>3</subscript></entry>
234 </row>
235 <row id="V4L2-MBUS-FMT-BGR565-2X8-BE">
236 <entry>V4L2_MBUS_FMT_BGR565_2X8_BE</entry>
237 <entry>0x1005</entry>
238 <entry></entry>
239 <entry>b<subscript>4</subscript></entry>
240 <entry>b<subscript>3</subscript></entry>
241 <entry>b<subscript>2</subscript></entry>
242 <entry>b<subscript>1</subscript></entry>
243 <entry>b<subscript>0</subscript></entry>
244 <entry>g<subscript>5</subscript></entry>
245 <entry>g<subscript>4</subscript></entry>
246 <entry>g<subscript>3</subscript></entry>
247 </row>
248 <row>
249 <entry></entry>
250 <entry></entry>
251 <entry></entry>
252 <entry>g<subscript>2</subscript></entry>
253 <entry>g<subscript>1</subscript></entry>
254 <entry>g<subscript>0</subscript></entry>
255 <entry>r<subscript>4</subscript></entry>
256 <entry>r<subscript>3</subscript></entry>
257 <entry>r<subscript>2</subscript></entry>
258 <entry>r<subscript>1</subscript></entry>
259 <entry>r<subscript>0</subscript></entry>
260 </row>
261 <row id="V4L2-MBUS-FMT-BGR565-2X8-LE">
262 <entry>V4L2_MBUS_FMT_BGR565_2X8_LE</entry>
263 <entry>0x1006</entry>
264 <entry></entry>
265 <entry>g<subscript>2</subscript></entry>
266 <entry>g<subscript>1</subscript></entry>
267 <entry>g<subscript>0</subscript></entry>
268 <entry>r<subscript>4</subscript></entry>
269 <entry>r<subscript>3</subscript></entry>
270 <entry>r<subscript>2</subscript></entry>
271 <entry>r<subscript>1</subscript></entry>
272 <entry>r<subscript>0</subscript></entry>
273 </row>
274 <row>
275 <entry></entry>
276 <entry></entry>
277 <entry></entry>
278 <entry>b<subscript>4</subscript></entry>
279 <entry>b<subscript>3</subscript></entry>
280 <entry>b<subscript>2</subscript></entry>
281 <entry>b<subscript>1</subscript></entry>
282 <entry>b<subscript>0</subscript></entry>
283 <entry>g<subscript>5</subscript></entry>
284 <entry>g<subscript>4</subscript></entry>
285 <entry>g<subscript>3</subscript></entry>
286 </row>
287 <row id="V4L2-MBUS-FMT-RGB565-2X8-BE">
288 <entry>V4L2_MBUS_FMT_RGB565_2X8_BE</entry>
289 <entry>0x1007</entry>
290 <entry></entry>
291 <entry>r<subscript>4</subscript></entry>
292 <entry>r<subscript>3</subscript></entry>
293 <entry>r<subscript>2</subscript></entry>
294 <entry>r<subscript>1</subscript></entry>
295 <entry>r<subscript>0</subscript></entry>
296 <entry>g<subscript>5</subscript></entry>
297 <entry>g<subscript>4</subscript></entry>
298 <entry>g<subscript>3</subscript></entry>
299 </row>
300 <row>
301 <entry></entry>
302 <entry></entry>
303 <entry></entry>
304 <entry>g<subscript>2</subscript></entry>
305 <entry>g<subscript>1</subscript></entry>
306 <entry>g<subscript>0</subscript></entry>
307 <entry>b<subscript>4</subscript></entry>
308 <entry>b<subscript>3</subscript></entry>
309 <entry>b<subscript>2</subscript></entry>
310 <entry>b<subscript>1</subscript></entry>
311 <entry>b<subscript>0</subscript></entry>
312 </row>
313 <row id="V4L2-MBUS-FMT-RGB565-2X8-LE">
314 <entry>V4L2_MBUS_FMT_RGB565_2X8_LE</entry>
315 <entry>0x1008</entry>
316 <entry></entry>
317 <entry>g<subscript>2</subscript></entry>
318 <entry>g<subscript>1</subscript></entry>
319 <entry>g<subscript>0</subscript></entry>
320 <entry>b<subscript>4</subscript></entry>
321 <entry>b<subscript>3</subscript></entry>
322 <entry>b<subscript>2</subscript></entry>
323 <entry>b<subscript>1</subscript></entry>
324 <entry>b<subscript>0</subscript></entry>
325 </row>
326 <row>
327 <entry></entry>
328 <entry></entry>
329 <entry></entry>
330 <entry>r<subscript>4</subscript></entry>
331 <entry>r<subscript>3</subscript></entry>
332 <entry>r<subscript>2</subscript></entry>
333 <entry>r<subscript>1</subscript></entry>
334 <entry>r<subscript>0</subscript></entry>
335 <entry>g<subscript>5</subscript></entry>
336 <entry>g<subscript>4</subscript></entry>
337 <entry>g<subscript>3</subscript></entry>
338 </row>
339 </tbody>
340 </tgroup>
341 </table>
342 </section>
343
344 <section>
345 <title>Bayer Formats</title>
346
347 <para>Those formats transfer pixel data as red, green and blue components.
348 The format code is made of the following information.
349 <itemizedlist>
350 <listitem><para>The red, green and blue components order code, as encoded in a
351 pixel sample. The possible values are shown in <xref
352 linkend="bayer-patterns" />.</para></listitem>
353 <listitem><para>The number of bits per pixel component. All components are
354 transferred on the same number of bits. Common values are 8, 10 and 12.</para>
355 </listitem>
356 <listitem><para>If the pixel components are DPCM-compressed, a mention of the
357 DPCM compression and the number of bits per compressed pixel component.</para>
358 </listitem>
359 <listitem><para>The number of bus samples per pixel. Pixels that are wider than
360 the bus width must be transferred in multiple samples. Common values are
361 1 and 2.</para></listitem>
362 <listitem><para>The bus width.</para></listitem>
363 <listitem><para>For formats where the total number of bits per pixel is smaller
364 than the number of bus samples per pixel times the bus width, a padding
365 value stating if the bytes are padded in their most high order bits
366 (PADHI) or low order bits (PADLO).</para></listitem>
367 <listitem><para>For formats where the number of bus samples per pixel is larger
368 than 1, an endianness value stating if the pixel is transferred MSB first
369 (BE) or LSB first (LE).</para></listitem>
370 </itemizedlist>
371 </para>
372
373 <para>For instance, a format with uncompressed 10-bit Bayer components
374 arranged in a red, green, green, blue pattern transferred as 2 8-bit
375 samples per pixel with the least significant bits transferred first will
376 be named <constant>V4L2_MBUS_FMT_SRGGB10_2X8_PADHI_LE</constant>.
377 </para>
378
379 <figure id="bayer-patterns">
380 <title>Bayer Patterns</title>
381 <mediaobject>
382 <imageobject>
383 <imagedata fileref="bayer.pdf" format="PS" />
384 </imageobject>
385 <imageobject>
386 <imagedata fileref="bayer.png" format="PNG" />
387 </imageobject>
388 <textobject>
389 <phrase>Bayer filter color patterns</phrase>
390 </textobject>
391 </mediaobject>
392 </figure>
393
394 <para>The following table lists existing packet Bayer formats. The data
395 organization is given as an example for the first pixel only.</para>
396
397 <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-bayer">
398 <title>Bayer Formats</title>
399 <tgroup cols="15">
400 <colspec colname="id" align="left" />
401 <colspec colname="code" align="center"/>
402 <colspec colname="bit" />
403 <colspec colnum="4" colname="b11" align="center" />
404 <colspec colnum="5" colname="b10" align="center" />
405 <colspec colnum="6" colname="b09" align="center" />
406 <colspec colnum="7" colname="b08" align="center" />
407 <colspec colnum="8" colname="b07" align="center" />
408 <colspec colnum="9" colname="b06" align="center" />
409 <colspec colnum="10" colname="b05" align="center" />
410 <colspec colnum="11" colname="b04" align="center" />
411 <colspec colnum="12" colname="b03" align="center" />
412 <colspec colnum="13" colname="b02" align="center" />
413 <colspec colnum="14" colname="b01" align="center" />
414 <colspec colnum="15" colname="b00" align="center" />
415 <spanspec namest="b11" nameend="b00" spanname="b0" />
416 <thead>
417 <row>
418 <entry>Identifier</entry>
419 <entry>Code</entry>
420 <entry></entry>
421 <entry spanname="b0">Data organization</entry>
422 </row>
423 <row>
424 <entry></entry>
425 <entry></entry>
426 <entry>Bit</entry>
427 <entry>11</entry>
428 <entry>10</entry>
429 <entry>9</entry>
430 <entry>8</entry>
431 <entry>7</entry>
432 <entry>6</entry>
433 <entry>5</entry>
434 <entry>4</entry>
435 <entry>3</entry>
436 <entry>2</entry>
437 <entry>1</entry>
438 <entry>0</entry>
439 </row>
440 </thead>
441 <tbody valign="top">
442 <row id="V4L2-MBUS-FMT-SBGGR8-1X8">
443 <entry>V4L2_MBUS_FMT_SBGGR8_1X8</entry>
444 <entry>0x3001</entry>
445 <entry></entry>
446 <entry>-</entry>
447 <entry>-</entry>
448 <entry>-</entry>
449 <entry>-</entry>
450 <entry>b<subscript>7</subscript></entry>
451 <entry>b<subscript>6</subscript></entry>
452 <entry>b<subscript>5</subscript></entry>
453 <entry>b<subscript>4</subscript></entry>
454 <entry>b<subscript>3</subscript></entry>
455 <entry>b<subscript>2</subscript></entry>
456 <entry>b<subscript>1</subscript></entry>
457 <entry>b<subscript>0</subscript></entry>
458 </row>
459 <row id="V4L2-MBUS-FMT-SGRBG8-1X8">
460 <entry>V4L2_MBUS_FMT_SGRBG8_1X8</entry>
461 <entry>0x3002</entry>
462 <entry></entry>
463 <entry>-</entry>
464 <entry>-</entry>
465 <entry>-</entry>
466 <entry>-</entry>
467 <entry>g<subscript>7</subscript></entry>
468 <entry>g<subscript>6</subscript></entry>
469 <entry>g<subscript>5</subscript></entry>
470 <entry>g<subscript>4</subscript></entry>
471 <entry>g<subscript>3</subscript></entry>
472 <entry>g<subscript>2</subscript></entry>
473 <entry>g<subscript>1</subscript></entry>
474 <entry>g<subscript>0</subscript></entry>
475 </row>
476 <row id="V4L2-MBUS-FMT-SBGGR10-DPCM8-1X8">
477 <entry>V4L2_MBUS_FMT_SBGGR10_DPCM8_1X8</entry>
478 <entry>0x300b</entry>
479 <entry></entry>
480 <entry>-</entry>
481 <entry>-</entry>
482 <entry>-</entry>
483 <entry>-</entry>
484 <entry>b<subscript>7</subscript></entry>
485 <entry>b<subscript>6</subscript></entry>
486 <entry>b<subscript>5</subscript></entry>
487 <entry>b<subscript>4</subscript></entry>
488 <entry>b<subscript>3</subscript></entry>
489 <entry>b<subscript>2</subscript></entry>
490 <entry>b<subscript>1</subscript></entry>
491 <entry>b<subscript>0</subscript></entry>
492 </row>
493 <row id="V4L2-MBUS-FMT-SGBRG10-DPCM8-1X8">
494 <entry>V4L2_MBUS_FMT_SGBRG10_DPCM8_1X8</entry>
495 <entry>0x300c</entry>
496 <entry></entry>
497 <entry>-</entry>
498 <entry>-</entry>
499 <entry>-</entry>
500 <entry>-</entry>
501 <entry>g<subscript>7</subscript></entry>
502 <entry>g<subscript>6</subscript></entry>
503 <entry>g<subscript>5</subscript></entry>
504 <entry>g<subscript>4</subscript></entry>
505 <entry>g<subscript>3</subscript></entry>
506 <entry>g<subscript>2</subscript></entry>
507 <entry>g<subscript>1</subscript></entry>
508 <entry>g<subscript>0</subscript></entry>
509 </row>
510 <row id="V4L2-MBUS-FMT-SGRBG10-DPCM8-1X8">
511 <entry>V4L2_MBUS_FMT_SGRBG10_DPCM8_1X8</entry>
512 <entry>0x3009</entry>
513 <entry></entry>
514 <entry>-</entry>
515 <entry>-</entry>
516 <entry>-</entry>
517 <entry>-</entry>
518 <entry>g<subscript>7</subscript></entry>
519 <entry>g<subscript>6</subscript></entry>
520 <entry>g<subscript>5</subscript></entry>
521 <entry>g<subscript>4</subscript></entry>
522 <entry>g<subscript>3</subscript></entry>
523 <entry>g<subscript>2</subscript></entry>
524 <entry>g<subscript>1</subscript></entry>
525 <entry>g<subscript>0</subscript></entry>
526 </row>
527 <row id="V4L2-MBUS-FMT-SRGGB10-DPCM8-1X8">
528 <entry>V4L2_MBUS_FMT_SRGGB10_DPCM8_1X8</entry>
529 <entry>0x300d</entry>
530 <entry></entry>
531 <entry>-</entry>
532 <entry>-</entry>
533 <entry>-</entry>
534 <entry>-</entry>
535 <entry>r<subscript>7</subscript></entry>
536 <entry>r<subscript>6</subscript></entry>
537 <entry>r<subscript>5</subscript></entry>
538 <entry>r<subscript>4</subscript></entry>
539 <entry>r<subscript>3</subscript></entry>
540 <entry>r<subscript>2</subscript></entry>
541 <entry>r<subscript>1</subscript></entry>
542 <entry>r<subscript>0</subscript></entry>
543 </row>
544 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-BE">
545 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_BE</entry>
546 <entry>0x3003</entry>
547 <entry></entry>
548 <entry>-</entry>
549 <entry>-</entry>
550 <entry>-</entry>
551 <entry>-</entry>
552 <entry>0</entry>
553 <entry>0</entry>
554 <entry>0</entry>
555 <entry>0</entry>
556 <entry>0</entry>
557 <entry>0</entry>
558 <entry>b<subscript>9</subscript></entry>
559 <entry>b<subscript>8</subscript></entry>
560 </row>
561 <row>
562 <entry></entry>
563 <entry></entry>
564 <entry></entry>
565 <entry>-</entry>
566 <entry>-</entry>
567 <entry>-</entry>
568 <entry>-</entry>
569 <entry>b<subscript>7</subscript></entry>
570 <entry>b<subscript>6</subscript></entry>
571 <entry>b<subscript>5</subscript></entry>
572 <entry>b<subscript>4</subscript></entry>
573 <entry>b<subscript>3</subscript></entry>
574 <entry>b<subscript>2</subscript></entry>
575 <entry>b<subscript>1</subscript></entry>
576 <entry>b<subscript>0</subscript></entry>
577 </row>
578 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-LE">
579 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_LE</entry>
580 <entry>0x3004</entry>
581 <entry></entry>
582 <entry>-</entry>
583 <entry>-</entry>
584 <entry>-</entry>
585 <entry>-</entry>
586 <entry>b<subscript>7</subscript></entry>
587 <entry>b<subscript>6</subscript></entry>
588 <entry>b<subscript>5</subscript></entry>
589 <entry>b<subscript>4</subscript></entry>
590 <entry>b<subscript>3</subscript></entry>
591 <entry>b<subscript>2</subscript></entry>
592 <entry>b<subscript>1</subscript></entry>
593 <entry>b<subscript>0</subscript></entry>
594 </row>
595 <row>
596 <entry></entry>
597 <entry></entry>
598 <entry></entry>
599 <entry>-</entry>
600 <entry>-</entry>
601 <entry>-</entry>
602 <entry>-</entry>
603 <entry>0</entry>
604 <entry>0</entry>
605 <entry>0</entry>
606 <entry>0</entry>
607 <entry>0</entry>
608 <entry>0</entry>
609 <entry>b<subscript>9</subscript></entry>
610 <entry>b<subscript>8</subscript></entry>
611 </row>
612 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-BE">
613 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_BE</entry>
614 <entry>0x3005</entry>
615 <entry></entry>
616 <entry>-</entry>
617 <entry>-</entry>
618 <entry>-</entry>
619 <entry>-</entry>
620 <entry>b<subscript>9</subscript></entry>
621 <entry>b<subscript>8</subscript></entry>
622 <entry>b<subscript>7</subscript></entry>
623 <entry>b<subscript>6</subscript></entry>
624 <entry>b<subscript>5</subscript></entry>
625 <entry>b<subscript>4</subscript></entry>
626 <entry>b<subscript>3</subscript></entry>
627 <entry>b<subscript>2</subscript></entry>
628 </row>
629 <row>
630 <entry></entry>
631 <entry></entry>
632 <entry></entry>
633 <entry>-</entry>
634 <entry>-</entry>
635 <entry>-</entry>
636 <entry>-</entry>
637 <entry>b<subscript>1</subscript></entry>
638 <entry>b<subscript>0</subscript></entry>
639 <entry>0</entry>
640 <entry>0</entry>
641 <entry>0</entry>
642 <entry>0</entry>
643 <entry>0</entry>
644 <entry>0</entry>
645 </row>
646 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-LE">
647 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_LE</entry>
648 <entry>0x3006</entry>
649 <entry></entry>
650 <entry>-</entry>
651 <entry>-</entry>
652 <entry>-</entry>
653 <entry>-</entry>
654 <entry>b<subscript>1</subscript></entry>
655 <entry>b<subscript>0</subscript></entry>
656 <entry>0</entry>
657 <entry>0</entry>
658 <entry>0</entry>
659 <entry>0</entry>
660 <entry>0</entry>
661 <entry>0</entry>
662 </row>
663 <row>
664 <entry></entry>
665 <entry></entry>
666 <entry></entry>
667 <entry>-</entry>
668 <entry>-</entry>
669 <entry>-</entry>
670 <entry>-</entry>
671 <entry>b<subscript>9</subscript></entry>
672 <entry>b<subscript>8</subscript></entry>
673 <entry>b<subscript>7</subscript></entry>
674 <entry>b<subscript>6</subscript></entry>
675 <entry>b<subscript>5</subscript></entry>
676 <entry>b<subscript>4</subscript></entry>
677 <entry>b<subscript>3</subscript></entry>
678 <entry>b<subscript>2</subscript></entry>
679 </row>
680 <row id="V4L2-MBUS-FMT-SBGGR10-1X10">
681 <entry>V4L2_MBUS_FMT_SBGGR10_1X10</entry>
682 <entry>0x3007</entry>
683 <entry></entry>
684 <entry>-</entry>
685 <entry>-</entry>
686 <entry>b<subscript>9</subscript></entry>
687 <entry>b<subscript>8</subscript></entry>
688 <entry>b<subscript>7</subscript></entry>
689 <entry>b<subscript>6</subscript></entry>
690 <entry>b<subscript>5</subscript></entry>
691 <entry>b<subscript>4</subscript></entry>
692 <entry>b<subscript>3</subscript></entry>
693 <entry>b<subscript>2</subscript></entry>
694 <entry>b<subscript>1</subscript></entry>
695 <entry>b<subscript>0</subscript></entry>
696 </row>
697 <row id="V4L2-MBUS-FMT-SGBRG10-1X10">
698 <entry>V4L2_MBUS_FMT_SGBRG10_1X10</entry>
699 <entry>0x300e</entry>
700 <entry></entry>
701 <entry>-</entry>
702 <entry>-</entry>
703 <entry>g<subscript>9</subscript></entry>
704 <entry>g<subscript>8</subscript></entry>
705 <entry>g<subscript>7</subscript></entry>
706 <entry>g<subscript>6</subscript></entry>
707 <entry>g<subscript>5</subscript></entry>
708 <entry>g<subscript>4</subscript></entry>
709 <entry>g<subscript>3</subscript></entry>
710 <entry>g<subscript>2</subscript></entry>
711 <entry>g<subscript>1</subscript></entry>
712 <entry>g<subscript>0</subscript></entry>
713 </row>
714 <row id="V4L2-MBUS-FMT-SGRBG10-1X10">
715 <entry>V4L2_MBUS_FMT_SGRBG10_1X10</entry>
716 <entry>0x300a</entry>
717 <entry></entry>
718 <entry>-</entry>
719 <entry>-</entry>
720 <entry>g<subscript>9</subscript></entry>
721 <entry>g<subscript>8</subscript></entry>
722 <entry>g<subscript>7</subscript></entry>
723 <entry>g<subscript>6</subscript></entry>
724 <entry>g<subscript>5</subscript></entry>
725 <entry>g<subscript>4</subscript></entry>
726 <entry>g<subscript>3</subscript></entry>
727 <entry>g<subscript>2</subscript></entry>
728 <entry>g<subscript>1</subscript></entry>
729 <entry>g<subscript>0</subscript></entry>
730 </row>
731 <row id="V4L2-MBUS-FMT-SRGGB10-1X10">
732 <entry>V4L2_MBUS_FMT_SRGGB10_1X10</entry>
733 <entry>0x300f</entry>
734 <entry></entry>
735 <entry>-</entry>
736 <entry>-</entry>
737 <entry>r<subscript>9</subscript></entry>
738 <entry>r<subscript>8</subscript></entry>
739 <entry>r<subscript>7</subscript></entry>
740 <entry>r<subscript>6</subscript></entry>
741 <entry>r<subscript>5</subscript></entry>
742 <entry>r<subscript>4</subscript></entry>
743 <entry>r<subscript>3</subscript></entry>
744 <entry>r<subscript>2</subscript></entry>
745 <entry>r<subscript>1</subscript></entry>
746 <entry>r<subscript>0</subscript></entry>
747 </row>
748 <row id="V4L2-MBUS-FMT-SBGGR12-1X12">
749 <entry>V4L2_MBUS_FMT_SBGGR12_1X12</entry>
750 <entry>0x3008</entry>
751 <entry></entry>
752 <entry>b<subscript>11</subscript></entry>
753 <entry>b<subscript>10</subscript></entry>
754 <entry>b<subscript>9</subscript></entry>
755 <entry>b<subscript>8</subscript></entry>
756 <entry>b<subscript>7</subscript></entry>
757 <entry>b<subscript>6</subscript></entry>
758 <entry>b<subscript>5</subscript></entry>
759 <entry>b<subscript>4</subscript></entry>
760 <entry>b<subscript>3</subscript></entry>
761 <entry>b<subscript>2</subscript></entry>
762 <entry>b<subscript>1</subscript></entry>
763 <entry>b<subscript>0</subscript></entry>
764 </row>
765 <row id="V4L2-MBUS-FMT-SGBRG12-1X12">
766 <entry>V4L2_MBUS_FMT_SGBRG12_1X12</entry>
767 <entry>0x3010</entry>
768 <entry></entry>
769 <entry>g<subscript>11</subscript></entry>
770 <entry>g<subscript>10</subscript></entry>
771 <entry>g<subscript>9</subscript></entry>
772 <entry>g<subscript>8</subscript></entry>
773 <entry>g<subscript>7</subscript></entry>
774 <entry>g<subscript>6</subscript></entry>
775 <entry>g<subscript>5</subscript></entry>
776 <entry>g<subscript>4</subscript></entry>
777 <entry>g<subscript>3</subscript></entry>
778 <entry>g<subscript>2</subscript></entry>
779 <entry>g<subscript>1</subscript></entry>
780 <entry>g<subscript>0</subscript></entry>
781 </row>
782 <row id="V4L2-MBUS-FMT-SGRBG12-1X12">
783 <entry>V4L2_MBUS_FMT_SGRBG12_1X12</entry>
784 <entry>0x3011</entry>
785 <entry></entry>
786 <entry>g<subscript>11</subscript></entry>
787 <entry>g<subscript>10</subscript></entry>
788 <entry>g<subscript>9</subscript></entry>
789 <entry>g<subscript>8</subscript></entry>
790 <entry>g<subscript>7</subscript></entry>
791 <entry>g<subscript>6</subscript></entry>
792 <entry>g<subscript>5</subscript></entry>
793 <entry>g<subscript>4</subscript></entry>
794 <entry>g<subscript>3</subscript></entry>
795 <entry>g<subscript>2</subscript></entry>
796 <entry>g<subscript>1</subscript></entry>
797 <entry>g<subscript>0</subscript></entry>
798 </row>
799 <row id="V4L2-MBUS-FMT-SRGGB12-1X12">
800 <entry>V4L2_MBUS_FMT_SRGGB12_1X12</entry>
801 <entry>0x3012</entry>
802 <entry></entry>
803 <entry>r<subscript>11</subscript></entry>
804 <entry>r<subscript>10</subscript></entry>
805 <entry>r<subscript>9</subscript></entry>
806 <entry>r<subscript>8</subscript></entry>
807 <entry>r<subscript>7</subscript></entry>
808 <entry>r<subscript>6</subscript></entry>
809 <entry>r<subscript>5</subscript></entry>
810 <entry>r<subscript>4</subscript></entry>
811 <entry>r<subscript>3</subscript></entry>
812 <entry>r<subscript>2</subscript></entry>
813 <entry>r<subscript>1</subscript></entry>
814 <entry>r<subscript>0</subscript></entry>
815 </row>
816 </tbody>
817 </tgroup>
818 </table>
819 </section>
820
821 <section>
822 <title>Packed YUV Formats</title>
823
824 <para>Those data formats transfer pixel data as (possibly downsampled) Y, U
825 and V components. The format code is made of the following information.
826 <itemizedlist>
827 <listitem><para>The Y, U and V components order code, as transferred on the
828 bus. Possible values are YUYV, UYVY, YVYU and VYUY.</para></listitem>
829 <listitem><para>The number of bits per pixel component. All components are
830 transferred on the same number of bits. Common values are 8, 10 and 12.</para>
831 </listitem>
832 <listitem><para>The number of bus samples per pixel. Pixels that are wider than
833 the bus width must be transferred in multiple samples. Common values are
834 1, 1.5 (encoded as 1_5) and 2.</para></listitem>
835 <listitem><para>The bus width. When the bus width is larger than the number of
836 bits per pixel component, several components are packed in a single bus
837 sample. The components are ordered as specified by the order code, with
838 components on the left of the code transferred in the high order bits.
839 Common values are 8 and 16.</para>
840 </listitem>
841 </itemizedlist>
842 </para>
843
844 <para>For instance, a format where pixels are encoded as 8-bit YUV values
845 downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the
846 U, Y, V, Y order will be named <constant>V4L2_MBUS_FMT_UYVY8_2X8</constant>.
847 </para>
848
849 <para>The following table lisst existing packet YUV formats.</para>
850
851 <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-yuv8">
852 <title>YUV Formats</title>
853 <tgroup cols="23">
854 <colspec colname="id" align="left" />
855 <colspec colname="code" align="center"/>
856 <colspec colname="bit" />
857 <colspec colnum="4" colname="b19" align="center" />
858 <colspec colnum="5" colname="b18" align="center" />
859 <colspec colnum="6" colname="b17" align="center" />
860 <colspec colnum="7" colname="b16" align="center" />
861 <colspec colnum="8" colname="b15" align="center" />
862 <colspec colnum="9" colname="b14" align="center" />
863 <colspec colnum="10" colname="b13" align="center" />
864 <colspec colnum="11" colname="b12" align="center" />
865 <colspec colnum="12" colname="b11" align="center" />
866 <colspec colnum="13" colname="b10" align="center" />
867 <colspec colnum="14" colname="b09" align="center" />
868 <colspec colnum="15" colname="b08" align="center" />
869 <colspec colnum="16" colname="b07" align="center" />
870 <colspec colnum="17" colname="b06" align="center" />
871 <colspec colnum="18" colname="b05" align="center" />
872 <colspec colnum="19" colname="b04" align="center" />
873 <colspec colnum="20" colname="b03" align="center" />
874 <colspec colnum="21" colname="b02" align="center" />
875 <colspec colnum="22" colname="b01" align="center" />
876 <colspec colnum="23" colname="b00" align="center" />
877 <spanspec namest="b19" nameend="b00" spanname="b0" />
878 <thead>
879 <row>
880 <entry>Identifier</entry>
881 <entry>Code</entry>
882 <entry></entry>
883 <entry spanname="b0">Data organization</entry>
884 </row>
885 <row>
886 <entry></entry>
887 <entry></entry>
888 <entry>Bit</entry>
889 <entry>19</entry>
890 <entry>18</entry>
891 <entry>17</entry>
892 <entry>16</entry>
893 <entry>15</entry>
894 <entry>14</entry>
895 <entry>13</entry>
896 <entry>12</entry>
897 <entry>11</entry>
898 <entry>10</entry>
899 <entry>9</entry>
900 <entry>8</entry>
901 <entry>7</entry>
902 <entry>6</entry>
903 <entry>5</entry>
904 <entry>4</entry>
905 <entry>3</entry>
906 <entry>2</entry>
907 <entry>1</entry>
908 <entry>0</entry>
909 </row>
910 </thead>
911 <tbody valign="top">
912 <row id="V4L2-MBUS-FMT-Y8-1X8">
913 <entry>V4L2_MBUS_FMT_Y8_1X8</entry>
914 <entry>0x2001</entry>
915 <entry></entry>
916 <entry>-</entry>
917 <entry>-</entry>
918 <entry>-</entry>
919 <entry>-</entry>
920 <entry>-</entry>
921 <entry>-</entry>
922 <entry>-</entry>
923 <entry>-</entry>
924 <entry>-</entry>
925 <entry>-</entry>
926 <entry>-</entry>
927 <entry>-</entry>
928 <entry>y<subscript>7</subscript></entry>
929 <entry>y<subscript>6</subscript></entry>
930 <entry>y<subscript>5</subscript></entry>
931 <entry>y<subscript>4</subscript></entry>
932 <entry>y<subscript>3</subscript></entry>
933 <entry>y<subscript>2</subscript></entry>
934 <entry>y<subscript>1</subscript></entry>
935 <entry>y<subscript>0</subscript></entry>
936 </row>
937 <row id="V4L2-MBUS-FMT-UYVY8-1_5X8">
938 <entry>V4L2_MBUS_FMT_UYVY8_1_5X8</entry>
939 <entry>0x2002</entry>
940 <entry></entry>
941 <entry>-</entry>
942 <entry>-</entry>
943 <entry>-</entry>
944 <entry>-</entry>
945 <entry>-</entry>
946 <entry>-</entry>
947 <entry>-</entry>
948 <entry>-</entry>
949 <entry>-</entry>
950 <entry>-</entry>
951 <entry>-</entry>
952 <entry>-</entry>
953 <entry>u<subscript>7</subscript></entry>
954 <entry>u<subscript>6</subscript></entry>
955 <entry>u<subscript>5</subscript></entry>
956 <entry>u<subscript>4</subscript></entry>
957 <entry>u<subscript>3</subscript></entry>
958 <entry>u<subscript>2</subscript></entry>
959 <entry>u<subscript>1</subscript></entry>
960 <entry>u<subscript>0</subscript></entry>
961 </row>
962 <row>
963 <entry></entry>
964 <entry></entry>
965 <entry></entry>
966 <entry>-</entry>
967 <entry>-</entry>
968 <entry>-</entry>
969 <entry>-</entry>
970 <entry>-</entry>
971 <entry>-</entry>
972 <entry>-</entry>
973 <entry>-</entry>
974 <entry>-</entry>
975 <entry>-</entry>
976 <entry>-</entry>
977 <entry>-</entry>
978 <entry>y<subscript>7</subscript></entry>
979 <entry>y<subscript>6</subscript></entry>
980 <entry>y<subscript>5</subscript></entry>
981 <entry>y<subscript>4</subscript></entry>
982 <entry>y<subscript>3</subscript></entry>
983 <entry>y<subscript>2</subscript></entry>
984 <entry>y<subscript>1</subscript></entry>
985 <entry>y<subscript>0</subscript></entry>
986 </row>
987 <row>
988 <entry></entry>
989 <entry></entry>
990 <entry></entry>
991 <entry>-</entry>
992 <entry>-</entry>
993 <entry>-</entry>
994 <entry>-</entry>
995 <entry>-</entry>
996 <entry>-</entry>
997 <entry>-</entry>
998 <entry>-</entry>
999 <entry>-</entry>
1000 <entry>-</entry>
1001 <entry>-</entry>
1002 <entry>-</entry>
1003 <entry>y<subscript>7</subscript></entry>
1004 <entry>y<subscript>6</subscript></entry>
1005 <entry>y<subscript>5</subscript></entry>
1006 <entry>y<subscript>4</subscript></entry>
1007 <entry>y<subscript>3</subscript></entry>
1008 <entry>y<subscript>2</subscript></entry>
1009 <entry>y<subscript>1</subscript></entry>
1010 <entry>y<subscript>0</subscript></entry>
1011 </row>
1012 <row>
1013 <entry></entry>
1014 <entry></entry>
1015 <entry></entry>
1016 <entry>-</entry>
1017 <entry>-</entry>
1018 <entry>-</entry>
1019 <entry>-</entry>
1020 <entry>-</entry>
1021 <entry>-</entry>
1022 <entry>-</entry>
1023 <entry>-</entry>
1024 <entry>-</entry>
1025 <entry>-</entry>
1026 <entry>-</entry>
1027 <entry>-</entry>
1028 <entry>v<subscript>7</subscript></entry>
1029 <entry>v<subscript>6</subscript></entry>
1030 <entry>v<subscript>5</subscript></entry>
1031 <entry>v<subscript>4</subscript></entry>
1032 <entry>v<subscript>3</subscript></entry>
1033 <entry>v<subscript>2</subscript></entry>
1034 <entry>v<subscript>1</subscript></entry>
1035 <entry>v<subscript>0</subscript></entry>
1036 </row>
1037 <row>
1038 <entry></entry>
1039 <entry></entry>
1040 <entry></entry>
1041 <entry>-</entry>
1042 <entry>-</entry>
1043 <entry>-</entry>
1044 <entry>-</entry>
1045 <entry>-</entry>
1046 <entry>-</entry>
1047 <entry>-</entry>
1048 <entry>-</entry>
1049 <entry>-</entry>
1050 <entry>-</entry>
1051 <entry>-</entry>
1052 <entry>-</entry>
1053 <entry>y<subscript>7</subscript></entry>
1054 <entry>y<subscript>6</subscript></entry>
1055 <entry>y<subscript>5</subscript></entry>
1056 <entry>y<subscript>4</subscript></entry>
1057 <entry>y<subscript>3</subscript></entry>
1058 <entry>y<subscript>2</subscript></entry>
1059 <entry>y<subscript>1</subscript></entry>
1060 <entry>y<subscript>0</subscript></entry>
1061 </row>
1062 <row>
1063 <entry></entry>
1064 <entry></entry>
1065 <entry></entry>
1066 <entry>-</entry>
1067 <entry>-</entry>
1068 <entry>-</entry>
1069 <entry>-</entry>
1070 <entry>-</entry>
1071 <entry>-</entry>
1072 <entry>-</entry>
1073 <entry>-</entry>
1074 <entry>-</entry>
1075 <entry>-</entry>
1076 <entry>-</entry>
1077 <entry>-</entry>
1078 <entry>y<subscript>7</subscript></entry>
1079 <entry>y<subscript>6</subscript></entry>
1080 <entry>y<subscript>5</subscript></entry>
1081 <entry>y<subscript>4</subscript></entry>
1082 <entry>y<subscript>3</subscript></entry>
1083 <entry>y<subscript>2</subscript></entry>
1084 <entry>y<subscript>1</subscript></entry>
1085 <entry>y<subscript>0</subscript></entry>
1086 </row>
1087 <row id="V4L2-MBUS-FMT-VYUY8-1_5X8">
1088 <entry>V4L2_MBUS_FMT_VYUY8_1_5X8</entry>
1089 <entry>0x2003</entry>
1090 <entry></entry>
1091 <entry>-</entry>
1092 <entry>-</entry>
1093 <entry>-</entry>
1094 <entry>-</entry>
1095 <entry>-</entry>
1096 <entry>-</entry>
1097 <entry>-</entry>
1098 <entry>-</entry>
1099 <entry>-</entry>
1100 <entry>-</entry>
1101 <entry>-</entry>
1102 <entry>-</entry>
1103 <entry>v<subscript>7</subscript></entry>
1104 <entry>v<subscript>6</subscript></entry>
1105 <entry>v<subscript>5</subscript></entry>
1106 <entry>v<subscript>4</subscript></entry>
1107 <entry>v<subscript>3</subscript></entry>
1108 <entry>v<subscript>2</subscript></entry>
1109 <entry>v<subscript>1</subscript></entry>
1110 <entry>v<subscript>0</subscript></entry>
1111 </row>
1112 <row>
1113 <entry></entry>
1114 <entry></entry>
1115 <entry></entry>
1116 <entry>-</entry>
1117 <entry>-</entry>
1118 <entry>-</entry>
1119 <entry>-</entry>
1120 <entry>-</entry>
1121 <entry>-</entry>
1122 <entry>-</entry>
1123 <entry>-</entry>
1124 <entry>-</entry>
1125 <entry>-</entry>
1126 <entry>-</entry>
1127 <entry>-</entry>
1128 <entry>y<subscript>7</subscript></entry>
1129 <entry>y<subscript>6</subscript></entry>
1130 <entry>y<subscript>5</subscript></entry>
1131 <entry>y<subscript>4</subscript></entry>
1132 <entry>y<subscript>3</subscript></entry>
1133 <entry>y<subscript>2</subscript></entry>
1134 <entry>y<subscript>1</subscript></entry>
1135 <entry>y<subscript>0</subscript></entry>
1136 </row>
1137 <row>
1138 <entry></entry>
1139 <entry></entry>
1140 <entry></entry>
1141 <entry>-</entry>
1142 <entry>-</entry>
1143 <entry>-</entry>
1144 <entry>-</entry>
1145 <entry>-</entry>
1146 <entry>-</entry>
1147 <entry>-</entry>
1148 <entry>-</entry>
1149 <entry>-</entry>
1150 <entry>-</entry>
1151 <entry>-</entry>
1152 <entry>-</entry>
1153 <entry>y<subscript>7</subscript></entry>
1154 <entry>y<subscript>6</subscript></entry>
1155 <entry>y<subscript>5</subscript></entry>
1156 <entry>y<subscript>4</subscript></entry>
1157 <entry>y<subscript>3</subscript></entry>
1158 <entry>y<subscript>2</subscript></entry>
1159 <entry>y<subscript>1</subscript></entry>
1160 <entry>y<subscript>0</subscript></entry>
1161 </row>
1162 <row>
1163 <entry></entry>
1164 <entry></entry>
1165 <entry></entry>
1166 <entry>-</entry>
1167 <entry>-</entry>
1168 <entry>-</entry>
1169 <entry>-</entry>
1170 <entry>-</entry>
1171 <entry>-</entry>
1172 <entry>-</entry>
1173 <entry>-</entry>
1174 <entry>-</entry>
1175 <entry>-</entry>
1176 <entry>-</entry>
1177 <entry>-</entry>
1178 <entry>u<subscript>7</subscript></entry>
1179 <entry>u<subscript>6</subscript></entry>
1180 <entry>u<subscript>5</subscript></entry>
1181 <entry>u<subscript>4</subscript></entry>
1182 <entry>u<subscript>3</subscript></entry>
1183 <entry>u<subscript>2</subscript></entry>
1184 <entry>u<subscript>1</subscript></entry>
1185 <entry>u<subscript>0</subscript></entry>
1186 </row>
1187 <row>
1188 <entry></entry>
1189 <entry></entry>
1190 <entry></entry>
1191 <entry>-</entry>
1192 <entry>-</entry>
1193 <entry>-</entry>
1194 <entry>-</entry>
1195 <entry>-</entry>
1196 <entry>-</entry>
1197 <entry>-</entry>
1198 <entry>-</entry>
1199 <entry>-</entry>
1200 <entry>-</entry>
1201 <entry>-</entry>
1202 <entry>-</entry>
1203 <entry>y<subscript>7</subscript></entry>
1204 <entry>y<subscript>6</subscript></entry>
1205 <entry>y<subscript>5</subscript></entry>
1206 <entry>y<subscript>4</subscript></entry>
1207 <entry>y<subscript>3</subscript></entry>
1208 <entry>y<subscript>2</subscript></entry>
1209 <entry>y<subscript>1</subscript></entry>
1210 <entry>y<subscript>0</subscript></entry>
1211 </row>
1212 <row>
1213 <entry></entry>
1214 <entry></entry>
1215 <entry></entry>
1216 <entry>-</entry>
1217 <entry>-</entry>
1218 <entry>-</entry>
1219 <entry>-</entry>
1220 <entry>-</entry>
1221 <entry>-</entry>
1222 <entry>-</entry>
1223 <entry>-</entry>
1224 <entry>-</entry>
1225 <entry>-</entry>
1226 <entry>-</entry>
1227 <entry>-</entry>
1228 <entry>y<subscript>7</subscript></entry>
1229 <entry>y<subscript>6</subscript></entry>
1230 <entry>y<subscript>5</subscript></entry>
1231 <entry>y<subscript>4</subscript></entry>
1232 <entry>y<subscript>3</subscript></entry>
1233 <entry>y<subscript>2</subscript></entry>
1234 <entry>y<subscript>1</subscript></entry>
1235 <entry>y<subscript>0</subscript></entry>
1236 </row>
1237 <row id="V4L2-MBUS-FMT-YUYV8-1_5X8">
1238 <entry>V4L2_MBUS_FMT_YUYV8_1_5X8</entry>
1239 <entry>0x2004</entry>
1240 <entry></entry>
1241 <entry>-</entry>
1242 <entry>-</entry>
1243 <entry>-</entry>
1244 <entry>-</entry>
1245 <entry>-</entry>
1246 <entry>-</entry>
1247 <entry>-</entry>
1248 <entry>-</entry>
1249 <entry>-</entry>
1250 <entry>-</entry>
1251 <entry>-</entry>
1252 <entry>-</entry>
1253 <entry>y<subscript>7</subscript></entry>
1254 <entry>y<subscript>6</subscript></entry>
1255 <entry>y<subscript>5</subscript></entry>
1256 <entry>y<subscript>4</subscript></entry>
1257 <entry>y<subscript>3</subscript></entry>
1258 <entry>y<subscript>2</subscript></entry>
1259 <entry>y<subscript>1</subscript></entry>
1260 <entry>y<subscript>0</subscript></entry>
1261 </row>
1262 <row>
1263 <entry></entry>
1264 <entry></entry>
1265 <entry></entry>
1266 <entry>-</entry>
1267 <entry>-</entry>
1268 <entry>-</entry>
1269 <entry>-</entry>
1270 <entry>-</entry>
1271 <entry>-</entry>
1272 <entry>-</entry>
1273 <entry>-</entry>
1274 <entry>-</entry>
1275 <entry>-</entry>
1276 <entry>-</entry>
1277 <entry>-</entry>
1278 <entry>y<subscript>7</subscript></entry>
1279 <entry>y<subscript>6</subscript></entry>
1280 <entry>y<subscript>5</subscript></entry>
1281 <entry>y<subscript>4</subscript></entry>
1282 <entry>y<subscript>3</subscript></entry>
1283 <entry>y<subscript>2</subscript></entry>
1284 <entry>y<subscript>1</subscript></entry>
1285 <entry>y<subscript>0</subscript></entry>
1286 </row>
1287 <row>
1288 <entry></entry>
1289 <entry></entry>
1290 <entry></entry>
1291 <entry>-</entry>
1292 <entry>-</entry>
1293 <entry>-</entry>
1294 <entry>-</entry>
1295 <entry>-</entry>
1296 <entry>-</entry>
1297 <entry>-</entry>
1298 <entry>-</entry>
1299 <entry>-</entry>
1300 <entry>-</entry>
1301 <entry>-</entry>
1302 <entry>-</entry>
1303 <entry>u<subscript>7</subscript></entry>
1304 <entry>u<subscript>6</subscript></entry>
1305 <entry>u<subscript>5</subscript></entry>
1306 <entry>u<subscript>4</subscript></entry>
1307 <entry>u<subscript>3</subscript></entry>
1308 <entry>u<subscript>2</subscript></entry>
1309 <entry>u<subscript>1</subscript></entry>
1310 <entry>u<subscript>0</subscript></entry>
1311 </row>
1312 <row>
1313 <entry></entry>
1314 <entry></entry>
1315 <entry></entry>
1316 <entry>-</entry>
1317 <entry>-</entry>
1318 <entry>-</entry>
1319 <entry>-</entry>
1320 <entry>-</entry>
1321 <entry>-</entry>
1322 <entry>-</entry>
1323 <entry>-</entry>
1324 <entry>-</entry>
1325 <entry>-</entry>
1326 <entry>-</entry>
1327 <entry>-</entry>
1328 <entry>y<subscript>7</subscript></entry>
1329 <entry>y<subscript>6</subscript></entry>
1330 <entry>y<subscript>5</subscript></entry>
1331 <entry>y<subscript>4</subscript></entry>
1332 <entry>y<subscript>3</subscript></entry>
1333 <entry>y<subscript>2</subscript></entry>
1334 <entry>y<subscript>1</subscript></entry>
1335 <entry>y<subscript>0</subscript></entry>
1336 </row>
1337 <row>
1338 <entry></entry>
1339 <entry></entry>
1340 <entry></entry>
1341 <entry>-</entry>
1342 <entry>-</entry>
1343 <entry>-</entry>
1344 <entry>-</entry>
1345 <entry>-</entry>
1346 <entry>-</entry>
1347 <entry>-</entry>
1348 <entry>-</entry>
1349 <entry>-</entry>
1350 <entry>-</entry>
1351 <entry>-</entry>
1352 <entry>-</entry>
1353 <entry>y<subscript>7</subscript></entry>
1354 <entry>y<subscript>6</subscript></entry>
1355 <entry>y<subscript>5</subscript></entry>
1356 <entry>y<subscript>4</subscript></entry>
1357 <entry>y<subscript>3</subscript></entry>
1358 <entry>y<subscript>2</subscript></entry>
1359 <entry>y<subscript>1</subscript></entry>
1360 <entry>y<subscript>0</subscript></entry>
1361 </row>
1362 <row>
1363 <entry></entry>
1364 <entry></entry>
1365 <entry></entry>
1366 <entry>-</entry>
1367 <entry>-</entry>
1368 <entry>-</entry>
1369 <entry>-</entry>
1370 <entry>-</entry>
1371 <entry>-</entry>
1372 <entry>-</entry>
1373 <entry>-</entry>
1374 <entry>-</entry>
1375 <entry>-</entry>
1376 <entry>-</entry>
1377 <entry>-</entry>
1378 <entry>v<subscript>7</subscript></entry>
1379 <entry>v<subscript>6</subscript></entry>
1380 <entry>v<subscript>5</subscript></entry>
1381 <entry>v<subscript>4</subscript></entry>
1382 <entry>v<subscript>3</subscript></entry>
1383 <entry>v<subscript>2</subscript></entry>
1384 <entry>v<subscript>1</subscript></entry>
1385 <entry>v<subscript>0</subscript></entry>
1386 </row>
1387 <row id="V4L2-MBUS-FMT-YVYU8-1_5X8">
1388 <entry>V4L2_MBUS_FMT_YVYU8_1_5X8</entry>
1389 <entry>0x2005</entry>
1390 <entry></entry>
1391 <entry>-</entry>
1392 <entry>-</entry>
1393 <entry>-</entry>
1394 <entry>-</entry>
1395 <entry>-</entry>
1396 <entry>-</entry>
1397 <entry>-</entry>
1398 <entry>-</entry>
1399 <entry>-</entry>
1400 <entry>-</entry>
1401 <entry>-</entry>
1402 <entry>-</entry>
1403 <entry>y<subscript>7</subscript></entry>
1404 <entry>y<subscript>6</subscript></entry>
1405 <entry>y<subscript>5</subscript></entry>
1406 <entry>y<subscript>4</subscript></entry>
1407 <entry>y<subscript>3</subscript></entry>
1408 <entry>y<subscript>2</subscript></entry>
1409 <entry>y<subscript>1</subscript></entry>
1410 <entry>y<subscript>0</subscript></entry>
1411 </row>
1412 <row>
1413 <entry></entry>
1414 <entry></entry>
1415 <entry></entry>
1416 <entry>-</entry>
1417 <entry>-</entry>
1418 <entry>-</entry>
1419 <entry>-</entry>
1420 <entry>-</entry>
1421 <entry>-</entry>
1422 <entry>-</entry>
1423 <entry>-</entry>
1424 <entry>-</entry>
1425 <entry>-</entry>
1426 <entry>-</entry>
1427 <entry>-</entry>
1428 <entry>y<subscript>7</subscript></entry>
1429 <entry>y<subscript>6</subscript></entry>
1430 <entry>y<subscript>5</subscript></entry>
1431 <entry>y<subscript>4</subscript></entry>
1432 <entry>y<subscript>3</subscript></entry>
1433 <entry>y<subscript>2</subscript></entry>
1434 <entry>y<subscript>1</subscript></entry>
1435 <entry>y<subscript>0</subscript></entry>
1436 </row>
1437 <row>
1438 <entry></entry>
1439 <entry></entry>
1440 <entry></entry>
1441 <entry>-</entry>
1442 <entry>-</entry>
1443 <entry>-</entry>
1444 <entry>-</entry>
1445 <entry>-</entry>
1446 <entry>-</entry>
1447 <entry>-</entry>
1448 <entry>-</entry>
1449 <entry>-</entry>
1450 <entry>-</entry>
1451 <entry>-</entry>
1452 <entry>-</entry>
1453 <entry>v<subscript>7</subscript></entry>
1454 <entry>v<subscript>6</subscript></entry>
1455 <entry>v<subscript>5</subscript></entry>
1456 <entry>v<subscript>4</subscript></entry>
1457 <entry>v<subscript>3</subscript></entry>
1458 <entry>v<subscript>2</subscript></entry>
1459 <entry>v<subscript>1</subscript></entry>
1460 <entry>v<subscript>0</subscript></entry>
1461 </row>
1462 <row>
1463 <entry></entry>
1464 <entry></entry>
1465 <entry></entry>
1466 <entry>-</entry>
1467 <entry>-</entry>
1468 <entry>-</entry>
1469 <entry>-</entry>
1470 <entry>-</entry>
1471 <entry>-</entry>
1472 <entry>-</entry>
1473 <entry>-</entry>
1474 <entry>-</entry>
1475 <entry>-</entry>
1476 <entry>-</entry>
1477 <entry>-</entry>
1478 <entry>y<subscript>7</subscript></entry>
1479 <entry>y<subscript>6</subscript></entry>
1480 <entry>y<subscript>5</subscript></entry>
1481 <entry>y<subscript>4</subscript></entry>
1482 <entry>y<subscript>3</subscript></entry>
1483 <entry>y<subscript>2</subscript></entry>
1484 <entry>y<subscript>1</subscript></entry>
1485 <entry>y<subscript>0</subscript></entry>
1486 </row>
1487 <row>
1488 <entry></entry>
1489 <entry></entry>
1490 <entry></entry>
1491 <entry>-</entry>
1492 <entry>-</entry>
1493 <entry>-</entry>
1494 <entry>-</entry>
1495 <entry>-</entry>
1496 <entry>-</entry>
1497 <entry>-</entry>
1498 <entry>-</entry>
1499 <entry>-</entry>
1500 <entry>-</entry>
1501 <entry>-</entry>
1502 <entry>-</entry>
1503 <entry>y<subscript>7</subscript></entry>
1504 <entry>y<subscript>6</subscript></entry>
1505 <entry>y<subscript>5</subscript></entry>
1506 <entry>y<subscript>4</subscript></entry>
1507 <entry>y<subscript>3</subscript></entry>
1508 <entry>y<subscript>2</subscript></entry>
1509 <entry>y<subscript>1</subscript></entry>
1510 <entry>y<subscript>0</subscript></entry>
1511 </row>
1512 <row>
1513 <entry></entry>
1514 <entry></entry>
1515 <entry></entry>
1516 <entry>-</entry>
1517 <entry>-</entry>
1518 <entry>-</entry>
1519 <entry>-</entry>
1520 <entry>-</entry>
1521 <entry>-</entry>
1522 <entry>-</entry>
1523 <entry>-</entry>
1524 <entry>-</entry>
1525 <entry>-</entry>
1526 <entry>-</entry>
1527 <entry>-</entry>
1528 <entry>u<subscript>7</subscript></entry>
1529 <entry>u<subscript>6</subscript></entry>
1530 <entry>u<subscript>5</subscript></entry>
1531 <entry>u<subscript>4</subscript></entry>
1532 <entry>u<subscript>3</subscript></entry>
1533 <entry>u<subscript>2</subscript></entry>
1534 <entry>u<subscript>1</subscript></entry>
1535 <entry>u<subscript>0</subscript></entry>
1536 </row>
1537 <row id="V4L2-MBUS-FMT-UYVY8-2X8">
1538 <entry>V4L2_MBUS_FMT_UYVY8_2X8</entry>
1539 <entry>0x2006</entry>
1540 <entry></entry>
1541 <entry>-</entry>
1542 <entry>-</entry>
1543 <entry>-</entry>
1544 <entry>-</entry>
1545 <entry>-</entry>
1546 <entry>-</entry>
1547 <entry>-</entry>
1548 <entry>-</entry>
1549 <entry>-</entry>
1550 <entry>-</entry>
1551 <entry>-</entry>
1552 <entry>-</entry>
1553 <entry>u<subscript>7</subscript></entry>
1554 <entry>u<subscript>6</subscript></entry>
1555 <entry>u<subscript>5</subscript></entry>
1556 <entry>u<subscript>4</subscript></entry>
1557 <entry>u<subscript>3</subscript></entry>
1558 <entry>u<subscript>2</subscript></entry>
1559 <entry>u<subscript>1</subscript></entry>
1560 <entry>u<subscript>0</subscript></entry>
1561 </row>
1562 <row>
1563 <entry></entry>
1564 <entry></entry>
1565 <entry></entry>
1566 <entry>-</entry>
1567 <entry>-</entry>
1568 <entry>-</entry>
1569 <entry>-</entry>
1570 <entry>-</entry>
1571 <entry>-</entry>
1572 <entry>-</entry>
1573 <entry>-</entry>
1574 <entry>-</entry>
1575 <entry>-</entry>
1576 <entry>-</entry>
1577 <entry>-</entry>
1578 <entry>y<subscript>7</subscript></entry>
1579 <entry>y<subscript>6</subscript></entry>
1580 <entry>y<subscript>5</subscript></entry>
1581 <entry>y<subscript>4</subscript></entry>
1582 <entry>y<subscript>3</subscript></entry>
1583 <entry>y<subscript>2</subscript></entry>
1584 <entry>y<subscript>1</subscript></entry>
1585 <entry>y<subscript>0</subscript></entry>
1586 </row>
1587 <row>
1588 <entry></entry>
1589 <entry></entry>
1590 <entry></entry>
1591 <entry>-</entry>
1592 <entry>-</entry>
1593 <entry>-</entry>
1594 <entry>-</entry>
1595 <entry>-</entry>
1596 <entry>-</entry>
1597 <entry>-</entry>
1598 <entry>-</entry>
1599 <entry>-</entry>
1600 <entry>-</entry>
1601 <entry>-</entry>
1602 <entry>-</entry>
1603 <entry>v<subscript>7</subscript></entry>
1604 <entry>v<subscript>6</subscript></entry>
1605 <entry>v<subscript>5</subscript></entry>
1606 <entry>v<subscript>4</subscript></entry>
1607 <entry>v<subscript>3</subscript></entry>
1608 <entry>v<subscript>2</subscript></entry>
1609 <entry>v<subscript>1</subscript></entry>
1610 <entry>v<subscript>0</subscript></entry>
1611 </row>
1612 <row>
1613 <entry></entry>
1614 <entry></entry>
1615 <entry></entry>
1616 <entry>-</entry>
1617 <entry>-</entry>
1618 <entry>-</entry>
1619 <entry>-</entry>
1620 <entry>-</entry>
1621 <entry>-</entry>
1622 <entry>-</entry>
1623 <entry>-</entry>
1624 <entry>-</entry>
1625 <entry>-</entry>
1626 <entry>-</entry>
1627 <entry>-</entry>
1628 <entry>y<subscript>7</subscript></entry>
1629 <entry>y<subscript>6</subscript></entry>
1630 <entry>y<subscript>5</subscript></entry>
1631 <entry>y<subscript>4</subscript></entry>
1632 <entry>y<subscript>3</subscript></entry>
1633 <entry>y<subscript>2</subscript></entry>
1634 <entry>y<subscript>1</subscript></entry>
1635 <entry>y<subscript>0</subscript></entry>
1636 </row>
1637 <row id="V4L2-MBUS-FMT-VYUY8-2X8">
1638 <entry>V4L2_MBUS_FMT_VYUY8_2X8</entry>
1639 <entry>0x2007</entry>
1640 <entry></entry>
1641 <entry>-</entry>
1642 <entry>-</entry>
1643 <entry>-</entry>
1644 <entry>-</entry>
1645 <entry>-</entry>
1646 <entry>-</entry>
1647 <entry>-</entry>
1648 <entry>-</entry>
1649 <entry>-</entry>
1650 <entry>-</entry>
1651 <entry>-</entry>
1652 <entry>-</entry>
1653 <entry>v<subscript>7</subscript></entry>
1654 <entry>v<subscript>6</subscript></entry>
1655 <entry>v<subscript>5</subscript></entry>
1656 <entry>v<subscript>4</subscript></entry>
1657 <entry>v<subscript>3</subscript></entry>
1658 <entry>v<subscript>2</subscript></entry>
1659 <entry>v<subscript>1</subscript></entry>
1660 <entry>v<subscript>0</subscript></entry>
1661 </row>
1662 <row>
1663 <entry></entry>
1664 <entry></entry>
1665 <entry></entry>
1666 <entry>-</entry>
1667 <entry>-</entry>
1668 <entry>-</entry>
1669 <entry>-</entry>
1670 <entry>-</entry>
1671 <entry>-</entry>
1672 <entry>-</entry>
1673 <entry>-</entry>
1674 <entry>-</entry>
1675 <entry>-</entry>
1676 <entry>-</entry>
1677 <entry>-</entry>
1678 <entry>y<subscript>7</subscript></entry>
1679 <entry>y<subscript>6</subscript></entry>
1680 <entry>y<subscript>5</subscript></entry>
1681 <entry>y<subscript>4</subscript></entry>
1682 <entry>y<subscript>3</subscript></entry>
1683 <entry>y<subscript>2</subscript></entry>
1684 <entry>y<subscript>1</subscript></entry>
1685 <entry>y<subscript>0</subscript></entry>
1686 </row>
1687 <row>
1688 <entry></entry>
1689 <entry></entry>
1690 <entry></entry>
1691 <entry>-</entry>
1692 <entry>-</entry>
1693 <entry>-</entry>
1694 <entry>-</entry>
1695 <entry>-</entry>
1696 <entry>-</entry>
1697 <entry>-</entry>
1698 <entry>-</entry>
1699 <entry>-</entry>
1700 <entry>-</entry>
1701 <entry>-</entry>
1702 <entry>-</entry>
1703 <entry>u<subscript>7</subscript></entry>
1704 <entry>u<subscript>6</subscript></entry>
1705 <entry>u<subscript>5</subscript></entry>
1706 <entry>u<subscript>4</subscript></entry>
1707 <entry>u<subscript>3</subscript></entry>
1708 <entry>u<subscript>2</subscript></entry>
1709 <entry>u<subscript>1</subscript></entry>
1710 <entry>u<subscript>0</subscript></entry>
1711 </row>
1712 <row>
1713 <entry></entry>
1714 <entry></entry>
1715 <entry></entry>
1716 <entry>-</entry>
1717 <entry>-</entry>
1718 <entry>-</entry>
1719 <entry>-</entry>
1720 <entry>-</entry>
1721 <entry>-</entry>
1722 <entry>-</entry>
1723 <entry>-</entry>
1724 <entry>-</entry>
1725 <entry>-</entry>
1726 <entry>-</entry>
1727 <entry>-</entry>
1728 <entry>y<subscript>7</subscript></entry>
1729 <entry>y<subscript>6</subscript></entry>
1730 <entry>y<subscript>5</subscript></entry>
1731 <entry>y<subscript>4</subscript></entry>
1732 <entry>y<subscript>3</subscript></entry>
1733 <entry>y<subscript>2</subscript></entry>
1734 <entry>y<subscript>1</subscript></entry>
1735 <entry>y<subscript>0</subscript></entry>
1736 </row>
1737 <row id="V4L2-MBUS-FMT-YUYV8-2X8">
1738 <entry>V4L2_MBUS_FMT_YUYV8_2X8</entry>
1739 <entry>0x2008</entry>
1740 <entry></entry>
1741 <entry>-</entry>
1742 <entry>-</entry>
1743 <entry>-</entry>
1744 <entry>-</entry>
1745 <entry>-</entry>
1746 <entry>-</entry>
1747 <entry>-</entry>
1748 <entry>-</entry>
1749 <entry>-</entry>
1750 <entry>-</entry>
1751 <entry>-</entry>
1752 <entry>-</entry>
1753 <entry>y<subscript>7</subscript></entry>
1754 <entry>y<subscript>6</subscript></entry>
1755 <entry>y<subscript>5</subscript></entry>
1756 <entry>y<subscript>4</subscript></entry>
1757 <entry>y<subscript>3</subscript></entry>
1758 <entry>y<subscript>2</subscript></entry>
1759 <entry>y<subscript>1</subscript></entry>
1760 <entry>y<subscript>0</subscript></entry>
1761 </row>
1762 <row>
1763 <entry></entry>
1764 <entry></entry>
1765 <entry></entry>
1766 <entry>-</entry>
1767 <entry>-</entry>
1768 <entry>-</entry>
1769 <entry>-</entry>
1770 <entry>-</entry>
1771 <entry>-</entry>
1772 <entry>-</entry>
1773 <entry>-</entry>
1774 <entry>-</entry>
1775 <entry>-</entry>
1776 <entry>-</entry>
1777 <entry>-</entry>
1778 <entry>u<subscript>7</subscript></entry>
1779 <entry>u<subscript>6</subscript></entry>
1780 <entry>u<subscript>5</subscript></entry>
1781 <entry>u<subscript>4</subscript></entry>
1782 <entry>u<subscript>3</subscript></entry>
1783 <entry>u<subscript>2</subscript></entry>
1784 <entry>u<subscript>1</subscript></entry>
1785 <entry>u<subscript>0</subscript></entry>
1786 </row>
1787 <row>
1788 <entry></entry>
1789 <entry></entry>
1790 <entry></entry>
1791 <entry>-</entry>
1792 <entry>-</entry>
1793 <entry>-</entry>
1794 <entry>-</entry>
1795 <entry>-</entry>
1796 <entry>-</entry>
1797 <entry>-</entry>
1798 <entry>-</entry>
1799 <entry>-</entry>
1800 <entry>-</entry>
1801 <entry>-</entry>
1802 <entry>-</entry>
1803 <entry>y<subscript>7</subscript></entry>
1804 <entry>y<subscript>6</subscript></entry>
1805 <entry>y<subscript>5</subscript></entry>
1806 <entry>y<subscript>4</subscript></entry>
1807 <entry>y<subscript>3</subscript></entry>
1808 <entry>y<subscript>2</subscript></entry>
1809 <entry>y<subscript>1</subscript></entry>
1810 <entry>y<subscript>0</subscript></entry>
1811 </row>
1812 <row>
1813 <entry></entry>
1814 <entry></entry>
1815 <entry></entry>
1816 <entry>-</entry>
1817 <entry>-</entry>
1818 <entry>-</entry>
1819 <entry>-</entry>
1820 <entry>-</entry>
1821 <entry>-</entry>
1822 <entry>-</entry>
1823 <entry>-</entry>
1824 <entry>-</entry>
1825 <entry>-</entry>
1826 <entry>-</entry>
1827 <entry>-</entry>
1828 <entry>v<subscript>7</subscript></entry>
1829 <entry>v<subscript>6</subscript></entry>
1830 <entry>v<subscript>5</subscript></entry>
1831 <entry>v<subscript>4</subscript></entry>
1832 <entry>v<subscript>3</subscript></entry>
1833 <entry>v<subscript>2</subscript></entry>
1834 <entry>v<subscript>1</subscript></entry>
1835 <entry>v<subscript>0</subscript></entry>
1836 </row>
1837 <row id="V4L2-MBUS-FMT-YVYU8-2X8">
1838 <entry>V4L2_MBUS_FMT_YVYU8_2X8</entry>
1839 <entry>0x2009</entry>
1840 <entry></entry>
1841 <entry>-</entry>
1842 <entry>-</entry>
1843 <entry>-</entry>
1844 <entry>-</entry>
1845 <entry>-</entry>
1846 <entry>-</entry>
1847 <entry>-</entry>
1848 <entry>-</entry>
1849 <entry>-</entry>
1850 <entry>-</entry>
1851 <entry>-</entry>
1852 <entry>-</entry>
1853 <entry>y<subscript>7</subscript></entry>
1854 <entry>y<subscript>6</subscript></entry>
1855 <entry>y<subscript>5</subscript></entry>
1856 <entry>y<subscript>4</subscript></entry>
1857 <entry>y<subscript>3</subscript></entry>
1858 <entry>y<subscript>2</subscript></entry>
1859 <entry>y<subscript>1</subscript></entry>
1860 <entry>y<subscript>0</subscript></entry>
1861 </row>
1862 <row>
1863 <entry></entry>
1864 <entry></entry>
1865 <entry></entry>
1866 <entry>-</entry>
1867 <entry>-</entry>
1868 <entry>-</entry>
1869 <entry>-</entry>
1870 <entry>-</entry>
1871 <entry>-</entry>
1872 <entry>-</entry>
1873 <entry>-</entry>
1874 <entry>-</entry>
1875 <entry>-</entry>
1876 <entry>-</entry>
1877 <entry>-</entry>
1878 <entry>v<subscript>7</subscript></entry>
1879 <entry>v<subscript>6</subscript></entry>
1880 <entry>v<subscript>5</subscript></entry>
1881 <entry>v<subscript>4</subscript></entry>
1882 <entry>v<subscript>3</subscript></entry>
1883 <entry>v<subscript>2</subscript></entry>
1884 <entry>v<subscript>1</subscript></entry>
1885 <entry>v<subscript>0</subscript></entry>
1886 </row>
1887 <row>
1888 <entry></entry>
1889 <entry></entry>
1890 <entry></entry>
1891 <entry>-</entry>
1892 <entry>-</entry>
1893 <entry>-</entry>
1894 <entry>-</entry>
1895 <entry>-</entry>
1896 <entry>-</entry>
1897 <entry>-</entry>
1898 <entry>-</entry>
1899 <entry>-</entry>
1900 <entry>-</entry>
1901 <entry>-</entry>
1902 <entry>-</entry>
1903 <entry>y<subscript>7</subscript></entry>
1904 <entry>y<subscript>6</subscript></entry>
1905 <entry>y<subscript>5</subscript></entry>
1906 <entry>y<subscript>4</subscript></entry>
1907 <entry>y<subscript>3</subscript></entry>
1908 <entry>y<subscript>2</subscript></entry>
1909 <entry>y<subscript>1</subscript></entry>
1910 <entry>y<subscript>0</subscript></entry>
1911 </row>
1912 <row>
1913 <entry></entry>
1914 <entry></entry>
1915 <entry></entry>
1916 <entry>-</entry>
1917 <entry>-</entry>
1918 <entry>-</entry>
1919 <entry>-</entry>
1920 <entry>-</entry>
1921 <entry>-</entry>
1922 <entry>-</entry>
1923 <entry>-</entry>
1924 <entry>-</entry>
1925 <entry>-</entry>
1926 <entry>-</entry>
1927 <entry>-</entry>
1928 <entry>u<subscript>7</subscript></entry>
1929 <entry>u<subscript>6</subscript></entry>
1930 <entry>u<subscript>5</subscript></entry>
1931 <entry>u<subscript>4</subscript></entry>
1932 <entry>u<subscript>3</subscript></entry>
1933 <entry>u<subscript>2</subscript></entry>
1934 <entry>u<subscript>1</subscript></entry>
1935 <entry>u<subscript>0</subscript></entry>
1936 </row>
1937 <row id="V4L2-MBUS-FMT-Y10-1X10">
1938 <entry>V4L2_MBUS_FMT_Y10_1X10</entry>
1939 <entry>0x200a</entry>
1940 <entry></entry>
1941 <entry>-</entry>
1942 <entry>-</entry>
1943 <entry>-</entry>
1944 <entry>-</entry>
1945 <entry>-</entry>
1946 <entry>-</entry>
1947 <entry>-</entry>
1948 <entry>-</entry>
1949 <entry>-</entry>
1950 <entry>-</entry>
1951 <entry>y<subscript>9</subscript></entry>
1952 <entry>y<subscript>8</subscript></entry>
1953 <entry>y<subscript>7</subscript></entry>
1954 <entry>y<subscript>6</subscript></entry>
1955 <entry>y<subscript>5</subscript></entry>
1956 <entry>y<subscript>4</subscript></entry>
1957 <entry>y<subscript>3</subscript></entry>
1958 <entry>y<subscript>2</subscript></entry>
1959 <entry>y<subscript>1</subscript></entry>
1960 <entry>y<subscript>0</subscript></entry>
1961 </row>
1962 <row id="V4L2-MBUS-FMT-YUYV10-2X10">
1963 <entry>V4L2_MBUS_FMT_YUYV10_2X10</entry>
1964 <entry>0x200b</entry>
1965 <entry></entry>
1966 <entry>-</entry>
1967 <entry>-</entry>
1968 <entry>-</entry>
1969 <entry>-</entry>
1970 <entry>-</entry>
1971 <entry>-</entry>
1972 <entry>-</entry>
1973 <entry>-</entry>
1974 <entry>-</entry>
1975 <entry>-</entry>
1976 <entry>y<subscript>9</subscript></entry>
1977 <entry>y<subscript>8</subscript></entry>
1978 <entry>y<subscript>7</subscript></entry>
1979 <entry>y<subscript>6</subscript></entry>
1980 <entry>y<subscript>5</subscript></entry>
1981 <entry>y<subscript>4</subscript></entry>
1982 <entry>y<subscript>3</subscript></entry>
1983 <entry>y<subscript>2</subscript></entry>
1984 <entry>y<subscript>1</subscript></entry>
1985 <entry>y<subscript>0</subscript></entry>
1986 </row>
1987 <row>
1988 <entry></entry>
1989 <entry></entry>
1990 <entry></entry>
1991 <entry>-</entry>
1992 <entry>-</entry>
1993 <entry>-</entry>
1994 <entry>-</entry>
1995 <entry>-</entry>
1996 <entry>-</entry>
1997 <entry>-</entry>
1998 <entry>-</entry>
1999 <entry>-</entry>
2000 <entry>-</entry>
2001 <entry>u<subscript>9</subscript></entry>
2002 <entry>u<subscript>8</subscript></entry>
2003 <entry>u<subscript>7</subscript></entry>
2004 <entry>u<subscript>6</subscript></entry>
2005 <entry>u<subscript>5</subscript></entry>
2006 <entry>u<subscript>4</subscript></entry>
2007 <entry>u<subscript>3</subscript></entry>
2008 <entry>u<subscript>2</subscript></entry>
2009 <entry>u<subscript>1</subscript></entry>
2010 <entry>u<subscript>0</subscript></entry>
2011 </row>
2012 <row>
2013 <entry></entry>
2014 <entry></entry>
2015 <entry></entry>
2016 <entry>-</entry>
2017 <entry>-</entry>
2018 <entry>-</entry>
2019 <entry>-</entry>
2020 <entry>-</entry>
2021 <entry>-</entry>
2022 <entry>-</entry>
2023 <entry>-</entry>
2024 <entry>-</entry>
2025 <entry>-</entry>
2026 <entry>y<subscript>9</subscript></entry>
2027 <entry>y<subscript>8</subscript></entry>
2028 <entry>y<subscript>7</subscript></entry>
2029 <entry>y<subscript>6</subscript></entry>
2030 <entry>y<subscript>5</subscript></entry>
2031 <entry>y<subscript>4</subscript></entry>
2032 <entry>y<subscript>3</subscript></entry>
2033 <entry>y<subscript>2</subscript></entry>
2034 <entry>y<subscript>1</subscript></entry>
2035 <entry>y<subscript>0</subscript></entry>
2036 </row>
2037 <row>
2038 <entry></entry>
2039 <entry></entry>
2040 <entry></entry>
2041 <entry>-</entry>
2042 <entry>-</entry>
2043 <entry>-</entry>
2044 <entry>-</entry>
2045 <entry>-</entry>
2046 <entry>-</entry>
2047 <entry>-</entry>
2048 <entry>-</entry>
2049 <entry>-</entry>
2050 <entry>-</entry>
2051 <entry>v<subscript>9</subscript></entry>
2052 <entry>v<subscript>8</subscript></entry>
2053 <entry>v<subscript>7</subscript></entry>
2054 <entry>v<subscript>6</subscript></entry>
2055 <entry>v<subscript>5</subscript></entry>
2056 <entry>v<subscript>4</subscript></entry>
2057 <entry>v<subscript>3</subscript></entry>
2058 <entry>v<subscript>2</subscript></entry>
2059 <entry>v<subscript>1</subscript></entry>
2060 <entry>v<subscript>0</subscript></entry>
2061 </row>
2062 <row id="V4L2-MBUS-FMT-YVYU10-2X10">
2063 <entry>V4L2_MBUS_FMT_YVYU10_2X10</entry>
2064 <entry>0x200c</entry>
2065 <entry></entry>
2066 <entry>-</entry>
2067 <entry>-</entry>
2068 <entry>-</entry>
2069 <entry>-</entry>
2070 <entry>-</entry>
2071 <entry>-</entry>
2072 <entry>-</entry>
2073 <entry>-</entry>
2074 <entry>-</entry>
2075 <entry>-</entry>
2076 <entry>y<subscript>9</subscript></entry>
2077 <entry>y<subscript>8</subscript></entry>
2078 <entry>y<subscript>7</subscript></entry>
2079 <entry>y<subscript>6</subscript></entry>
2080 <entry>y<subscript>5</subscript></entry>
2081 <entry>y<subscript>4</subscript></entry>
2082 <entry>y<subscript>3</subscript></entry>
2083 <entry>y<subscript>2</subscript></entry>
2084 <entry>y<subscript>1</subscript></entry>
2085 <entry>y<subscript>0</subscript></entry>
2086 </row>
2087 <row>
2088 <entry></entry>
2089 <entry></entry>
2090 <entry></entry>
2091 <entry>-</entry>
2092 <entry>-</entry>
2093 <entry>-</entry>
2094 <entry>-</entry>
2095 <entry>-</entry>
2096 <entry>-</entry>
2097 <entry>-</entry>
2098 <entry>-</entry>
2099 <entry>-</entry>
2100 <entry>-</entry>
2101 <entry>v<subscript>9</subscript></entry>
2102 <entry>v<subscript>8</subscript></entry>
2103 <entry>v<subscript>7</subscript></entry>
2104 <entry>v<subscript>6</subscript></entry>
2105 <entry>v<subscript>5</subscript></entry>
2106 <entry>v<subscript>4</subscript></entry>
2107 <entry>v<subscript>3</subscript></entry>
2108 <entry>v<subscript>2</subscript></entry>
2109 <entry>v<subscript>1</subscript></entry>
2110 <entry>v<subscript>0</subscript></entry>
2111 </row>
2112 <row>
2113 <entry></entry>
2114 <entry></entry>
2115 <entry></entry>
2116 <entry>-</entry>
2117 <entry>-</entry>
2118 <entry>-</entry>
2119 <entry>-</entry>
2120 <entry>-</entry>
2121 <entry>-</entry>
2122 <entry>-</entry>
2123 <entry>-</entry>
2124 <entry>-</entry>
2125 <entry>-</entry>
2126 <entry>y<subscript>9</subscript></entry>
2127 <entry>y<subscript>8</subscript></entry>
2128 <entry>y<subscript>7</subscript></entry>
2129 <entry>y<subscript>6</subscript></entry>
2130 <entry>y<subscript>5</subscript></entry>
2131 <entry>y<subscript>4</subscript></entry>
2132 <entry>y<subscript>3</subscript></entry>
2133 <entry>y<subscript>2</subscript></entry>
2134 <entry>y<subscript>1</subscript></entry>
2135 <entry>y<subscript>0</subscript></entry>
2136 </row>
2137 <row>
2138 <entry></entry>
2139 <entry></entry>
2140 <entry></entry>
2141 <entry>-</entry>
2142 <entry>-</entry>
2143 <entry>-</entry>
2144 <entry>-</entry>
2145 <entry>-</entry>
2146 <entry>-</entry>
2147 <entry>-</entry>
2148 <entry>-</entry>
2149 <entry>-</entry>
2150 <entry>-</entry>
2151 <entry>u<subscript>9</subscript></entry>
2152 <entry>u<subscript>8</subscript></entry>
2153 <entry>u<subscript>7</subscript></entry>
2154 <entry>u<subscript>6</subscript></entry>
2155 <entry>u<subscript>5</subscript></entry>
2156 <entry>u<subscript>4</subscript></entry>
2157 <entry>u<subscript>3</subscript></entry>
2158 <entry>u<subscript>2</subscript></entry>
2159 <entry>u<subscript>1</subscript></entry>
2160 <entry>u<subscript>0</subscript></entry>
2161 </row>
2162 <row id="V4L2-MBUS-FMT-UYVY8-1X16">
2163 <entry>V4L2_MBUS_FMT_UYVY8_1X16</entry>
2164 <entry>0x200f</entry>
2165 <entry></entry>
2166 <entry>-</entry>
2167 <entry>-</entry>
2168 <entry>-</entry>
2169 <entry>-</entry>
2170 <entry>u<subscript>7</subscript></entry>
2171 <entry>u<subscript>6</subscript></entry>
2172 <entry>u<subscript>5</subscript></entry>
2173 <entry>u<subscript>4</subscript></entry>
2174 <entry>u<subscript>3</subscript></entry>
2175 <entry>u<subscript>2</subscript></entry>
2176 <entry>u<subscript>1</subscript></entry>
2177 <entry>u<subscript>0</subscript></entry>
2178 <entry>y<subscript>7</subscript></entry>
2179 <entry>y<subscript>6</subscript></entry>
2180 <entry>y<subscript>5</subscript></entry>
2181 <entry>y<subscript>4</subscript></entry>
2182 <entry>y<subscript>3</subscript></entry>
2183 <entry>y<subscript>2</subscript></entry>
2184 <entry>y<subscript>1</subscript></entry>
2185 <entry>y<subscript>0</subscript></entry>
2186 </row>
2187 <row>
2188 <entry></entry>
2189 <entry></entry>
2190 <entry></entry>
2191 <entry>-</entry>
2192 <entry>-</entry>
2193 <entry>-</entry>
2194 <entry>-</entry>
2195 <entry>v<subscript>7</subscript></entry>
2196 <entry>v<subscript>6</subscript></entry>
2197 <entry>v<subscript>5</subscript></entry>
2198 <entry>v<subscript>4</subscript></entry>
2199 <entry>v<subscript>3</subscript></entry>
2200 <entry>v<subscript>2</subscript></entry>
2201 <entry>v<subscript>1</subscript></entry>
2202 <entry>v<subscript>0</subscript></entry>
2203 <entry>y<subscript>7</subscript></entry>
2204 <entry>y<subscript>6</subscript></entry>
2205 <entry>y<subscript>5</subscript></entry>
2206 <entry>y<subscript>4</subscript></entry>
2207 <entry>y<subscript>3</subscript></entry>
2208 <entry>y<subscript>2</subscript></entry>
2209 <entry>y<subscript>1</subscript></entry>
2210 <entry>y<subscript>0</subscript></entry>
2211 </row>
2212 <row id="V4L2-MBUS-FMT-VYUY8-1X16">
2213 <entry>V4L2_MBUS_FMT_VYUY8_1X16</entry>
2214 <entry>0x2010</entry>
2215 <entry></entry>
2216 <entry>-</entry>
2217 <entry>-</entry>
2218 <entry>-</entry>
2219 <entry>-</entry>
2220 <entry>v<subscript>7</subscript></entry>
2221 <entry>v<subscript>6</subscript></entry>
2222 <entry>v<subscript>5</subscript></entry>
2223 <entry>v<subscript>4</subscript></entry>
2224 <entry>v<subscript>3</subscript></entry>
2225 <entry>v<subscript>2</subscript></entry>
2226 <entry>v<subscript>1</subscript></entry>
2227 <entry>v<subscript>0</subscript></entry>
2228 <entry>y<subscript>7</subscript></entry>
2229 <entry>y<subscript>6</subscript></entry>
2230 <entry>y<subscript>5</subscript></entry>
2231 <entry>y<subscript>4</subscript></entry>
2232 <entry>y<subscript>3</subscript></entry>
2233 <entry>y<subscript>2</subscript></entry>
2234 <entry>y<subscript>1</subscript></entry>
2235 <entry>y<subscript>0</subscript></entry>
2236 </row>
2237 <row>
2238 <entry></entry>
2239 <entry></entry>
2240 <entry></entry>
2241 <entry>-</entry>
2242 <entry>-</entry>
2243 <entry>-</entry>
2244 <entry>-</entry>
2245 <entry>u<subscript>7</subscript></entry>
2246 <entry>u<subscript>6</subscript></entry>
2247 <entry>u<subscript>5</subscript></entry>
2248 <entry>u<subscript>4</subscript></entry>
2249 <entry>u<subscript>3</subscript></entry>
2250 <entry>u<subscript>2</subscript></entry>
2251 <entry>u<subscript>1</subscript></entry>
2252 <entry>u<subscript>0</subscript></entry>
2253 <entry>y<subscript>7</subscript></entry>
2254 <entry>y<subscript>6</subscript></entry>
2255 <entry>y<subscript>5</subscript></entry>
2256 <entry>y<subscript>4</subscript></entry>
2257 <entry>y<subscript>3</subscript></entry>
2258 <entry>y<subscript>2</subscript></entry>
2259 <entry>y<subscript>1</subscript></entry>
2260 <entry>y<subscript>0</subscript></entry>
2261 </row>
2262 <row id="V4L2-MBUS-FMT-YUYV8-1X16">
2263 <entry>V4L2_MBUS_FMT_YUYV8_1X16</entry>
2264 <entry>0x2011</entry>
2265 <entry></entry>
2266 <entry>-</entry>
2267 <entry>-</entry>
2268 <entry>-</entry>
2269 <entry>-</entry>
2270 <entry>y<subscript>7</subscript></entry>
2271 <entry>y<subscript>6</subscript></entry>
2272 <entry>y<subscript>5</subscript></entry>
2273 <entry>y<subscript>4</subscript></entry>
2274 <entry>y<subscript>3</subscript></entry>
2275 <entry>y<subscript>2</subscript></entry>
2276 <entry>y<subscript>1</subscript></entry>
2277 <entry>y<subscript>0</subscript></entry>
2278 <entry>u<subscript>7</subscript></entry>
2279 <entry>u<subscript>6</subscript></entry>
2280 <entry>u<subscript>5</subscript></entry>
2281 <entry>u<subscript>4</subscript></entry>
2282 <entry>u<subscript>3</subscript></entry>
2283 <entry>u<subscript>2</subscript></entry>
2284 <entry>u<subscript>1</subscript></entry>
2285 <entry>u<subscript>0</subscript></entry>
2286 </row>
2287 <row>
2288 <entry></entry>
2289 <entry></entry>
2290 <entry></entry>
2291 <entry>-</entry>
2292 <entry>-</entry>
2293 <entry>-</entry>
2294 <entry>-</entry>
2295 <entry>y<subscript>7</subscript></entry>
2296 <entry>y<subscript>6</subscript></entry>
2297 <entry>y<subscript>5</subscript></entry>
2298 <entry>y<subscript>4</subscript></entry>
2299 <entry>y<subscript>3</subscript></entry>
2300 <entry>y<subscript>2</subscript></entry>
2301 <entry>y<subscript>1</subscript></entry>
2302 <entry>y<subscript>0</subscript></entry>
2303 <entry>v<subscript>7</subscript></entry>
2304 <entry>v<subscript>6</subscript></entry>
2305 <entry>v<subscript>5</subscript></entry>
2306 <entry>v<subscript>4</subscript></entry>
2307 <entry>v<subscript>3</subscript></entry>
2308 <entry>v<subscript>2</subscript></entry>
2309 <entry>v<subscript>1</subscript></entry>
2310 <entry>v<subscript>0</subscript></entry>
2311 </row>
2312 <row id="V4L2-MBUS-FMT-YVYU8-1X16">
2313 <entry>V4L2_MBUS_FMT_YVYU8_1X16</entry>
2314 <entry>0x2012</entry>
2315 <entry></entry>
2316 <entry>-</entry>
2317 <entry>-</entry>
2318 <entry>-</entry>
2319 <entry>-</entry>
2320 <entry>y<subscript>7</subscript></entry>
2321 <entry>y<subscript>6</subscript></entry>
2322 <entry>y<subscript>5</subscript></entry>
2323 <entry>y<subscript>4</subscript></entry>
2324 <entry>y<subscript>3</subscript></entry>
2325 <entry>y<subscript>2</subscript></entry>
2326 <entry>y<subscript>1</subscript></entry>
2327 <entry>y<subscript>0</subscript></entry>
2328 <entry>v<subscript>7</subscript></entry>
2329 <entry>v<subscript>6</subscript></entry>
2330 <entry>v<subscript>5</subscript></entry>
2331 <entry>v<subscript>4</subscript></entry>
2332 <entry>v<subscript>3</subscript></entry>
2333 <entry>v<subscript>2</subscript></entry>
2334 <entry>v<subscript>1</subscript></entry>
2335 <entry>v<subscript>0</subscript></entry>
2336 </row>
2337 <row>
2338 <entry></entry>
2339 <entry></entry>
2340 <entry></entry>
2341 <entry>-</entry>
2342 <entry>-</entry>
2343 <entry>-</entry>
2344 <entry>-</entry>
2345 <entry>y<subscript>7</subscript></entry>
2346 <entry>y<subscript>6</subscript></entry>
2347 <entry>y<subscript>5</subscript></entry>
2348 <entry>y<subscript>4</subscript></entry>
2349 <entry>y<subscript>3</subscript></entry>
2350 <entry>y<subscript>2</subscript></entry>
2351 <entry>y<subscript>1</subscript></entry>
2352 <entry>y<subscript>0</subscript></entry>
2353 <entry>u<subscript>7</subscript></entry>
2354 <entry>u<subscript>6</subscript></entry>
2355 <entry>u<subscript>5</subscript></entry>
2356 <entry>u<subscript>4</subscript></entry>
2357 <entry>u<subscript>3</subscript></entry>
2358 <entry>u<subscript>2</subscript></entry>
2359 <entry>u<subscript>1</subscript></entry>
2360 <entry>u<subscript>0</subscript></entry>
2361 </row>
2362 <row id="V4L2-MBUS-FMT-YUYV10-1X20">
2363 <entry>V4L2_MBUS_FMT_YUYV10_1X20</entry>
2364 <entry>0x200d</entry>
2365 <entry></entry>
2366 <entry>y<subscript>9</subscript></entry>
2367 <entry>y<subscript>8</subscript></entry>
2368 <entry>y<subscript>7</subscript></entry>
2369 <entry>y<subscript>6</subscript></entry>
2370 <entry>y<subscript>5</subscript></entry>
2371 <entry>y<subscript>4</subscript></entry>
2372 <entry>y<subscript>3</subscript></entry>
2373 <entry>y<subscript>2</subscript></entry>
2374 <entry>y<subscript>1</subscript></entry>
2375 <entry>y<subscript>0</subscript></entry>
2376 <entry>u<subscript>9</subscript></entry>
2377 <entry>u<subscript>8</subscript></entry>
2378 <entry>u<subscript>7</subscript></entry>
2379 <entry>u<subscript>6</subscript></entry>
2380 <entry>u<subscript>5</subscript></entry>
2381 <entry>u<subscript>4</subscript></entry>
2382 <entry>u<subscript>3</subscript></entry>
2383 <entry>u<subscript>2</subscript></entry>
2384 <entry>u<subscript>1</subscript></entry>
2385 <entry>u<subscript>0</subscript></entry>
2386 </row>
2387 <row>
2388 <entry></entry>
2389 <entry></entry>
2390 <entry></entry>
2391 <entry>y<subscript>9</subscript></entry>
2392 <entry>y<subscript>8</subscript></entry>
2393 <entry>y<subscript>7</subscript></entry>
2394 <entry>y<subscript>6</subscript></entry>
2395 <entry>y<subscript>5</subscript></entry>
2396 <entry>y<subscript>4</subscript></entry>
2397 <entry>y<subscript>3</subscript></entry>
2398 <entry>y<subscript>2</subscript></entry>
2399 <entry>y<subscript>1</subscript></entry>
2400 <entry>y<subscript>0</subscript></entry>
2401 <entry>v<subscript>9</subscript></entry>
2402 <entry>v<subscript>8</subscript></entry>
2403 <entry>v<subscript>7</subscript></entry>
2404 <entry>v<subscript>6</subscript></entry>
2405 <entry>v<subscript>5</subscript></entry>
2406 <entry>v<subscript>4</subscript></entry>
2407 <entry>v<subscript>3</subscript></entry>
2408 <entry>v<subscript>2</subscript></entry>
2409 <entry>v<subscript>1</subscript></entry>
2410 <entry>v<subscript>0</subscript></entry>
2411 </row>
2412 <row id="V4L2-MBUS-FMT-YVYU10-1X20">
2413 <entry>V4L2_MBUS_FMT_YVYU10_1X20</entry>
2414 <entry>0x200e</entry>
2415 <entry></entry>
2416 <entry>y<subscript>9</subscript></entry>
2417 <entry>y<subscript>8</subscript></entry>
2418 <entry>y<subscript>7</subscript></entry>
2419 <entry>y<subscript>6</subscript></entry>
2420 <entry>y<subscript>5</subscript></entry>
2421 <entry>y<subscript>4</subscript></entry>
2422 <entry>y<subscript>3</subscript></entry>
2423 <entry>y<subscript>2</subscript></entry>
2424 <entry>y<subscript>1</subscript></entry>
2425 <entry>y<subscript>0</subscript></entry>
2426 <entry>v<subscript>9</subscript></entry>
2427 <entry>v<subscript>8</subscript></entry>
2428 <entry>v<subscript>7</subscript></entry>
2429 <entry>v<subscript>6</subscript></entry>
2430 <entry>v<subscript>5</subscript></entry>
2431 <entry>v<subscript>4</subscript></entry>
2432 <entry>v<subscript>3</subscript></entry>
2433 <entry>v<subscript>2</subscript></entry>
2434 <entry>v<subscript>1</subscript></entry>
2435 <entry>v<subscript>0</subscript></entry>
2436 </row>
2437 <row>
2438 <entry></entry>
2439 <entry></entry>
2440 <entry></entry>
2441 <entry>y<subscript>9</subscript></entry>
2442 <entry>y<subscript>8</subscript></entry>
2443 <entry>y<subscript>7</subscript></entry>
2444 <entry>y<subscript>6</subscript></entry>
2445 <entry>y<subscript>5</subscript></entry>
2446 <entry>y<subscript>4</subscript></entry>
2447 <entry>y<subscript>3</subscript></entry>
2448 <entry>y<subscript>2</subscript></entry>
2449 <entry>y<subscript>1</subscript></entry>
2450 <entry>y<subscript>0</subscript></entry>
2451 <entry>u<subscript>9</subscript></entry>
2452 <entry>u<subscript>8</subscript></entry>
2453 <entry>u<subscript>7</subscript></entry>
2454 <entry>u<subscript>6</subscript></entry>
2455 <entry>u<subscript>5</subscript></entry>
2456 <entry>u<subscript>4</subscript></entry>
2457 <entry>u<subscript>3</subscript></entry>
2458 <entry>u<subscript>2</subscript></entry>
2459 <entry>u<subscript>1</subscript></entry>
2460 <entry>u<subscript>0</subscript></entry>
2461 </row>
2462 </tbody>
2463 </tgroup>
2464 </table>
2465 </section>
2466 </section>
2467</section>
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml
index 9288af96de34..a7fd76d0dac1 100644
--- a/Documentation/DocBook/v4l/v4l2.xml
+++ b/Documentation/DocBook/v4l/v4l2.xml
@@ -85,6 +85,17 @@ Remote Controller chapter.</contrib>
85 </address> 85 </address>
86 </affiliation> 86 </affiliation>
87 </author> 87 </author>
88
89 <author>
90 <firstname>Pawel</firstname>
91 <surname>Osciak</surname>
92 <contrib>Designed and documented the multi-planar API.</contrib>
93 <affiliation>
94 <address>
95 <email>pawel AT osciak.com</email>
96 </address>
97 </affiliation>
98 </author>
88 </authorgroup> 99 </authorgroup>
89 100
90 <copyright> 101 <copyright>
@@ -102,7 +113,8 @@ Remote Controller chapter.</contrib>
102 <year>2010</year> 113 <year>2010</year>
103 <year>2011</year> 114 <year>2011</year>
104 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin 115 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
105Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab</holder> 116Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
117 Pawel Osciak</holder>
106 </copyright> 118 </copyright>
107 <legalnotice> 119 <legalnotice>
108 <para>Except when explicitly stated as GPL, programming examples within 120 <para>Except when explicitly stated as GPL, programming examples within
@@ -116,6 +128,13 @@ structs, ioctls) must be noted in more detail in the history chapter
116applications. --> 128applications. -->
117 129
118 <revision> 130 <revision>
131 <revnumber>2.6.39</revnumber>
132 <date>2011-03-01</date>
133 <authorinitials>mcc, po</authorinitials>
134 <revremark>Removed VIDIOC_*_OLD from videodev2.h header and update it to reflect latest changes. Added the <link linkend="planar-apis">multi-planar API</link>.</revremark>
135 </revision>
136
137 <revision>
119 <revnumber>2.6.37</revnumber> 138 <revnumber>2.6.37</revnumber>
120 <date>2010-08-06</date> 139 <date>2010-08-06</date>
121 <authorinitials>hv</authorinitials> 140 <authorinitials>hv</authorinitials>
@@ -382,7 +401,7 @@ and discussions on the V4L mailing list.</revremark>
382</partinfo> 401</partinfo>
383 402
384<title>Video for Linux Two API Specification</title> 403<title>Video for Linux Two API Specification</title>
385 <subtitle>Revision 2.6.38</subtitle> 404 <subtitle>Revision 2.6.39</subtitle>
386 405
387 <chapter id="common"> 406 <chapter id="common">
388 &sub-common; 407 &sub-common;
@@ -411,6 +430,7 @@ and discussions on the V4L mailing list.</revremark>
411 <section id="radio"> &sub-dev-radio; </section> 430 <section id="radio"> &sub-dev-radio; </section>
412 <section id="rds"> &sub-dev-rds; </section> 431 <section id="rds"> &sub-dev-rds; </section>
413 <section id="event"> &sub-dev-event; </section> 432 <section id="event"> &sub-dev-event; </section>
433 <section id="subdev"> &sub-dev-subdev; </section>
414 </chapter> 434 </chapter>
415 435
416 <chapter id="driver"> 436 <chapter id="driver">
@@ -478,6 +498,12 @@ and discussions on the V4L mailing list.</revremark>
478 &sub-reqbufs; 498 &sub-reqbufs;
479 &sub-s-hw-freq-seek; 499 &sub-s-hw-freq-seek;
480 &sub-streamon; 500 &sub-streamon;
501 &sub-subdev-enum-frame-interval;
502 &sub-subdev-enum-frame-size;
503 &sub-subdev-enum-mbus-code;
504 &sub-subdev-g-crop;
505 &sub-subdev-g-fmt;
506 &sub-subdev-g-frame-interval;
481 &sub-subscribe-event; 507 &sub-subscribe-event;
482 <!-- End of ioctls. --> 508 <!-- End of ioctls. -->
483 &sub-mmap; 509 &sub-mmap;
diff --git a/Documentation/DocBook/v4l/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml
index 325b23b6964c..2b796a2ee98a 100644
--- a/Documentation/DocBook/v4l/videodev2.h.xml
+++ b/Documentation/DocBook/v4l/videodev2.h.xml
@@ -71,6 +71,7 @@
71 * Moved from videodev.h 71 * Moved from videodev.h
72 */ 72 */
73#define VIDEO_MAX_FRAME 32 73#define VIDEO_MAX_FRAME 32
74#define VIDEO_MAX_PLANES 8
74 75
75#ifndef __KERNEL__ 76#ifndef __KERNEL__
76 77
@@ -158,9 +159,23 @@ enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> {
158 /* Experimental */ 159 /* Experimental */
159 V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8, 160 V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8,
160#endif 161#endif
162 V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE = 9,
163 V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE = 10,
161 V4L2_BUF_TYPE_PRIVATE = 0x80, 164 V4L2_BUF_TYPE_PRIVATE = 0x80,
162}; 165};
163 166
167#define V4L2_TYPE_IS_MULTIPLANAR(type) \
168 ((type) == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE \
169 || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE)
170
171#define V4L2_TYPE_IS_OUTPUT(type) \
172 ((type) == V4L2_BUF_TYPE_VIDEO_OUTPUT \
173 || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE \
174 || (type) == V4L2_BUF_TYPE_VIDEO_OVERLAY \
175 || (type) == V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY \
176 || (type) == V4L2_BUF_TYPE_VBI_OUTPUT \
177 || (type) == V4L2_BUF_TYPE_SLICED_VBI_OUTPUT)
178
164enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> { 179enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> {
165 V4L2_TUNER_RADIO = 1, 180 V4L2_TUNER_RADIO = 1,
166 V4L2_TUNER_ANALOG_TV = 2, 181 V4L2_TUNER_ANALOG_TV = 2,
@@ -246,6 +261,11 @@ struct <link linkend="v4l2-capability">v4l2_capability</link> {
246#define V4L2_CAP_HW_FREQ_SEEK 0x00000400 /* Can do hardware frequency seek */ 261#define V4L2_CAP_HW_FREQ_SEEK 0x00000400 /* Can do hardware frequency seek */
247#define V4L2_CAP_RDS_OUTPUT 0x00000800 /* Is an RDS encoder */ 262#define V4L2_CAP_RDS_OUTPUT 0x00000800 /* Is an RDS encoder */
248 263
264/* Is a video capture device that supports multiplanar formats */
265#define V4L2_CAP_VIDEO_CAPTURE_MPLANE 0x00001000
266/* Is a video output device that supports multiplanar formats */
267#define V4L2_CAP_VIDEO_OUTPUT_MPLANE 0x00002000
268
249#define V4L2_CAP_TUNER 0x00010000 /* has a tuner */ 269#define V4L2_CAP_TUNER 0x00010000 /* has a tuner */
250#define V4L2_CAP_AUDIO 0x00020000 /* has audio support */ 270#define V4L2_CAP_AUDIO 0x00020000 /* has audio support */
251#define V4L2_CAP_RADIO 0x00040000 /* is a radio device */ 271#define V4L2_CAP_RADIO 0x00040000 /* is a radio device */
@@ -320,6 +340,13 @@ struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> {
320#define <link linkend="V4L2-PIX-FMT-NV16">V4L2_PIX_FMT_NV16</link> v4l2_fourcc('N', 'V', '1', '6') /* 16 Y/CbCr 4:2:2 */ 340#define <link linkend="V4L2-PIX-FMT-NV16">V4L2_PIX_FMT_NV16</link> v4l2_fourcc('N', 'V', '1', '6') /* 16 Y/CbCr 4:2:2 */
321#define <link linkend="V4L2-PIX-FMT-NV61">V4L2_PIX_FMT_NV61</link> v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */ 341#define <link linkend="V4L2-PIX-FMT-NV61">V4L2_PIX_FMT_NV61</link> v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */
322 342
343/* two non contiguous planes - one Y, one Cr + Cb interleaved */
344#define <link linkend="V4L2-PIX-FMT-NV12M">V4L2_PIX_FMT_NV12M</link> v4l2_fourcc('N', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 */
345#define <link linkend="V4L2-PIX-FMT-NV12MT">V4L2_PIX_FMT_NV12MT</link> v4l2_fourcc('T', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 64x32 macroblocks */
346
347/* three non contiguous planes - Y, Cb, Cr */
348#define <link linkend="V4L2-PIX-FMT-YUV420M">V4L2_PIX_FMT_YUV420M</link> v4l2_fourcc('Y', 'M', '1', '2') /* 12 YUV420 planar */
349
323/* Bayer formats - see http://www.siliconimaging.com/RGB%20Bayer.htm */ 350/* Bayer formats - see http://www.siliconimaging.com/RGB%20Bayer.htm */
324#define <link linkend="V4L2-PIX-FMT-SBGGR8">V4L2_PIX_FMT_SBGGR8</link> v4l2_fourcc('B', 'A', '8', '1') /* 8 BGBG.. GRGR.. */ 351#define <link linkend="V4L2-PIX-FMT-SBGGR8">V4L2_PIX_FMT_SBGGR8</link> v4l2_fourcc('B', 'A', '8', '1') /* 8 BGBG.. GRGR.. */
325#define <link linkend="V4L2-PIX-FMT-SGBRG8">V4L2_PIX_FMT_SGBRG8</link> v4l2_fourcc('G', 'B', 'R', 'G') /* 8 GBGB.. RGRG.. */ 352#define <link linkend="V4L2-PIX-FMT-SGBRG8">V4L2_PIX_FMT_SGBRG8</link> v4l2_fourcc('G', 'B', 'R', 'G') /* 8 GBGB.. RGRG.. */
@@ -518,6 +545,62 @@ struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> {
518 __u32 reserved[2]; 545 __u32 reserved[2];
519}; 546};
520 547
548/**
549 * struct <link linkend="v4l2-plane">v4l2_plane</link> - plane info for multi-planar buffers
550 * @bytesused: number of bytes occupied by data in the plane (payload)
551 * @length: size of this plane (NOT the payload) in bytes
552 * @mem_offset: when memory in the associated struct <link linkend="v4l2-buffer">v4l2_buffer</link> is
553 * V4L2_MEMORY_MMAP, equals the offset from the start of
554 * the device memory for this plane (or is a "cookie" that
555 * should be passed to mmap() called on the video node)
556 * @userptr: when memory is V4L2_MEMORY_USERPTR, a userspace pointer
557 * pointing to this plane
558 * @data_offset: offset in the plane to the start of data; usually 0,
559 * unless there is a header in front of the data
560 *
561 * Multi-planar buffers consist of one or more planes, e.g. an YCbCr buffer
562 * with two planes can have one plane for Y, and another for interleaved CbCr
563 * components. Each plane can reside in a separate memory buffer, or even in
564 * a completely separate memory node (e.g. in embedded devices).
565 */
566struct <link linkend="v4l2-plane">v4l2_plane</link> {
567 __u32 bytesused;
568 __u32 length;
569 union {
570 __u32 mem_offset;
571 unsigned long userptr;
572 } m;
573 __u32 data_offset;
574 __u32 reserved[11];
575};
576
577/**
578 * struct <link linkend="v4l2-buffer">v4l2_buffer</link> - video buffer info
579 * @index: id number of the buffer
580 * @type: buffer type (type == *_MPLANE for multiplanar buffers)
581 * @bytesused: number of bytes occupied by data in the buffer (payload);
582 * unused (set to 0) for multiplanar buffers
583 * @flags: buffer informational flags
584 * @field: field order of the image in the buffer
585 * @timestamp: frame timestamp
586 * @timecode: frame timecode
587 * @sequence: sequence count of this frame
588 * @memory: the method, in which the actual video data is passed
589 * @offset: for non-multiplanar buffers with memory == V4L2_MEMORY_MMAP;
590 * offset from the start of the device memory for this plane,
591 * (or a "cookie" that should be passed to mmap() as offset)
592 * @userptr: for non-multiplanar buffers with memory == V4L2_MEMORY_USERPTR;
593 * a userspace pointer pointing to this buffer
594 * @planes: for multiplanar buffers; userspace pointer to the array of plane
595 * info structs for this buffer
596 * @length: size in bytes of the buffer (NOT its payload) for single-plane
597 * buffers (when type != *_MPLANE); number of elements in the
598 * planes array for multi-plane buffers
599 * @input: input number from which the video data has has been captured
600 *
601 * Contains data exchanged by application and driver using one of the Streaming
602 * I/O methods.
603 */
521struct <link linkend="v4l2-buffer">v4l2_buffer</link> { 604struct <link linkend="v4l2-buffer">v4l2_buffer</link> {
522 __u32 index; 605 __u32 index;
523 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; 606 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
@@ -533,6 +616,7 @@ struct <link linkend="v4l2-buffer">v4l2_buffer</link> {
533 union { 616 union {
534 __u32 offset; 617 __u32 offset;
535 unsigned long userptr; 618 unsigned long userptr;
619 struct <link linkend="v4l2-plane">v4l2_plane</link> *planes;
536 } m; 620 } m;
537 __u32 length; 621 __u32 length;
538 __u32 input; 622 __u32 input;
@@ -1623,12 +1707,56 @@ struct <link linkend="v4l2-mpeg-vbi-fmt-ivtv">v4l2_mpeg_vbi_fmt_ivtv</link> {
1623 * A G G R E G A T E S T R U C T U R E S 1707 * A G G R E G A T E S T R U C T U R E S
1624 */ 1708 */
1625 1709
1626/* Stream data format 1710/**
1711 * struct <link linkend="v4l2-plane-pix-format">v4l2_plane_pix_format</link> - additional, per-plane format definition
1712 * @sizeimage: maximum size in bytes required for data, for which
1713 * this plane will be used
1714 * @bytesperline: distance in bytes between the leftmost pixels in two
1715 * adjacent lines
1716 */
1717struct <link linkend="v4l2-plane-pix-format">v4l2_plane_pix_format</link> {
1718 __u32 sizeimage;
1719 __u16 bytesperline;
1720 __u16 reserved[7];
1721} __attribute__ ((packed));
1722
1723/**
1724 * struct <link linkend="v4l2-pix-format-mplane">v4l2_pix_format_mplane</link> - multiplanar format definition
1725 * @width: image width in pixels
1726 * @height: image height in pixels
1727 * @pixelformat: little endian four character code (fourcc)
1728 * @field: field order (for interlaced video)
1729 * @colorspace: supplemental to pixelformat
1730 * @plane_fmt: per-plane information
1731 * @num_planes: number of planes for this format
1732 */
1733struct <link linkend="v4l2-pix-format-mplane">v4l2_pix_format_mplane</link> {
1734 __u32 width;
1735 __u32 height;
1736 __u32 pixelformat;
1737 enum <link linkend="v4l2-field">v4l2_field</link> field;
1738 enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> colorspace;
1739
1740 struct <link linkend="v4l2-plane-pix-format">v4l2_plane_pix_format</link> plane_fmt[VIDEO_MAX_PLANES];
1741 __u8 num_planes;
1742 __u8 reserved[11];
1743} __attribute__ ((packed));
1744
1745/**
1746 * struct <link linkend="v4l2-format">v4l2_format</link> - stream data format
1747 * @type: type of the data stream
1748 * @pix: definition of an image format
1749 * @pix_mp: definition of a multiplanar image format
1750 * @win: definition of an overlaid image
1751 * @vbi: raw VBI capture or output parameters
1752 * @sliced: sliced VBI capture or output parameters
1753 * @raw_data: placeholder for future extensions and custom formats
1627 */ 1754 */
1628struct <link linkend="v4l2-format">v4l2_format</link> { 1755struct <link linkend="v4l2-format">v4l2_format</link> {
1629 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; 1756 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
1630 union { 1757 union {
1631 struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> pix; /* V4L2_BUF_TYPE_VIDEO_CAPTURE */ 1758 struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> pix; /* V4L2_BUF_TYPE_VIDEO_CAPTURE */
1759 struct <link linkend="v4l2-pix-format-mplane">v4l2_pix_format_mplane</link> pix_mp; /* V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE */
1632 struct <link linkend="v4l2-window">v4l2_window</link> win; /* V4L2_BUF_TYPE_VIDEO_OVERLAY */ 1760 struct <link linkend="v4l2-window">v4l2_window</link> win; /* V4L2_BUF_TYPE_VIDEO_OVERLAY */
1633 struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> vbi; /* V4L2_BUF_TYPE_VBI_CAPTURE */ 1761 struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> vbi; /* V4L2_BUF_TYPE_VBI_CAPTURE */
1634 struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> sliced; /* V4L2_BUF_TYPE_SLICED_VBI_CAPTURE */ 1762 struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> sliced; /* V4L2_BUF_TYPE_SLICED_VBI_CAPTURE */
@@ -1636,7 +1764,6 @@ struct <link linkend="v4l2-format">v4l2_format</link> {
1636 } fmt; 1764 } fmt;
1637}; 1765};
1638 1766
1639
1640/* Stream type-dependent parameters 1767/* Stream type-dependent parameters
1641 */ 1768 */
1642struct <link linkend="v4l2-streamparm">v4l2_streamparm</link> { 1769struct <link linkend="v4l2-streamparm">v4l2_streamparm</link> {
@@ -1809,16 +1936,6 @@ struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> {
1809/* Reminder: when adding new ioctls please add support for them to 1936/* Reminder: when adding new ioctls please add support for them to
1810 drivers/media/video/v4l2-compat-ioctl32.c as well! */ 1937 drivers/media/video/v4l2-compat-ioctl32.c as well! */
1811 1938
1812#ifdef __OLD_VIDIOC_
1813/* for compatibility, will go away some day */
1814#define VIDIOC_OVERLAY_OLD _IOWR('V', 14, int)
1815#define VIDIOC_S_PARM_OLD _IOW('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>)
1816#define VIDIOC_S_CTRL_OLD _IOW('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>)
1817#define VIDIOC_G_AUDIO_OLD _IOWR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>)
1818#define VIDIOC_G_AUDOUT_OLD _IOWR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>)
1819#define VIDIOC_CROPCAP_OLD _IOR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>)
1820#endif
1821
1822#define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */ 1939#define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */
1823 1940
1824#endif /* __LINUX_VIDEODEV2_H */ 1941#endif /* __LINUX_VIDEODEV2_H */
diff --git a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
index 960d44615ca6..71d373b6d36a 100644
--- a/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
+++ b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
@@ -76,7 +76,9 @@ pixelformat</structfield> field.</entry>
76 <entry>Type of the data stream, set by the application. 76 <entry>Type of the data stream, set by the application.
77Only these types are valid here: 77Only these types are valid here:
78<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, 78<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
79<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
79<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, 80<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
81<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>,
80<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver 82<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
81defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> 83defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
82and higher.</entry> 84and higher.</entry>
diff --git a/Documentation/DocBook/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-g-fmt.xml
index 7c7d1b72c40d..a4ae59b664eb 100644
--- a/Documentation/DocBook/v4l/vidioc-g-fmt.xml
+++ b/Documentation/DocBook/v4l/vidioc-g-fmt.xml
@@ -60,11 +60,13 @@ application.</para>
60<structfield>type</structfield> field of a struct 60<structfield>type</structfield> field of a struct
61<structname>v4l2_format</structname> to the respective buffer (stream) 61<structname>v4l2_format</structname> to the respective buffer (stream)
62type. For example video capture devices use 62type. For example video capture devices use
63<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>. When the application 63<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
64<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
64calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to 65calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
65this structure the driver fills the respective member of the 66this structure the driver fills the respective member of the
66<structfield>fmt</structfield> union. In case of video capture devices 67<structfield>fmt</structfield> union. In case of video capture devices
67that is the &v4l2-pix-format; <structfield>pix</structfield> member. 68that is either the &v4l2-pix-format; <structfield>pix</structfield> or
69the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
68When the requested buffer type is not supported drivers return an 70When the requested buffer type is not supported drivers return an
69&EINVAL;.</para> 71&EINVAL;.</para>
70 72
@@ -134,6 +136,15 @@ devices.</entry>
134 </row> 136 </row>
135 <row> 137 <row>
136 <entry></entry> 138 <entry></entry>
139 <entry>&v4l2-pix-format-mplane;</entry>
140 <entry><structfield>pix_mp</structfield></entry>
141 <entry>Definition of an image format, see <xref
142 linkend="pixfmt" />, used by video capture and output
143devices that support the <link linkend="planar-apis">multi-planar
144version of the API</link>.</entry>
145 </row>
146 <row>
147 <entry></entry>
137 <entry>&v4l2-window;</entry> 148 <entry>&v4l2-window;</entry>
138 <entry><structfield>win</structfield></entry> 149 <entry><structfield>win</structfield></entry>
139 <entry>Definition of an overlaid image, see <xref 150 <entry>Definition of an overlaid image, see <xref
diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml
index ab691ebf3b93..f2b11f8a4031 100644
--- a/Documentation/DocBook/v4l/vidioc-qbuf.xml
+++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml
@@ -64,7 +64,8 @@ zero to the number of buffers allocated with &VIDIOC-REQBUFS;
64contents of the struct <structname>v4l2_buffer</structname> returned 64contents of the struct <structname>v4l2_buffer</structname> returned
65by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is 65by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
66intended for output (<structfield>type</structfield> is 66intended for output (<structfield>type</structfield> is
67<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or 67<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
68<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or
68<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also 69<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
69initialize the <structfield>bytesused</structfield>, 70initialize the <structfield>bytesused</structfield>,
70<structfield>field</structfield> and 71<structfield>field</structfield> and
@@ -75,7 +76,11 @@ supports capturing from specific video inputs and you want to specify a video
75input, then <structfield>flags</structfield> should be set to 76input, then <structfield>flags</structfield> should be set to
76<constant>V4L2_BUF_FLAG_INPUT</constant> and the field 77<constant>V4L2_BUF_FLAG_INPUT</constant> and the field
77<structfield>input</structfield> must be initialized to the desired input. 78<structfield>input</structfield> must be initialized to the desired input.
78The <structfield>reserved</structfield> field must be set to 0. 79The <structfield>reserved</structfield> field must be set to 0. When using
80the <link linkend="planar-apis">multi-planar API</link>, the
81<structfield>m.planes</structfield> field must contain a userspace pointer
82to a filled-in array of &v4l2-plane; and the <structfield>length</structfield>
83field must be set to the number of elements in that array.
79</para> 84</para>
80 85
81 <para>To enqueue a <link linkend="mmap">memory mapped</link> 86 <para>To enqueue a <link linkend="mmap">memory mapped</link>
@@ -93,10 +98,13 @@ structure the driver sets the
93buffer applications set the <structfield>memory</structfield> 98buffer applications set the <structfield>memory</structfield>
94field to <constant>V4L2_MEMORY_USERPTR</constant>, the 99field to <constant>V4L2_MEMORY_USERPTR</constant>, the
95<structfield>m.userptr</structfield> field to the address of the 100<structfield>m.userptr</structfield> field to the address of the
96buffer and <structfield>length</structfield> to its size. 101buffer and <structfield>length</structfield> to its size. When the multi-planar
97When <constant>VIDIOC_QBUF</constant> is called with a pointer to this 102API is used, <structfield>m.userptr</structfield> and
98structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant> 103<structfield>length</structfield> members of the passed array of &v4l2-plane;
99flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and 104have to be used instead. When <constant>VIDIOC_QBUF</constant> is called with
105a pointer to this structure the driver sets the
106<constant>V4L2_BUF_FLAG_QUEUED</constant> flag and clears the
107<constant>V4L2_BUF_FLAG_MAPPED</constant> and
100<constant>V4L2_BUF_FLAG_DONE</constant> flags in the 108<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
101<structfield>flags</structfield> field, or it returns an error code. 109<structfield>flags</structfield> field, or it returns an error code.
102This ioctl locks the memory pages of the buffer in physical memory, 110This ioctl locks the memory pages of the buffer in physical memory,
@@ -115,7 +123,9 @@ remaining fields or returns an error code. The driver may also set
115<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield> 123<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
116field. It indicates a non-critical (recoverable) streaming error. In such case 124field. It indicates a non-critical (recoverable) streaming error. In such case
117the application may continue as normal, but should be aware that data in the 125the application may continue as normal, but should be aware that data in the
118dequeued buffer might be corrupted.</para> 126dequeued buffer might be corrupted. When using the multi-planar API, the
127planes array does not have to be passed; the <structfield>m.planes</structfield>
128member must be set to NULL in that case.</para>
119 129
120 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no 130 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
121buffer is in the outgoing queue. When the 131buffer is in the outgoing queue. When the
diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml
index e649805a4908..5c104d42d31c 100644
--- a/Documentation/DocBook/v4l/vidioc-querybuf.xml
+++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml
@@ -61,6 +61,10 @@ buffer at any time after buffers have been allocated with the
61to the number of buffers allocated with &VIDIOC-REQBUFS; 61to the number of buffers allocated with &VIDIOC-REQBUFS;
62 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one. 62 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
63The <structfield>reserved</structfield> field should to set to 0. 63The <structfield>reserved</structfield> field should to set to 0.
64When using the <link linkend="planar-apis">multi-planar API</link>, the
65<structfield>m.planes</structfield> field must contain a userspace pointer to an
66array of &v4l2-plane; and the <structfield>length</structfield> field has
67to be set to the number of elements in that array.
64After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to 68After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
65 this structure drivers return an error code or fill the rest of 69 this structure drivers return an error code or fill the rest of
66the structure.</para> 70the structure.</para>
@@ -70,11 +74,13 @@ the structure.</para>
70<constant>V4L2_BUF_FLAG_QUEUED</constant> and 74<constant>V4L2_BUF_FLAG_QUEUED</constant> and
71<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The 75<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The
72<structfield>memory</structfield> field will be set to the current 76<structfield>memory</structfield> field will be set to the current
73I/O method, the <structfield>m.offset</structfield> 77I/O method. For the single-planar API, the <structfield>m.offset</structfield>
74contains the offset of the buffer from the start of the device memory, 78contains the offset of the buffer from the start of the device memory,
75the <structfield>length</structfield> field its size. The driver may 79the <structfield>length</structfield> field its size. For the multi-planar API,
76or may not set the remaining fields and flags, they are meaningless in 80fields <structfield>m.mem_offset</structfield> and
77this context.</para> 81<structfield>length</structfield> in the <structfield>m.planes</structfield>
82array elements will be used instead. The driver may or may not set the remaining
83fields and flags, they are meaningless in this context.</para>
78 84
79 <para>The <structname>v4l2_buffer</structname> structure is 85 <para>The <structname>v4l2_buffer</structname> structure is
80 specified in <xref linkend="buffer" />.</para> 86 specified in <xref linkend="buffer" />.</para>
diff --git a/Documentation/DocBook/v4l/vidioc-querycap.xml b/Documentation/DocBook/v4l/vidioc-querycap.xml
index d499da93a450..f29f1b86213c 100644
--- a/Documentation/DocBook/v4l/vidioc-querycap.xml
+++ b/Documentation/DocBook/v4l/vidioc-querycap.xml
@@ -142,16 +142,30 @@ this array to zero.</entry>
142 <row> 142 <row>
143 <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry> 143 <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
144 <entry>0x00000001</entry> 144 <entry>0x00000001</entry>
145 <entry>The device supports the <link 145 <entry>The device supports the single-planar API through the <link
146linkend="capture">Video Capture</link> interface.</entry> 146linkend="capture">Video Capture</link> interface.</entry>
147 </row> 147 </row>
148 <row> 148 <row>
149 <entry><constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant></entry>
150 <entry>0x00001000</entry>
151 <entry>The device supports the
152 <link linkend="planar-apis">multi-planar API</link> through the
153 <link linkend="capture">Video Capture</link> interface.</entry>
154 </row>
155 <row>
149 <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry> 156 <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry>
150 <entry>0x00000002</entry> 157 <entry>0x00000002</entry>
151 <entry>The device supports the <link 158 <entry>The device supports the single-planar API through the <link
152linkend="output">Video Output</link> interface.</entry> 159linkend="output">Video Output</link> interface.</entry>
153 </row> 160 </row>
154 <row> 161 <row>
162 <entry><constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant></entry>
163 <entry>0x00002000</entry>
164 <entry>The device supports the
165 <link linkend="planar-apis">multi-planar API</link> through the
166 <link linkend="output">Video Output</link> interface.</entry>
167 </row>
168 <row>
155 <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry> 169 <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
156 <entry>0x00000004</entry> 170 <entry>0x00000004</entry>
157 <entry>The device supports the <link 171 <entry>The device supports the <link
diff --git a/Documentation/DocBook/v4l/vidioc-streamon.xml b/Documentation/DocBook/v4l/vidioc-streamon.xml
index e42bff1f2c0a..75ed39bf4d2b 100644
--- a/Documentation/DocBook/v4l/vidioc-streamon.xml
+++ b/Documentation/DocBook/v4l/vidioc-streamon.xml
@@ -93,6 +93,15 @@ synchronize with other events.</para>
93been allocated (memory mapping) or enqueued (output) yet.</para> 93been allocated (memory mapping) or enqueued (output) yet.</para>
94 </listitem> 94 </listitem>
95 </varlistentry> 95 </varlistentry>
96 <varlistentry>
97 <term><errorcode>EPIPE</errorcode></term>
98 <listitem>
99 <para>The driver implements <link
100 linkend="pad-level-formats">pad-level format configuration</link> and
101 the pipeline configuration is invalid.
102 </para>
103 </listitem>
104 </varlistentry>
96 </variablelist> 105 </variablelist>
97 </refsect1> 106 </refsect1>
98</refentry> 107</refentry>
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml
new file mode 100644
index 000000000000..2f8f4f0a0235
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-interval.xml
@@ -0,0 +1,152 @@
1<refentry id="vidioc-subdev-enum-frame-interval">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</refname>
9 <refpurpose>Enumerate frame intervals</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct v4l2_subdev_frame_interval_enum *
19 <parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <note>
53 <title>Experimental</title>
54 <para>This is an <link linkend="experimental">experimental</link>
55 interface and may change in the future.</para>
56 </note>
57
58 <para>This ioctl lets applications enumerate available frame intervals on a
59 given sub-device pad. Frame intervals only makes sense for sub-devices that
60 can control the frame period on their own. This includes, for instance,
61 image sensors and TV tuners.</para>
62
63 <para>For the common use case of image sensors, the frame intervals
64 available on the sub-device output pad depend on the frame format and size
65 on the same pad. Applications must thus specify the desired format and size
66 when enumerating frame intervals.</para>
67
68 <para>To enumerate frame intervals applications initialize the
69 <structfield>index</structfield>, <structfield>pad</structfield>,
70 <structfield>code</structfield>, <structfield>width</structfield> and
71 <structfield>height</structfield> fields of
72 &v4l2-subdev-frame-interval-enum; and call the
73 <constant>VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL</constant> ioctl with a pointer
74 to this structure. Drivers fill the rest of the structure or return
75 an &EINVAL; if one of the input fields is invalid. All frame intervals are
76 enumerable by beginning at index zero and incrementing by one until
77 <errorcode>EINVAL</errorcode> is returned.</para>
78
79 <para>Available frame intervals may depend on the current 'try' formats
80 at other pads of the sub-device, as well as on the current active links. See
81 &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
82
83 <para>Sub-devices that support the frame interval enumeration ioctl should
84 implemented it on a single pad only. Its behaviour when supported on
85 multiple pads of the same sub-device is not defined.</para>
86
87 <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval-enum">
88 <title>struct <structname>v4l2_subdev_frame_interval_enum</structname></title>
89 <tgroup cols="3">
90 &cs-str;
91 <tbody valign="top">
92 <row>
93 <entry>__u32</entry>
94 <entry><structfield>index</structfield></entry>
95 <entry>Number of the format in the enumeration, set by the
96 application.</entry>
97 </row>
98 <row>
99 <entry>__u32</entry>
100 <entry><structfield>pad</structfield></entry>
101 <entry>Pad number as reported by the media controller API.</entry>
102 </row>
103 <row>
104 <entry>__u32</entry>
105 <entry><structfield>code</structfield></entry>
106 <entry>The media bus format code, as defined in
107 <xref linkend="v4l2-mbus-format" />.</entry>
108 </row>
109 <row>
110 <entry>__u32</entry>
111 <entry><structfield>width</structfield></entry>
112 <entry>Frame width, in pixels.</entry>
113 </row>
114 <row>
115 <entry>__u32</entry>
116 <entry><structfield>height</structfield></entry>
117 <entry>Frame height, in pixels.</entry>
118 </row>
119 <row>
120 <entry>&v4l2-fract;</entry>
121 <entry><structfield>interval</structfield></entry>
122 <entry>Period, in seconds, between consecutive video frames.</entry>
123 </row>
124 <row>
125 <entry>__u32</entry>
126 <entry><structfield>reserved</structfield>[9]</entry>
127 <entry>Reserved for future extensions. Applications and drivers must
128 set the array to zero.</entry>
129 </row>
130 </tbody>
131 </tgroup>
132 </table>
133 </refsect1>
134
135 <refsect1>
136 &return-value;
137
138 <variablelist>
139 <varlistentry>
140 <term><errorcode>EINVAL</errorcode></term>
141 <listitem>
142 <para>The &v4l2-subdev-frame-interval-enum;
143 <structfield>pad</structfield> references a non-existing pad, one of
144 the <structfield>code</structfield>, <structfield>width</structfield>
145 or <structfield>height</structfield> fields are invalid for the given
146 pad or the <structfield>index</structfield> field is out of bounds.
147 </para>
148 </listitem>
149 </varlistentry>
150 </variablelist>
151 </refsect1>
152</refentry>
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml
new file mode 100644
index 000000000000..79ce42b7c60c
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-frame-size.xml
@@ -0,0 +1,154 @@
1<refentry id="vidioc-subdev-enum-frame-size">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</refname>
9 <refpurpose>Enumerate media bus frame sizes</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct v4l2_subdev_frame_size_enum *
19 <parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <note>
53 <title>Experimental</title>
54 <para>This is an <link linkend="experimental">experimental</link>
55 interface and may change in the future.</para>
56 </note>
57
58 <para>This ioctl allows applications to enumerate all frame sizes
59 supported by a sub-device on the given pad for the given media bus format.
60 Supported formats can be retrieved with the &VIDIOC-SUBDEV-ENUM-MBUS-CODE;
61 ioctl.</para>
62
63 <para>To enumerate frame sizes applications initialize the
64 <structfield>pad</structfield>, <structfield>code</structfield> and
65 <structfield>index</structfield> fields of the
66 &v4l2-subdev-mbus-code-enum; and call the
67 <constant>VIDIOC_SUBDEV_ENUM_FRAME_SIZE</constant> ioctl with a pointer to
68 the structure. Drivers fill the minimum and maximum frame sizes or return
69 an &EINVAL; if one of the input parameters is invalid.</para>
70
71 <para>Sub-devices that only support discrete frame sizes (such as most
72 sensors) will return one or more frame sizes with identical minimum and
73 maximum values.</para>
74
75 <para>Not all possible sizes in given [minimum, maximum] ranges need to be
76 supported. For instance, a scaler that uses a fixed-point scaling ratio
77 might not be able to produce every frame size between the minimum and
78 maximum values. Applications must use the &VIDIOC-SUBDEV-S-FMT; ioctl to
79 try the sub-device for an exact supported frame size.</para>
80
81 <para>Available frame sizes may depend on the current 'try' formats at other
82 pads of the sub-device, as well as on the current active links and the
83 current values of V4L2 controls. See &VIDIOC-SUBDEV-G-FMT; for more
84 information about try formats.</para>
85
86 <table pgwide="1" frame="none" id="v4l2-subdev-frame-size-enum">
87 <title>struct <structname>v4l2_subdev_frame_size_enum</structname></title>
88 <tgroup cols="3">
89 &cs-str;
90 <tbody valign="top">
91 <row>
92 <entry>__u32</entry>
93 <entry><structfield>index</structfield></entry>
94 <entry>Number of the format in the enumeration, set by the
95 application.</entry>
96 </row>
97 <row>
98 <entry>__u32</entry>
99 <entry><structfield>pad</structfield></entry>
100 <entry>Pad number as reported by the media controller API.</entry>
101 </row>
102 <row>
103 <entry>__u32</entry>
104 <entry><structfield>code</structfield></entry>
105 <entry>The media bus format code, as defined in
106 <xref linkend="v4l2-mbus-format" />.</entry>
107 </row>
108 <row>
109 <entry>__u32</entry>
110 <entry><structfield>min_width</structfield></entry>
111 <entry>Minimum frame width, in pixels.</entry>
112 </row>
113 <row>
114 <entry>__u32</entry>
115 <entry><structfield>max_width</structfield></entry>
116 <entry>Maximum frame width, in pixels.</entry>
117 </row>
118 <row>
119 <entry>__u32</entry>
120 <entry><structfield>min_height</structfield></entry>
121 <entry>Minimum frame height, in pixels.</entry>
122 </row>
123 <row>
124 <entry>__u32</entry>
125 <entry><structfield>max_height</structfield></entry>
126 <entry>Maximum frame height, in pixels.</entry>
127 </row>
128 <row>
129 <entry>__u32</entry>
130 <entry><structfield>reserved</structfield>[9]</entry>
131 <entry>Reserved for future extensions. Applications and drivers must
132 set the array to zero.</entry>
133 </row>
134 </tbody>
135 </tgroup>
136 </table>
137 </refsect1>
138
139 <refsect1>
140 &return-value;
141
142 <variablelist>
143 <varlistentry>
144 <term><errorcode>EINVAL</errorcode></term>
145 <listitem>
146 <para>The &v4l2-subdev-frame-size-enum; <structfield>pad</structfield>
147 references a non-existing pad, the <structfield>code</structfield> is
148 invalid for the given pad or the <structfield>index</structfield>
149 field is out of bounds.</para>
150 </listitem>
151 </varlistentry>
152 </variablelist>
153 </refsect1>
154</refentry>
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml b/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml
new file mode 100644
index 000000000000..a6b3432449f6
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-enum-mbus-code.xml
@@ -0,0 +1,119 @@
1<refentry id="vidioc-subdev-enum-mbus-code">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_ENUM_MBUS_CODE</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_ENUM_MBUS_CODE</refname>
9 <refpurpose>Enumerate media bus formats</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct v4l2_subdev_mbus_code_enum *
19 <parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>VIDIOC_SUBDEV_ENUM_MBUS_CODE</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <note>
53 <title>Experimental</title>
54 <para>This is an <link linkend="experimental">experimental</link>
55 interface and may change in the future.</para>
56 </note>
57
58 <para>To enumerate media bus formats available at a given sub-device pad
59 applications initialize the <structfield>pad</structfield> and
60 <structfield>index</structfield> fields of &v4l2-subdev-mbus-code-enum; and
61 call the <constant>VIDIOC_SUBDEV_ENUM_MBUS_CODE</constant> ioctl with a
62 pointer to this structure. Drivers fill the rest of the structure or return
63 an &EINVAL; if either the <structfield>pad</structfield> or
64 <structfield>index</structfield> are invalid. All media bus formats are
65 enumerable by beginning at index zero and incrementing by one until
66 <errorcode>EINVAL</errorcode> is returned.</para>
67
68 <para>Available media bus formats may depend on the current 'try' formats
69 at other pads of the sub-device, as well as on the current active links. See
70 &VIDIOC-SUBDEV-G-FMT; for more information about the try formats.</para>
71
72 <table pgwide="1" frame="none" id="v4l2-subdev-mbus-code-enum">
73 <title>struct <structname>v4l2_subdev_mbus_code_enum</structname></title>
74 <tgroup cols="3">
75 &cs-str;
76 <tbody valign="top">
77 <row>
78 <entry>__u32</entry>
79 <entry><structfield>pad</structfield></entry>
80 <entry>Pad number as reported by the media controller API.</entry>
81 </row>
82 <row>
83 <entry>__u32</entry>
84 <entry><structfield>index</structfield></entry>
85 <entry>Number of the format in the enumeration, set by the
86 application.</entry>
87 </row>
88 <row>
89 <entry>__u32</entry>
90 <entry><structfield>code</structfield></entry>
91 <entry>The media bus format code, as defined in
92 <xref linkend="v4l2-mbus-format" />.</entry>
93 </row>
94 <row>
95 <entry>__u32</entry>
96 <entry><structfield>reserved</structfield>[9]</entry>
97 <entry>Reserved for future extensions. Applications and drivers must
98 set the array to zero.</entry>
99 </row>
100 </tbody>
101 </tgroup>
102 </table>
103 </refsect1>
104
105 <refsect1>
106 &return-value;
107
108 <variablelist>
109 <varlistentry>
110 <term><errorcode>EINVAL</errorcode></term>
111 <listitem>
112 <para>The &v4l2-subdev-mbus-code-enum; <structfield>pad</structfield>
113 references a non-existing pad, or the <structfield>index</structfield>
114 field is out of bounds.</para>
115 </listitem>
116 </varlistentry>
117 </variablelist>
118 </refsect1>
119</refentry>
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml b/Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml
new file mode 100644
index 000000000000..06197323a8cc
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-g-crop.xml
@@ -0,0 +1,155 @@
1<refentry id="vidioc-subdev-g-crop">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_G_CROP</refname>
9 <refname>VIDIOC_SUBDEV_S_CROP</refname>
10 <refpurpose>Get or set the crop rectangle on a subdev pad</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 <funcsynopsis>
23 <funcprototype>
24 <funcdef>int <function>ioctl</function></funcdef>
25 <paramdef>int <parameter>fd</parameter></paramdef>
26 <paramdef>int <parameter>request</parameter></paramdef>
27 <paramdef>const struct v4l2_subdev_crop *<parameter>argp</parameter></paramdef>
28 </funcprototype>
29 </funcsynopsis>
30 </refsynopsisdiv>
31
32 <refsect1>
33 <title>Arguments</title>
34
35 <variablelist>
36 <varlistentry>
37 <term><parameter>fd</parameter></term>
38 <listitem>
39 <para>&fd;</para>
40 </listitem>
41 </varlistentry>
42 <varlistentry>
43 <term><parameter>request</parameter></term>
44 <listitem>
45 <para>VIDIOC_SUBDEV_G_CROP, VIDIOC_SUBDEV_S_CROP</para>
46 </listitem>
47 </varlistentry>
48 <varlistentry>
49 <term><parameter>argp</parameter></term>
50 <listitem>
51 <para></para>
52 </listitem>
53 </varlistentry>
54 </variablelist>
55 </refsect1>
56
57 <refsect1>
58 <title>Description</title>
59
60 <note>
61 <title>Experimental</title>
62 <para>This is an <link linkend="experimental">experimental</link>
63 interface and may change in the future.</para>
64 </note>
65
66 <para>To retrieve the current crop rectangle applications set the
67 <structfield>pad</structfield> field of a &v4l2-subdev-crop; to the
68 desired pad number as reported by the media API and the
69 <structfield>which</structfield> field to
70 <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. They then call the
71 <constant>VIDIOC_SUBDEV_G_CROP</constant> ioctl with a pointer to this
72 structure. The driver fills the members of the <structfield>rect</structfield>
73 field or returns &EINVAL; if the input arguments are invalid, or if cropping
74 is not supported on the given pad.</para>
75
76 <para>To change the current crop rectangle applications set both the
77 <structfield>pad</structfield> and <structfield>which</structfield> fields
78 and all members of the <structfield>rect</structfield> field. They then call
79 the <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctl with a pointer to this
80 structure. The driver verifies the requested crop rectangle, adjusts it
81 based on the hardware capabilities and configures the device. Upon return
82 the &v4l2-subdev-crop; contains the current format as would be returned
83 by a <constant>VIDIOC_SUBDEV_G_CROP</constant> call.</para>
84
85 <para>Applications can query the device capabilities by setting the
86 <structfield>which</structfield> to
87 <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' crop
88 rectangles are not applied to the device by the driver, but are mangled
89 exactly as active crop rectangles and stored in the sub-device file handle.
90 Two applications querying the same sub-device would thus not interact with
91 each other.</para>
92
93 <para>Drivers must not return an error solely because the requested crop
94 rectangle doesn't match the device capabilities. They must instead modify
95 the rectangle to match what the hardware can provide. The modified format
96 should be as close as possible to the original request.</para>
97
98 <table pgwide="1" frame="none" id="v4l2-subdev-crop">
99 <title>struct <structname>v4l2_subdev_crop</structname></title>
100 <tgroup cols="3">
101 &cs-str;
102 <tbody valign="top">
103 <row>
104 <entry>__u32</entry>
105 <entry><structfield>pad</structfield></entry>
106 <entry>Pad number as reported by the media framework.</entry>
107 </row>
108 <row>
109 <entry>__u32</entry>
110 <entry><structfield>which</structfield></entry>
111 <entry>Crop rectangle to get or set, from
112 &v4l2-subdev-format-whence;.</entry>
113 </row>
114 <row>
115 <entry>&v4l2-rect;</entry>
116 <entry><structfield>rect</structfield></entry>
117 <entry>Crop rectangle boundaries, in pixels.</entry>
118 </row>
119 <row>
120 <entry>__u32</entry>
121 <entry><structfield>reserved</structfield>[8]</entry>
122 <entry>Reserved for future extensions. Applications and drivers must
123 set the array to zero.</entry>
124 </row>
125 </tbody>
126 </tgroup>
127 </table>
128 </refsect1>
129
130 <refsect1>
131 &return-value;
132
133 <variablelist>
134 <varlistentry>
135 <term><errorcode>EBUSY</errorcode></term>
136 <listitem>
137 <para>The crop rectangle can't be changed because the pad is currently
138 busy. This can be caused, for instance, by an active video stream on
139 the pad. The ioctl must not be retried without performing another
140 action to fix the problem first. Only returned by
141 <constant>VIDIOC_SUBDEV_S_CROP</constant></para>
142 </listitem>
143 </varlistentry>
144 <varlistentry>
145 <term><errorcode>EINVAL</errorcode></term>
146 <listitem>
147 <para>The &v4l2-subdev-crop; <structfield>pad</structfield>
148 references a non-existing pad, the <structfield>which</structfield>
149 field references a non-existing format, or cropping is not supported
150 on the given subdev pad.</para>
151 </listitem>
152 </varlistentry>
153 </variablelist>
154 </refsect1>
155</refentry>
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml
new file mode 100644
index 000000000000..f367c570c530
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-g-fmt.xml
@@ -0,0 +1,180 @@
1<refentry id="vidioc-subdev-g-fmt">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_G_FMT</refname>
9 <refname>VIDIOC_SUBDEV_S_FMT</refname>
10 <refpurpose>Get or set the data format on a subdev pad</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct v4l2_subdev_format *<parameter>argp</parameter>
20 </paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 </refsynopsisdiv>
24
25 <refsect1>
26 <title>Arguments</title>
27
28 <variablelist>
29 <varlistentry>
30 <term><parameter>fd</parameter></term>
31 <listitem>
32 <para>&fd;</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><parameter>request</parameter></term>
37 <listitem>
38 <para>VIDIOC_SUBDEV_G_FMT, VIDIOC_SUBDEV_S_FMT</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para></para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <note>
54 <title>Experimental</title>
55 <para>This is an <link linkend="experimental">experimental</link>
56 interface and may change in the future.</para>
57 </note>
58
59 <para>These ioctls are used to negotiate the frame format at specific
60 subdev pads in the image pipeline.</para>
61
62 <para>To retrieve the current format applications set the
63 <structfield>pad</structfield> field of a &v4l2-subdev-format; to the
64 desired pad number as reported by the media API and the
65 <structfield>which</structfield> field to
66 <constant>V4L2_SUBDEV_FORMAT_ACTIVE</constant>. When they call the
67 <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl with a pointer to this
68 structure the driver fills the members of the <structfield>format</structfield>
69 field.</para>
70
71 <para>To change the current format applications set both the
72 <structfield>pad</structfield> and <structfield>which</structfield> fields
73 and all members of the <structfield>format</structfield> field. When they
74 call the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl with a pointer to this
75 structure the driver verifies the requested format, adjusts it based on the
76 hardware capabilities and configures the device. Upon return the
77 &v4l2-subdev-format; contains the current format as would be returned by a
78 <constant>VIDIOC_SUBDEV_G_FMT</constant> call.</para>
79
80 <para>Applications can query the device capabilities by setting the
81 <structfield>which</structfield> to
82 <constant>V4L2_SUBDEV_FORMAT_TRY</constant>. When set, 'try' formats are not
83 applied to the device by the driver, but are changed exactly as active
84 formats and stored in the sub-device file handle. Two applications querying
85 the same sub-device would thus not interact with each other.</para>
86
87 <para>For instance, to try a format at the output pad of a sub-device,
88 applications would first set the try format at the sub-device input with the
89 <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl. They would then either
90 retrieve the default format at the output pad with the
91 <constant>VIDIOC_SUBDEV_G_FMT</constant> ioctl, or set the desired output
92 pad format with the <constant>VIDIOC_SUBDEV_S_FMT</constant> ioctl and check
93 the returned value.</para>
94
95 <para>Try formats do not depend on active formats, but can depend on the
96 current links configuration or sub-device controls value. For instance, a
97 low-pass noise filter might crop pixels at the frame boundaries, modifying
98 its output frame size.</para>
99
100 <para>Drivers must not return an error solely because the requested format
101 doesn't match the device capabilities. They must instead modify the format
102 to match what the hardware can provide. The modified format should be as
103 close as possible to the original request.</para>
104
105 <table pgwide="1" frame="none" id="v4l2-subdev-format">
106 <title>struct <structname>v4l2_subdev_format</structname></title>
107 <tgroup cols="3">
108 &cs-str;
109 <tbody valign="top">
110 <row>
111 <entry>__u32</entry>
112 <entry><structfield>pad</structfield></entry>
113 <entry>Pad number as reported by the media controller API.</entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>which</structfield></entry>
118 <entry>Format to modified, from &v4l2-subdev-format-whence;.</entry>
119 </row>
120 <row>
121 <entry>&v4l2-mbus-framefmt;</entry>
122 <entry><structfield>format</structfield></entry>
123 <entry>Definition of an image format, see <xref
124 linkend="v4l2-mbus-framefmt" /> for details.</entry>
125 </row>
126 <row>
127 <entry>__u32</entry>
128 <entry><structfield>reserved</structfield>[8]</entry>
129 <entry>Reserved for future extensions. Applications and drivers must
130 set the array to zero.</entry>
131 </row>
132 </tbody>
133 </tgroup>
134 </table>
135
136 <table pgwide="1" frame="none" id="v4l2-subdev-format-whence">
137 <title>enum <structname>v4l2_subdev_format_whence</structname></title>
138 <tgroup cols="3">
139 &cs-def;
140 <tbody valign="top">
141 <row>
142 <entry>V4L2_SUBDEV_FORMAT_TRY</entry>
143 <entry>0</entry>
144 <entry>Try formats, used for querying device capabilities.</entry>
145 </row>
146 <row>
147 <entry>V4L2_SUBDEV_FORMAT_ACTIVE</entry>
148 <entry>1</entry>
149 <entry>Active formats, applied to the hardware.</entry>
150 </row>
151 </tbody>
152 </tgroup>
153 </table>
154 </refsect1>
155
156 <refsect1>
157 &return-value;
158
159 <variablelist>
160 <varlistentry>
161 <term><errorcode>EBUSY</errorcode></term>
162 <listitem>
163 <para>The format can't be changed because the pad is currently busy.
164 This can be caused, for instance, by an active video stream on the
165 pad. The ioctl must not be retried without performing another action
166 to fix the problem first. Only returned by
167 <constant>VIDIOC_SUBDEV_S_FMT</constant></para>
168 </listitem>
169 </varlistentry>
170 <varlistentry>
171 <term><errorcode>EINVAL</errorcode></term>
172 <listitem>
173 <para>The &v4l2-subdev-format; <structfield>pad</structfield>
174 references a non-existing pad, or the <structfield>which</structfield>
175 field references a non-existing format.</para>
176 </listitem>
177 </varlistentry>
178 </variablelist>
179 </refsect1>
180</refentry>
diff --git a/Documentation/DocBook/v4l/vidioc-subdev-g-frame-interval.xml b/Documentation/DocBook/v4l/vidioc-subdev-g-frame-interval.xml
new file mode 100644
index 000000000000..0bc3ea22d31f
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-subdev-g-frame-interval.xml
@@ -0,0 +1,141 @@
1<refentry id="vidioc-subdev-g-frame-interval">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBDEV_G_FRAME_INTERVAL</refname>
9 <refname>VIDIOC_SUBDEV_S_FRAME_INTERVAL</refname>
10 <refpurpose>Get or set the frame interval on a subdev pad</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct v4l2_subdev_frame_interval *<parameter>argp</parameter>
20 </paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 </refsynopsisdiv>
24
25 <refsect1>
26 <title>Arguments</title>
27
28 <variablelist>
29 <varlistentry>
30 <term><parameter>fd</parameter></term>
31 <listitem>
32 <para>&fd;</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><parameter>request</parameter></term>
37 <listitem>
38 <para>VIDIOC_SUBDEV_G_FRAME_INTERVAL, VIDIOC_SUBDEV_S_FRAME_INTERVAL</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para></para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <note>
54 <title>Experimental</title>
55 <para>This is an <link linkend="experimental">experimental</link>
56 interface and may change in the future.</para>
57 </note>
58
59 <para>These ioctls are used to get and set the frame interval at specific
60 subdev pads in the image pipeline. The frame interval only makes sense for
61 sub-devices that can control the frame period on their own. This includes,
62 for instance, image sensors and TV tuners. Sub-devices that don't support
63 frame intervals must not implement these ioctls.</para>
64
65 <para>To retrieve the current frame interval applications set the
66 <structfield>pad</structfield> field of a &v4l2-subdev-frame-interval; to
67 the desired pad number as reported by the media controller API. When they
68 call the <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> ioctl with a
69 pointer to this structure the driver fills the members of the
70 <structfield>interval</structfield> field.</para>
71
72 <para>To change the current frame interval applications set both the
73 <structfield>pad</structfield> field and all members of the
74 <structfield>interval</structfield> field. When they call the
75 <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant> ioctl with a pointer to
76 this structure the driver verifies the requested interval, adjusts it based
77 on the hardware capabilities and configures the device. Upon return the
78 &v4l2-subdev-frame-interval; contains the current frame interval as would be
79 returned by a <constant>VIDIOC_SUBDEV_G_FRAME_INTERVAL</constant> call.
80 </para>
81
82 <para>Drivers must not return an error solely because the requested interval
83 doesn't match the device capabilities. They must instead modify the interval
84 to match what the hardware can provide. The modified interval should be as
85 close as possible to the original request.</para>
86
87 <para>Sub-devices that support the frame interval ioctls should implement
88 them on a single pad only. Their behaviour when supported on multiple pads
89 of the same sub-device is not defined.</para>
90
91 <table pgwide="1" frame="none" id="v4l2-subdev-frame-interval">
92 <title>struct <structname>v4l2_subdev_frame_interval</structname></title>
93 <tgroup cols="3">
94 &cs-str;
95 <tbody valign="top">
96 <row>
97 <entry>__u32</entry>
98 <entry><structfield>pad</structfield></entry>
99 <entry>Pad number as reported by the media controller API.</entry>
100 </row>
101 <row>
102 <entry>&v4l2-fract;</entry>
103 <entry><structfield>interval</structfield></entry>
104 <entry>Period, in seconds, between consecutive video frames.</entry>
105 </row>
106 <row>
107 <entry>__u32</entry>
108 <entry><structfield>reserved</structfield>[9]</entry>
109 <entry>Reserved for future extensions. Applications and drivers must
110 set the array to zero.</entry>
111 </row>
112 </tbody>
113 </tgroup>
114 </table>
115 </refsect1>
116
117 <refsect1>
118 &return-value;
119
120 <variablelist>
121 <varlistentry>
122 <term><errorcode>EBUSY</errorcode></term>
123 <listitem>
124 <para>The frame interval can't be changed because the pad is currently
125 busy. This can be caused, for instance, by an active video stream on
126 the pad. The ioctl must not be retried without performing another
127 action to fix the problem first. Only returned by
128 <constant>VIDIOC_SUBDEV_S_FRAME_INTERVAL</constant></para>
129 </listitem>
130 </varlistentry>
131 <varlistentry>
132 <term><errorcode>EINVAL</errorcode></term>
133 <listitem>
134 <para>The &v4l2-subdev-frame-interval; <structfield>pad</structfield>
135 references a non-existing pad, or the pad doesn't support frame
136 intervals.</para>
137 </listitem>
138 </varlistentry>
139 </variablelist>
140 </refsect1>
141</refentry>
diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware
index 59690de8ebfe..3348d313fbe0 100644
--- a/Documentation/dvb/get_dvb_firmware
+++ b/Documentation/dvb/get_dvb_firmware
@@ -556,6 +556,9 @@ sub ngene {
556 my $hash1 = "d798d5a757121174f0dbc5f2833c0c85"; 556 my $hash1 = "d798d5a757121174f0dbc5f2833c0c85";
557 my $file2 = "ngene_17.fw"; 557 my $file2 = "ngene_17.fw";
558 my $hash2 = "26b687136e127b8ac24b81e0eeafc20b"; 558 my $hash2 = "26b687136e127b8ac24b81e0eeafc20b";
559 my $url2 = "http://l4m-daten.de/downloads/firmware/dvb-s2/linux/all/";
560 my $file3 = "ngene_18.fw";
561 my $hash3 = "ebce3ea769a53e3e0b0197c3b3f127e3";
559 562
560 checkstandard(); 563 checkstandard();
561 564
@@ -565,7 +568,10 @@ sub ngene {
565 wgetfile($file2, $url . $file2); 568 wgetfile($file2, $url . $file2);
566 verify($file2, $hash2); 569 verify($file2, $hash2);
567 570
568 "$file1, $file2"; 571 wgetfile($file3, $url2 . $file3);
572 verify($file3, $hash3);
573
574 "$file1, $file2, $file3";
569} 575}
570 576
571sub az6027{ 577sub az6027{
diff --git a/Documentation/dvb/lmedm04.txt b/Documentation/dvb/lmedm04.txt
index 641886504201..10b5f0411386 100644
--- a/Documentation/dvb/lmedm04.txt
+++ b/Documentation/dvb/lmedm04.txt
@@ -4,7 +4,7 @@ following file(s) to this directory.
4for DM04+/QQBOX LME2510C (Sharp 7395 Tuner) 4for DM04+/QQBOX LME2510C (Sharp 7395 Tuner)
5------------------------------------------- 5-------------------------------------------
6 6
7The Sharp 7395 driver can be found in windows/system32/driver 7The Sharp 7395 driver can be found in windows/system32/drivers
8 8
9US2A0D.sys (dated 17 Mar 2009) 9US2A0D.sys (dated 17 Mar 2009)
10 10
@@ -44,7 +44,7 @@ and run
44 44
45 45
46Other LG firmware can be extracted manually from US280D.sys 46Other LG firmware can be extracted manually from US280D.sys
47only found in windows/system32/driver. 47only found in windows/system32/drivers
48 48
49dd if=US280D.sys ibs=1 skip=42360 count=3924 of=dvb-usb-lme2510-lg.fw 49dd if=US280D.sys ibs=1 skip=42360 count=3924 of=dvb-usb-lme2510-lg.fw
50 50
@@ -55,4 +55,16 @@ dd if=US280D.sys ibs=1 skip=35200 count=3850 of=dvb-usb-lme2510c-lg.fw
55 55
56--------------------------------------------------------------------- 56---------------------------------------------------------------------
57 57
58The Sharp 0194 tuner driver can be found in windows/system32/drivers
59
60US290D.sys (dated 09 Apr 2009)
61
62For LME2510
63dd if=US290D.sys ibs=1 skip=36856 count=3976 of=dvb-usb-lme2510-s0194.fw
64
65
66For LME2510C
67dd if=US290D.sys ibs=1 skip=33152 count=3697 of=dvb-usb-lme2510c-s0194.fw
68
69
58Copy the firmware file(s) to /lib/firmware 70Copy the firmware file(s) to /lib/firmware
diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt
index 75c37e4c3d75..274b32d12532 100644
--- a/Documentation/feature-removal-schedule.txt
+++ b/Documentation/feature-removal-schedule.txt
@@ -108,42 +108,6 @@ Who: Pavel Machek <pavel@ucw.cz>
108 108
109--------------------------- 109---------------------------
110 110
111What: Video4Linux obsolete drivers using V4L1 API
112When: kernel 2.6.39
113Files: drivers/staging/se401/* drivers/staging/usbvideo/*
114Check: drivers/staging/se401/se401.c drivers/staging/usbvideo/usbvideo.c
115Why: There are some drivers still using V4L1 API, despite all efforts we've done
116 to migrate. Those drivers are for obsolete hardware that the old maintainer
117 didn't care (or not have the hardware anymore), and that no other developer
118 could find any hardware to buy. They probably have no practical usage today,
119 and people with such old hardware could probably keep using an older version
120 of the kernel. Those drivers will be moved to staging on 2.6.38 and, if nobody
121 cares enough to port and test them with V4L2 API, they'll be removed on 2.6.39.
122Who: Mauro Carvalho Chehab <mchehab@infradead.org>
123
124---------------------------
125
126What: Video4Linux: Remove obsolete ioctl's
127When: kernel 2.6.39
128Files: include/media/videodev2.h
129Why: Some ioctl's were defined wrong on 2.6.2 and 2.6.6, using the wrong
130 type of R/W arguments. They were fixed, but the old ioctl names are
131 still there, maintained to avoid breaking binary compatibility:
132 #define VIDIOC_OVERLAY_OLD _IOWR('V', 14, int)
133 #define VIDIOC_S_PARM_OLD _IOW('V', 22, struct v4l2_streamparm)
134 #define VIDIOC_S_CTRL_OLD _IOW('V', 28, struct v4l2_control)
135 #define VIDIOC_G_AUDIO_OLD _IOWR('V', 33, struct v4l2_audio)
136 #define VIDIOC_G_AUDOUT_OLD _IOWR('V', 49, struct v4l2_audioout)
137 #define VIDIOC_CROPCAP_OLD _IOR('V', 58, struct v4l2_cropcap)
138 There's no sense on preserving those forever, as it is very doubtful
139 that someone would try to use a such old binary with a modern kernel.
140 Removing them will allow us to remove some magic done at the V4L ioctl
141 handler.
142
143Who: Mauro Carvalho Chehab <mchehab@infradead.org>
144
145---------------------------
146
147What: sys_sysctl 111What: sys_sysctl
148When: September 2010 112When: September 2010
149Option: CONFIG_SYSCTL_SYSCALL 113Option: CONFIG_SYSCTL_SYSCALL
diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt
index e68543f767d5..a0a5d82b6b0b 100644
--- a/Documentation/ioctl/ioctl-number.txt
+++ b/Documentation/ioctl/ioctl-number.txt
@@ -273,6 +273,7 @@ Code Seq#(hex) Include File Comments
273'z' 40-7F CAN bus card conflict! 273'z' 40-7F CAN bus card conflict!
274 <mailto:oe@port.de> 274 <mailto:oe@port.de>
275'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! 275'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict!
276'|' 00-7F linux/media.h
2760x80 00-1F linux/fb.h 2770x80 00-1F linux/fb.h
2770x89 00-06 arch/x86/include/asm/sockios.h 2780x89 00-06 arch/x86/include/asm/sockios.h
2780x89 0B-DF linux/sockios.h 2790x89 0B-DF linux/sockios.h
diff --git a/Documentation/media-framework.txt b/Documentation/media-framework.txt
new file mode 100644
index 000000000000..fd48add02cb0
--- /dev/null
+++ b/Documentation/media-framework.txt
@@ -0,0 +1,353 @@
1Linux kernel media framework
2============================
3
4This document describes the Linux kernel media framework, its data structures,
5functions and their usage.
6
7
8Introduction
9------------
10
11The media controller API is documented in DocBook format in
12Documentation/DocBook/v4l/media-controller.xml. This document will focus on
13the kernel-side implementation of the media framework.
14
15
16Abstract media device model
17---------------------------
18
19Discovering a device internal topology, and configuring it at runtime, is one
20of the goals of the media framework. To achieve this, hardware devices are
21modeled as an oriented graph of building blocks called entities connected
22through pads.
23
24An entity is a basic media hardware building block. It can correspond to
25a large variety of logical blocks such as physical hardware devices
26(CMOS sensor for instance), logical hardware devices (a building block
27in a System-on-Chip image processing pipeline), DMA channels or physical
28connectors.
29
30A pad is a connection endpoint through which an entity can interact with
31other entities. Data (not restricted to video) produced by an entity
32flows from the entity's output to one or more entity inputs. Pads should
33not be confused with physical pins at chip boundaries.
34
35A link is a point-to-point oriented connection between two pads, either
36on the same entity or on different entities. Data flows from a source
37pad to a sink pad.
38
39
40Media device
41------------
42
43A media device is represented by a struct media_device instance, defined in
44include/media/media-device.h. Allocation of the structure is handled by the
45media device driver, usually by embedding the media_device instance in a
46larger driver-specific structure.
47
48Drivers register media device instances by calling
49
50 media_device_register(struct media_device *mdev);
51
52The caller is responsible for initializing the media_device structure before
53registration. The following fields must be set:
54
55 - dev must point to the parent device (usually a pci_dev, usb_interface or
56 platform_device instance).
57
58 - model must be filled with the device model name as a NUL-terminated UTF-8
59 string. The device/model revision must not be stored in this field.
60
61The following fields are optional:
62
63 - serial is a unique serial number stored as a NUL-terminated ASCII string.
64 The field is big enough to store a GUID in text form. If the hardware
65 doesn't provide a unique serial number this field must be left empty.
66
67 - bus_info represents the location of the device in the system as a
68 NUL-terminated ASCII string. For PCI/PCIe devices bus_info must be set to
69 "PCI:" (or "PCIe:") followed by the value of pci_name(). For USB devices,
70 the usb_make_path() function must be used. This field is used by
71 applications to distinguish between otherwise identical devices that don't
72 provide a serial number.
73
74 - hw_revision is the hardware device revision in a driver-specific format.
75 When possible the revision should be formatted with the KERNEL_VERSION
76 macro.
77
78 - driver_version is formatted with the KERNEL_VERSION macro. The version
79 minor must be incremented when new features are added to the userspace API
80 without breaking binary compatibility. The version major must be
81 incremented when binary compatibility is broken.
82
83Upon successful registration a character device named media[0-9]+ is created.
84The device major and minor numbers are dynamic. The model name is exported as
85a sysfs attribute.
86
87Drivers unregister media device instances by calling
88
89 media_device_unregister(struct media_device *mdev);
90
91Unregistering a media device that hasn't been registered is *NOT* safe.
92
93
94Entities, pads and links
95------------------------
96
97- Entities
98
99Entities are represented by a struct media_entity instance, defined in
100include/media/media-entity.h. The structure is usually embedded into a
101higher-level structure, such as a v4l2_subdev or video_device instance,
102although drivers can allocate entities directly.
103
104Drivers initialize entities by calling
105
106 media_entity_init(struct media_entity *entity, u16 num_pads,
107 struct media_pad *pads, u16 extra_links);
108
109The media_entity name, type, flags, revision and group_id fields can be
110initialized before or after calling media_entity_init. Entities embedded in
111higher-level standard structures can have some of those fields set by the
112higher-level framework.
113
114As the number of pads is known in advance, the pads array is not allocated
115dynamically but is managed by the entity driver. Most drivers will embed the
116pads array in a driver-specific structure, avoiding dynamic allocation.
117
118Drivers must set the direction of every pad in the pads array before calling
119media_entity_init. The function will initialize the other pads fields.
120
121Unlike the number of pads, the total number of links isn't always known in
122advance by the entity driver. As an initial estimate, media_entity_init
123pre-allocates a number of links equal to the number of pads plus an optional
124number of extra links. The links array will be reallocated if it grows beyond
125the initial estimate.
126
127Drivers register entities with a media device by calling
128
129 media_device_register_entity(struct media_device *mdev,
130 struct media_entity *entity);
131
132Entities are identified by a unique positive integer ID. Drivers can provide an
133ID by filling the media_entity id field prior to registration, or request the
134media controller framework to assign an ID automatically. Drivers that provide
135IDs manually must ensure that all IDs are unique. IDs are not guaranteed to be
136contiguous even when they are all assigned automatically by the framework.
137
138Drivers unregister entities by calling
139
140 media_device_unregister_entity(struct media_entity *entity);
141
142Unregistering an entity will not change the IDs of the other entities, and the
143ID will never be reused for a newly registered entity.
144
145When a media device is unregistered, all its entities are unregistered
146automatically. No manual entities unregistration is then required.
147
148Drivers free resources associated with an entity by calling
149
150 media_entity_cleanup(struct media_entity *entity);
151
152This function must be called during the cleanup phase after unregistering the
153entity. Note that the media_entity instance itself must be freed explicitly by
154the driver if required.
155
156Entities have flags that describe the entity capabilities and state.
157
158 MEDIA_ENT_FL_DEFAULT indicates the default entity for a given type.
159 This can be used to report the default audio and video devices or the
160 default camera sensor.
161
162Logical entity groups can be defined by setting the group ID of all member
163entities to the same non-zero value. An entity group serves no purpose in the
164kernel, but is reported to userspace during entities enumeration. The group_id
165field belongs to the media device driver and must not by touched by entity
166drivers.
167
168Media device drivers should define groups if several entities are logically
169bound together. Example usages include reporting
170
171 - ALSA, VBI and video nodes that carry the same media stream
172 - lens and flash controllers associated with a sensor
173
174- Pads
175
176Pads are represented by a struct media_pad instance, defined in
177include/media/media-entity.h. Each entity stores its pads in a pads array
178managed by the entity driver. Drivers usually embed the array in a
179driver-specific structure.
180
181Pads are identified by their entity and their 0-based index in the pads array.
182Both information are stored in the media_pad structure, making the media_pad
183pointer the canonical way to store and pass link references.
184
185Pads have flags that describe the pad capabilities and state.
186
187 MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
188 MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
189
190One and only one of MEDIA_PAD_FL_SINK and MEDIA_PAD_FL_SOURCE must be set for
191each pad.
192
193- Links
194
195Links are represented by a struct media_link instance, defined in
196include/media/media-entity.h. Each entity stores all links originating at or
197targetting any of its pads in a links array. A given link is thus stored
198twice, once in the source entity and once in the target entity. The array is
199pre-allocated and grows dynamically as needed.
200
201Drivers create links by calling
202
203 media_entity_create_link(struct media_entity *source, u16 source_pad,
204 struct media_entity *sink, u16 sink_pad,
205 u32 flags);
206
207An entry in the link array of each entity is allocated and stores pointers
208to source and sink pads.
209
210Links have flags that describe the link capabilities and state.
211
212 MEDIA_LNK_FL_ENABLED indicates that the link is enabled and can be used
213 to transfer media data. When two or more links target a sink pad, only
214 one of them can be enabled at a time.
215 MEDIA_LNK_FL_IMMUTABLE indicates that the link enabled state can't be
216 modified at runtime. If MEDIA_LNK_FL_IMMUTABLE is set, then
217 MEDIA_LNK_FL_ENABLED must also be set since an immutable link is always
218 enabled.
219
220
221Graph traversal
222---------------
223
224The media framework provides APIs to iterate over entities in a graph.
225
226To iterate over all entities belonging to a media device, drivers can use the
227media_device_for_each_entity macro, defined in include/media/media-device.h.
228
229 struct media_entity *entity;
230
231 media_device_for_each_entity(entity, mdev) {
232 /* entity will point to each entity in turn */
233 ...
234 }
235
236Drivers might also need to iterate over all entities in a graph that can be
237reached only through enabled links starting at a given entity. The media
238framework provides a depth-first graph traversal API for that purpose.
239
240Note that graphs with cycles (whether directed or undirected) are *NOT*
241supported by the graph traversal API. To prevent infinite loops, the graph
242traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
243currently defined as 16.
244
245Drivers initiate a graph traversal by calling
246
247 media_entity_graph_walk_start(struct media_entity_graph *graph,
248 struct media_entity *entity);
249
250The graph structure, provided by the caller, is initialized to start graph
251traversal at the given entity.
252
253Drivers can then retrieve the next entity by calling
254
255 media_entity_graph_walk_next(struct media_entity_graph *graph);
256
257When the graph traversal is complete the function will return NULL.
258
259Graph traversal can be interrupted at any moment. No cleanup function call is
260required and the graph structure can be freed normally.
261
262Helper functions can be used to find a link between two given pads, or a pad
263connected to another pad through an enabled link
264
265 media_entity_find_link(struct media_pad *source,
266 struct media_pad *sink);
267
268 media_entity_remote_source(struct media_pad *pad);
269
270Refer to the kerneldoc documentation for more information.
271
272
273Use count and power handling
274----------------------------
275
276Due to the wide differences between drivers regarding power management needs,
277the media controller does not implement power management. However, the
278media_entity structure includes a use_count field that media drivers can use to
279track the number of users of every entity for power management needs.
280
281The use_count field is owned by media drivers and must not be touched by entity
282drivers. Access to the field must be protected by the media device graph_mutex
283lock.
284
285
286Links setup
287-----------
288
289Link properties can be modified at runtime by calling
290
291 media_entity_setup_link(struct media_link *link, u32 flags);
292
293The flags argument contains the requested new link flags.
294
295The only configurable property is the ENABLED link flag to enable/disable a
296link. Links marked with the IMMUTABLE link flag can not be enabled or disabled.
297
298When a link is enabled or disabled, the media framework calls the
299link_setup operation for the two entities at the source and sink of the link,
300in that order. If the second link_setup call fails, another link_setup call is
301made on the first entity to restore the original link flags.
302
303Media device drivers can be notified of link setup operations by setting the
304media_device::link_notify pointer to a callback function. If provided, the
305notification callback will be called before enabling and after disabling
306links.
307
308Entity drivers must implement the link_setup operation if any of their links
309is non-immutable. The operation must either configure the hardware or store
310the configuration information to be applied later.
311
312Link configuration must not have any side effect on other links. If an enabled
313link at a sink pad prevents another link at the same pad from being disabled,
314the link_setup operation must return -EBUSY and can't implicitly disable the
315first enabled link.
316
317
318Pipelines and media streams
319---------------------------
320
321When starting streaming, drivers must notify all entities in the pipeline to
322prevent link states from being modified during streaming by calling
323
324 media_entity_pipeline_start(struct media_entity *entity,
325 struct media_pipeline *pipe);
326
327The function will mark all entities connected to the given entity through
328enabled links, either directly or indirectly, as streaming.
329
330The media_pipeline instance pointed to by the pipe argument will be stored in
331every entity in the pipeline. Drivers should embed the media_pipeline structure
332in higher-level pipeline structures and can then access the pipeline through
333the media_entity pipe field.
334
335Calls to media_entity_pipeline_start() can be nested. The pipeline pointer must
336be identical for all nested calls to the function.
337
338When stopping the stream, drivers must notify the entities with
339
340 media_entity_pipeline_stop(struct media_entity *entity);
341
342If multiple calls to media_entity_pipeline_start() have been made the same
343number of media_entity_pipeline_stop() calls are required to stop streaming. The
344media_entity pipe field is reset to NULL on the last nested stop call.
345
346Link configuration will fail with -EBUSY by default if either end of the link is
347a streaming entity. Links that can be modified while streaming must be marked
348with the MEDIA_LNK_FL_DYNAMIC flag.
349
350If other operations need to be disallowed on streaming entities (such as
351changing entities configuration parameters) drivers can explictly check the
352media_entity stream_count field to find out if an entity is streaming. This
353operation must be done with the media_device graph_mutex held.
diff --git a/Documentation/video4linux/README.ivtv b/Documentation/video4linux/README.ivtv
index 42b06686eb78..2579b5b709ed 100644
--- a/Documentation/video4linux/README.ivtv
+++ b/Documentation/video4linux/README.ivtv
@@ -36,8 +36,7 @@ Additional features for the PVR-350 (CX23415 based):
36 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the 36 * Provides comprehensive OSD (On Screen Display: ie. graphics overlaying the
37 video signal) 37 video signal)
38 * Provides a framebuffer (allowing X applications to appear on the video 38 * Provides a framebuffer (allowing X applications to appear on the video
39 device) (this framebuffer is not yet part of the kernel. In the meantime it 39 device)
40 is available from www.ivtvdriver.org).
41 * Supports raw YUV output. 40 * Supports raw YUV output.
42 41
43IMPORTANT: In case of problems first read this page: 42IMPORTANT: In case of problems first read this page:
diff --git a/Documentation/video4linux/gspca.txt b/Documentation/video4linux/gspca.txt
index 261776e0c5e1..5c542e60f51d 100644
--- a/Documentation/video4linux/gspca.txt
+++ b/Documentation/video4linux/gspca.txt
@@ -103,6 +103,7 @@ spca561 046d:092d Logitech QC Elch2
103spca561 046d:092e Logitech QC Elch2 103spca561 046d:092e Logitech QC Elch2
104spca561 046d:092f Logitech QuickCam Express Plus 104spca561 046d:092f Logitech QuickCam Express Plus
105sunplus 046d:0960 Logitech ClickSmart 420 105sunplus 046d:0960 Logitech ClickSmart 420
106nw80x 046d:d001 Logitech QuickCam Pro (dark focus ring)
106sunplus 0471:0322 Philips DMVC1300K 107sunplus 0471:0322 Philips DMVC1300K
107zc3xx 0471:0325 Philips SPC 200 NC 108zc3xx 0471:0325 Philips SPC 200 NC
108zc3xx 0471:0326 Philips SPC 300 NC 109zc3xx 0471:0326 Philips SPC 300 NC
@@ -150,10 +151,12 @@ sunplus 04fc:5330 Digitrex 2110
150sunplus 04fc:5360 Sunplus Generic 151sunplus 04fc:5360 Sunplus Generic
151spca500 04fc:7333 PalmPixDC85 152spca500 04fc:7333 PalmPixDC85
152sunplus 04fc:ffff Pure DigitalDakota 153sunplus 04fc:ffff Pure DigitalDakota
154nw80x 0502:d001 DVC V6
153spca501 0506:00df 3Com HomeConnect Lite 155spca501 0506:00df 3Com HomeConnect Lite
154sunplus 052b:1507 Megapixel 5 Pretec DC-1007 156sunplus 052b:1507 Megapixel 5 Pretec DC-1007
155sunplus 052b:1513 Megapix V4 157sunplus 052b:1513 Megapix V4
156sunplus 052b:1803 MegaImage VI 158sunplus 052b:1803 MegaImage VI
159nw80x 052b:d001 EZCam Pro p35u
157tv8532 0545:808b Veo Stingray 160tv8532 0545:808b Veo Stingray
158tv8532 0545:8333 Veo Stingray 161tv8532 0545:8333 Veo Stingray
159sunplus 0546:3155 Polaroid PDC3070 162sunplus 0546:3155 Polaroid PDC3070
@@ -177,6 +180,7 @@ sunplus 055f:c530 Mustek Gsmart LCD 3
177sunplus 055f:c540 Gsmart D30 180sunplus 055f:c540 Gsmart D30
178sunplus 055f:c630 Mustek MDC4000 181sunplus 055f:c630 Mustek MDC4000
179sunplus 055f:c650 Mustek MDC5500Z 182sunplus 055f:c650 Mustek MDC5500Z
183nw80x 055f:d001 Mustek Wcam 300 mini
180zc3xx 055f:d003 Mustek WCam300A 184zc3xx 055f:d003 Mustek WCam300A
181zc3xx 055f:d004 Mustek WCam300 AN 185zc3xx 055f:d004 Mustek WCam300 AN
182conex 0572:0041 Creative Notebook cx11646 186conex 0572:0041 Creative Notebook cx11646
@@ -195,14 +199,20 @@ gl860 05e3:0503 Genesys Logic PC Camera
195gl860 05e3:f191 Genesys Logic PC Camera 199gl860 05e3:f191 Genesys Logic PC Camera
196spca561 060b:a001 Maxell Compact Pc PM3 200spca561 060b:a001 Maxell Compact Pc PM3
197zc3xx 0698:2003 CTX M730V built in 201zc3xx 0698:2003 CTX M730V built in
202nw80x 06a5:0000 Typhoon Webcam 100 USB
203nw80x 06a5:d001 Divio based webcams
204nw80x 06a5:d800 Divio Chicony TwinkleCam, Trust SpaceCam
198spca500 06bd:0404 Agfa CL20 205spca500 06bd:0404 Agfa CL20
199spca500 06be:0800 Optimedia 206spca500 06be:0800 Optimedia
207nw80x 06be:d001 EZCam Pro p35u
200sunplus 06d6:0031 Trust 610 LCD PowerC@m Zoom 208sunplus 06d6:0031 Trust 610 LCD PowerC@m Zoom
201spca506 06e1:a190 ADS Instant VCD 209spca506 06e1:a190 ADS Instant VCD
210ov534 06f8:3002 Hercules Blog Webcam
202ov534_9 06f8:3003 Hercules Dualpix HD Weblog 211ov534_9 06f8:3003 Hercules Dualpix HD Weblog
203sonixj 06f8:3004 Hercules Classic Silver 212sonixj 06f8:3004 Hercules Classic Silver
204sonixj 06f8:3008 Hercules Deluxe Optical Glass 213sonixj 06f8:3008 Hercules Deluxe Optical Glass
205pac7302 06f8:3009 Hercules Classic Link 214pac7302 06f8:3009 Hercules Classic Link
215nw80x 0728:d001 AVerMedia Camguard
206spca508 0733:0110 ViewQuest VQ110 216spca508 0733:0110 ViewQuest VQ110
207spca501 0733:0401 Intel Create and Share 217spca501 0733:0401 Intel Create and Share
208spca501 0733:0402 ViewQuest M318B 218spca501 0733:0402 ViewQuest M318B
diff --git a/Documentation/video4linux/omap3isp.txt b/Documentation/video4linux/omap3isp.txt
new file mode 100644
index 000000000000..69be2c782b98
--- /dev/null
+++ b/Documentation/video4linux/omap3isp.txt
@@ -0,0 +1,278 @@
1OMAP 3 Image Signal Processor (ISP) driver
2
3Copyright (C) 2010 Nokia Corporation
4Copyright (C) 2009 Texas Instruments, Inc.
5
6Contacts: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
7 Sakari Ailus <sakari.ailus@iki.fi>
8 David Cohen <dacohen@gmail.com>
9
10
11Introduction
12============
13
14This file documents the Texas Instruments OMAP 3 Image Signal Processor (ISP)
15driver located under drivers/media/video/omap3isp. The original driver was
16written by Texas Instruments but since that it has been rewritten (twice) at
17Nokia.
18
19The driver has been successfully used on the following versions of OMAP 3:
20
21 3430
22 3530
23 3630
24
25The driver implements V4L2, Media controller and v4l2_subdev interfaces.
26Sensor, lens and flash drivers using the v4l2_subdev interface in the kernel
27are supported.
28
29
30Split to subdevs
31================
32
33The OMAP 3 ISP is split into V4L2 subdevs, each of the blocks inside the ISP
34having one subdev to represent it. Each of the subdevs provide a V4L2 subdev
35interface to userspace.
36
37 OMAP3 ISP CCP2
38 OMAP3 ISP CSI2a
39 OMAP3 ISP CCDC
40 OMAP3 ISP preview
41 OMAP3 ISP resizer
42 OMAP3 ISP AEWB
43 OMAP3 ISP AF
44 OMAP3 ISP histogram
45
46Each possible link in the ISP is modelled by a link in the Media controller
47interface. For an example program see [2].
48
49
50Controlling the OMAP 3 ISP
51==========================
52
53In general, the settings given to the OMAP 3 ISP take effect at the beginning
54of the following frame. This is done when the module becomes idle during the
55vertical blanking period on the sensor. In memory-to-memory operation the pipe
56is run one frame at a time. Applying the settings is done between the frames.
57
58All the blocks in the ISP, excluding the CSI-2 and possibly the CCP2 receiver,
59insist on receiving complete frames. Sensors must thus never send the ISP
60partial frames.
61
62Autoidle does have issues with some ISP blocks on the 3430, at least.
63Autoidle is only enabled on 3630 when the omap3isp module parameter autoidle
64is non-zero.
65
66
67Events
68======
69
70The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and
71statistics (AEWB, AF and histogram) subdevs.
72
73The CCDC subdev produces V4L2_EVENT_OMAP3ISP_HS_VS type event on HS_VS
74interrupt which is used to signal frame start. The event is triggered exactly
75when the reception of the first line of the frame starts in the CCDC module.
76The event can be subscribed on the CCDC subdev.
77
78(When using parallel interface one must pay account to correct configuration
79of the VS signal polarity. This is automatically correct when using the serial
80receivers.)
81
82Each of the statistics subdevs is able to produce events. An event is
83generated whenever a statistics buffer can be dequeued by a user space
84application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available
85are:
86
87 V4L2_EVENT_OMAP3ISP_AEWB
88 V4L2_EVENT_OMAP3ISP_AF
89 V4L2_EVENT_OMAP3ISP_HIST
90
91The type of the event data is struct omap3isp_stat_event_status for these
92ioctls. If there is an error calculating the statistics, there will be an
93event as usual, but no related statistics buffer. In this case
94omap3isp_stat_event_status.buf_err is set to non-zero.
95
96
97Private IOCTLs
98==============
99
100The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where
101possible and practical. Much of the functions provided by the ISP, however,
102does not fall under the standard IOCTLs --- gamma tables and configuration of
103statistics collection are examples of such.
104
105In general, there is a private ioctl for configuring each of the blocks
106containing hardware-dependent functions.
107
108The following private IOCTLs are supported:
109
110 VIDIOC_OMAP3ISP_CCDC_CFG
111 VIDIOC_OMAP3ISP_PRV_CFG
112 VIDIOC_OMAP3ISP_AEWB_CFG
113 VIDIOC_OMAP3ISP_HIST_CFG
114 VIDIOC_OMAP3ISP_AF_CFG
115 VIDIOC_OMAP3ISP_STAT_REQ
116 VIDIOC_OMAP3ISP_STAT_EN
117
118The parameter structures used by these ioctls are described in
119include/linux/omap3isp.h. The detailed functions of the ISP itself related to
120a given ISP block is described in the Technical Reference Manuals (TRMs) ---
121see the end of the document for those.
122
123While it is possible to use the ISP driver without any use of these private
124IOCTLs it is not possible to obtain optimal image quality this way. The AEWB,
125AF and histogram modules cannot be used without configuring them using the
126appropriate private IOCTLs.
127
128
129CCDC and preview block IOCTLs
130=============================
131
132The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to
133configure, enable and disable functions in the CCDC and preview blocks,
134respectively. Both IOCTLs control several functions in the blocks they
135control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct
136omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG
137accepts a pointer to struct omap3isp_prev_update_config. The definition of
138both structures is available in [1].
139
140The update field in the structures tells whether to update the configuration
141for the specific function and the flag tells whether to enable or disable the
142function.
143
144The update and flag bit masks accept the following values. Each separate
145functions in the CCDC and preview blocks is associated with a flag (either
146disable or enable; part of the flag field in the structure) and a pointer to
147configuration data for the function.
148
149Valid values for the update and flag fields are listed here for
150VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one
151function in the same IOCTL call.
152
153 OMAP3ISP_CCDC_ALAW
154 OMAP3ISP_CCDC_LPF
155 OMAP3ISP_CCDC_BLCLAMP
156 OMAP3ISP_CCDC_BCOMP
157 OMAP3ISP_CCDC_FPC
158 OMAP3ISP_CCDC_CULL
159 OMAP3ISP_CCDC_CONFIG_LSC
160 OMAP3ISP_CCDC_TBL_LSC
161
162The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here:
163
164 OMAP3ISP_PREV_LUMAENH
165 OMAP3ISP_PREV_INVALAW
166 OMAP3ISP_PREV_HRZ_MED
167 OMAP3ISP_PREV_CFA
168 OMAP3ISP_PREV_CHROMA_SUPP
169 OMAP3ISP_PREV_WB
170 OMAP3ISP_PREV_BLKADJ
171 OMAP3ISP_PREV_RGB2RGB
172 OMAP3ISP_PREV_COLOR_CONV
173 OMAP3ISP_PREV_YC_LIMIT
174 OMAP3ISP_PREV_DEFECT_COR
175 OMAP3ISP_PREV_GAMMABYPASS
176 OMAP3ISP_PREV_DRK_FRM_CAPTURE
177 OMAP3ISP_PREV_DRK_FRM_SUBTRACT
178 OMAP3ISP_PREV_LENS_SHADING
179 OMAP3ISP_PREV_NF
180 OMAP3ISP_PREV_GAMMA
181
182The associated configuration pointer for the function may not be NULL when
183enabling the function. When disabling a function the configuration pointer is
184ignored.
185
186
187Statistic blocks IOCTLs
188=======================
189
190The statistics subdevs do offer more dynamic configuration options than the
191other subdevs. They can be enabled, disable and reconfigured when the pipeline
192is in streaming state.
193
194The statistics blocks always get the input image data from the CCDC (as the
195histogram memory read isn't implemented). The statistics are dequeueable by
196the user from the statistics subdev nodes using private IOCTLs.
197
198The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily
199reflected by the register level interface offered by the ISP hardware. There
200are aspects that are purely related to the driver implementation and these are
201discussed next.
202
203VIDIOC_OMAP3ISP_STAT_EN
204-----------------------
205
206This private IOCTL enables/disables a statistic module. If this request is
207done before streaming, it will take effect as soon as the pipeline starts to
208stream. If the pipeline is already streaming, it will take effect as soon as
209the CCDC becomes idle.
210
211VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
212-----------------------------------------------------------------------------
213
214Those IOCTLs are used to configure the modules. They require user applications
215to have an in-depth knowledge of the hardware. Most of the fields explanation
216can be found on OMAP's TRMs. The two following fields common to all the above
217configure private IOCTLs require explanation for better understanding as they
218are not part of the TRM.
219
220omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size:
221
222The modules handle their buffers internally. The necessary buffer size for the
223module's data output depends on the requested configuration. Although the
224driver supports reconfiguration while streaming, it does not support a
225reconfiguration which requires bigger buffer size than what is already
226internally allocated if the module is enabled. It will return -EBUSY on this
227case. In order to avoid such condition, either disable/reconfigure/enable the
228module or request the necessary buffer size during the first configuration
229while the module is disabled.
230
231The internal buffer size allocation considers the requested configuration's
232minimum buffer size and the value set on buf_size field. If buf_size field is
233out of [minimum, maximum] buffer size range, it's clamped to fit in there.
234The driver then selects the biggest value. The corrected buf_size value is
235written back to user application.
236
237omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter:
238
239As the configuration doesn't take effect synchronously to the request, the
240driver must provide a way to track this information to provide more accurate
241data. After a configuration is requested, the config_counter returned to user
242space application will be an unique value associated to that request. When
243user application receives an event for buffer availability or when a new
244buffer is requested, this config_counter is used to match a buffer data and a
245configuration.
246
247VIDIOC_OMAP3ISP_STAT_REQ
248------------------------
249
250Send to user space the oldest data available in the internal buffer queue and
251discards such buffer afterwards. The field omap3isp_stat_data.frame_number
252matches with the video buffer's field_count.
253
254
255Technical reference manuals (TRMs) and other documentation
256==========================================================
257
258OMAP 3430 TRM:
259<URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip>
260Referenced 2011-03-05.
261
262OMAP 35xx TRM:
263<URL:http://www.ti.com/litv/pdf/spruf98o> Referenced 2011-03-05.
264
265OMAP 3630 TRM:
266<URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip>
267Referenced 2011-03-05.
268
269DM 3730 TRM:
270<URL:http://www.ti.com/litv/pdf/sprugn4h> Referenced 2011-03-06.
271
272
273References
274==========
275
276[1] include/linux/omap3isp.h
277
278[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt
index f22f35c271f3..3b15608ee070 100644
--- a/Documentation/video4linux/v4l2-framework.txt
+++ b/Documentation/video4linux/v4l2-framework.txt
@@ -71,6 +71,10 @@ sub-device instances, the video_device struct stores V4L2 device node data
71and in the future a v4l2_fh struct will keep track of filehandle instances 71and in the future a v4l2_fh struct will keep track of filehandle instances
72(this is not yet implemented). 72(this is not yet implemented).
73 73
74The V4L2 framework also optionally integrates with the media framework. If a
75driver sets the struct v4l2_device mdev field, sub-devices and video nodes
76will automatically appear in the media framework as entities.
77
74 78
75struct v4l2_device 79struct v4l2_device
76------------------ 80------------------
@@ -83,11 +87,20 @@ You must register the device instance:
83 87
84 v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev); 88 v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
85 89
86Registration will initialize the v4l2_device struct and link dev->driver_data 90Registration will initialize the v4l2_device struct. If the dev->driver_data
87to v4l2_dev. If v4l2_dev->name is empty then it will be set to a value derived 91field is NULL, it will be linked to v4l2_dev.
88from dev (driver name followed by the bus_id, to be precise). If you set it 92
89up before calling v4l2_device_register then it will be untouched. If dev is 93Drivers that want integration with the media device framework need to set
90NULL, then you *must* setup v4l2_dev->name before calling v4l2_device_register. 94dev->driver_data manually to point to the driver-specific device structure
95that embed the struct v4l2_device instance. This is achieved by a
96dev_set_drvdata() call before registering the V4L2 device instance. They must
97also set the struct v4l2_device mdev field to point to a properly initialized
98and registered media_device instance.
99
100If v4l2_dev->name is empty then it will be set to a value derived from dev
101(driver name followed by the bus_id, to be precise). If you set it up before
102calling v4l2_device_register then it will be untouched. If dev is NULL, then
103you *must* setup v4l2_dev->name before calling v4l2_device_register.
91 104
92You can use v4l2_device_set_name() to set the name based on a driver name and 105You can use v4l2_device_set_name() to set the name based on a driver name and
93a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1, 106a driver-global atomic_t instance. This will generate names like ivtv0, ivtv1,
@@ -108,6 +121,7 @@ You unregister with:
108 121
109 v4l2_device_unregister(struct v4l2_device *v4l2_dev); 122 v4l2_device_unregister(struct v4l2_device *v4l2_dev);
110 123
124If the dev->driver_data field points to v4l2_dev, it will be reset to NULL.
111Unregistering will also automatically unregister all subdevs from the device. 125Unregistering will also automatically unregister all subdevs from the device.
112 126
113If you have a hotpluggable device (e.g. a USB device), then when a disconnect 127If you have a hotpluggable device (e.g. a USB device), then when a disconnect
@@ -167,6 +181,21 @@ static int __devinit drv_probe(struct pci_dev *pdev,
167 state->instance = atomic_inc_return(&drv_instance) - 1; 181 state->instance = atomic_inc_return(&drv_instance) - 1;
168} 182}
169 183
184If you have multiple device nodes then it can be difficult to know when it is
185safe to unregister v4l2_device. For this purpose v4l2_device has refcounting
186support. The refcount is increased whenever video_register_device is called and
187it is decreased whenever that device node is released. When the refcount reaches
188zero, then the v4l2_device release() callback is called. You can do your final
189cleanup there.
190
191If other device nodes (e.g. ALSA) are created, then you can increase and
192decrease the refcount manually as well by calling:
193
194void v4l2_device_get(struct v4l2_device *v4l2_dev);
195
196or:
197
198int v4l2_device_put(struct v4l2_device *v4l2_dev);
170 199
171struct v4l2_subdev 200struct v4l2_subdev
172------------------ 201------------------
@@ -254,6 +283,26 @@ A sub-device driver initializes the v4l2_subdev struct using:
254Afterwards you need to initialize subdev->name with a unique name and set the 283Afterwards you need to initialize subdev->name with a unique name and set the
255module owner. This is done for you if you use the i2c helper functions. 284module owner. This is done for you if you use the i2c helper functions.
256 285
286If integration with the media framework is needed, you must initialize the
287media_entity struct embedded in the v4l2_subdev struct (entity field) by
288calling media_entity_init():
289
290 struct media_pad *pads = &my_sd->pads;
291 int err;
292
293 err = media_entity_init(&sd->entity, npads, pads, 0);
294
295The pads array must have been previously initialized. There is no need to
296manually set the struct media_entity type and name fields, but the revision
297field must be initialized if needed.
298
299A reference to the entity will be automatically acquired/released when the
300subdev device node (if any) is opened/closed.
301
302Don't forget to cleanup the media entity before the sub-device is destroyed:
303
304 media_entity_cleanup(&sd->entity);
305
257A device (bridge) driver needs to register the v4l2_subdev with the 306A device (bridge) driver needs to register the v4l2_subdev with the
258v4l2_device: 307v4l2_device:
259 308
@@ -263,6 +312,9 @@ This can fail if the subdev module disappeared before it could be registered.
263After this function was called successfully the subdev->dev field points to 312After this function was called successfully the subdev->dev field points to
264the v4l2_device. 313the v4l2_device.
265 314
315If the v4l2_device parent device has a non-NULL mdev field, the sub-device
316entity will be automatically registered with the media device.
317
266You can unregister a sub-device using: 318You can unregister a sub-device using:
267 319
268 v4l2_device_unregister_subdev(sd); 320 v4l2_device_unregister_subdev(sd);
@@ -319,6 +371,61 @@ controlled through GPIO pins. This distinction is only relevant when setting
319up the device, but once the subdev is registered it is completely transparent. 371up the device, but once the subdev is registered it is completely transparent.
320 372
321 373
374V4L2 sub-device userspace API
375-----------------------------
376
377Beside exposing a kernel API through the v4l2_subdev_ops structure, V4L2
378sub-devices can also be controlled directly by userspace applications.
379
380Device nodes named v4l-subdevX can be created in /dev to access sub-devices
381directly. If a sub-device supports direct userspace configuration it must set
382the V4L2_SUBDEV_FL_HAS_DEVNODE flag before being registered.
383
384After registering sub-devices, the v4l2_device driver can create device nodes
385for all registered sub-devices marked with V4L2_SUBDEV_FL_HAS_DEVNODE by calling
386v4l2_device_register_subdev_nodes(). Those device nodes will be automatically
387removed when sub-devices are unregistered.
388
389The device node handles a subset of the V4L2 API.
390
391VIDIOC_QUERYCTRL
392VIDIOC_QUERYMENU
393VIDIOC_G_CTRL
394VIDIOC_S_CTRL
395VIDIOC_G_EXT_CTRLS
396VIDIOC_S_EXT_CTRLS
397VIDIOC_TRY_EXT_CTRLS
398
399 The controls ioctls are identical to the ones defined in V4L2. They
400 behave identically, with the only exception that they deal only with
401 controls implemented in the sub-device. Depending on the driver, those
402 controls can be also be accessed through one (or several) V4L2 device
403 nodes.
404
405VIDIOC_DQEVENT
406VIDIOC_SUBSCRIBE_EVENT
407VIDIOC_UNSUBSCRIBE_EVENT
408
409 The events ioctls are identical to the ones defined in V4L2. They
410 behave identically, with the only exception that they deal only with
411 events generated by the sub-device. Depending on the driver, those
412 events can also be reported by one (or several) V4L2 device nodes.
413
414 Sub-device drivers that want to use events need to set the
415 V4L2_SUBDEV_USES_EVENTS v4l2_subdev::flags and initialize
416 v4l2_subdev::nevents to events queue depth before registering the
417 sub-device. After registration events can be queued as usual on the
418 v4l2_subdev::devnode device node.
419
420 To properly support events, the poll() file operation is also
421 implemented.
422
423Private ioctls
424
425 All ioctls not in the above list are passed directly to the sub-device
426 driver through the core::ioctl operation.
427
428
322I2C sub-device drivers 429I2C sub-device drivers
323---------------------- 430----------------------
324 431
@@ -457,6 +564,10 @@ You should also set these fields:
457 Otherwise you give it a pointer to a struct mutex_lock and before any 564 Otherwise you give it a pointer to a struct mutex_lock and before any
458 of the v4l2_file_operations is called this lock will be taken by the 565 of the v4l2_file_operations is called this lock will be taken by the
459 core and released afterwards. 566 core and released afterwards.
567- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY.
568 If left to NULL, then it will use the struct v4l2_prio_state in v4l2_device.
569 If you want to have a separate priority state per (group of) device node(s),
570 then you can point it to your own struct v4l2_prio_state.
460- parent: you only set this if v4l2_device was registered with NULL as 571- parent: you only set this if v4l2_device was registered with NULL as
461 the parent device struct. This only happens in cases where one hardware 572 the parent device struct. This only happens in cases where one hardware
462 device has multiple PCI devices that all share the same v4l2_device core. 573 device has multiple PCI devices that all share the same v4l2_device core.
@@ -466,13 +577,34 @@ You should also set these fields:
466 (cx8802). Since the v4l2_device cannot be associated with a particular 577 (cx8802). Since the v4l2_device cannot be associated with a particular
467 PCI device it is setup without a parent device. But when the struct 578 PCI device it is setup without a parent device. But when the struct
468 video_device is setup you do know which parent PCI device to use. 579 video_device is setup you do know which parent PCI device to use.
580- flags: optional. Set to V4L2_FL_USE_FH_PRIO if you want to let the framework
581 handle the VIDIOC_G/S_PRIORITY ioctls. This requires that you use struct
582 v4l2_fh. Eventually this flag will disappear once all drivers use the core
583 priority handling. But for now it has to be set explicitly.
469 584
470If you use v4l2_ioctl_ops, then you should set either .unlocked_ioctl or 585If you use v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2
471.ioctl to video_ioctl2 in your v4l2_file_operations struct. 586in your v4l2_file_operations struct.
587
588Do not use .ioctl! This is deprecated and will go away in the future.
472 589
473The v4l2_file_operations struct is a subset of file_operations. The main 590The v4l2_file_operations struct is a subset of file_operations. The main
474difference is that the inode argument is omitted since it is never used. 591difference is that the inode argument is omitted since it is never used.
475 592
593If integration with the media framework is needed, you must initialize the
594media_entity struct embedded in the video_device struct (entity field) by
595calling media_entity_init():
596
597 struct media_pad *pad = &my_vdev->pad;
598 int err;
599
600 err = media_entity_init(&vdev->entity, 1, pad, 0);
601
602The pads array must have been previously initialized. There is no need to
603manually set the struct media_entity type and name fields.
604
605A reference to the entity will be automatically acquired/released when the
606video device is opened/closed.
607
476v4l2_file_operations and locking 608v4l2_file_operations and locking
477-------------------------------- 609--------------------------------
478 610
@@ -502,6 +634,9 @@ for you.
502 return err; 634 return err;
503 } 635 }
504 636
637If the v4l2_device parent device has a non-NULL mdev field, the video device
638entity will be automatically registered with the media device.
639
505Which device is registered depends on the type argument. The following 640Which device is registered depends on the type argument. The following
506types exist: 641types exist:
507 642
@@ -577,6 +712,13 @@ release, of course) will return an error as well.
577When the last user of the video device node exits, then the vdev->release() 712When the last user of the video device node exits, then the vdev->release()
578callback is called and you can do the final cleanup there. 713callback is called and you can do the final cleanup there.
579 714
715Don't forget to cleanup the media entity associated with the video device if
716it has been initialized:
717
718 media_entity_cleanup(&vdev->entity);
719
720This can be done from the release callback.
721
580 722
581video_device helper functions 723video_device helper functions
582----------------------------- 724-----------------------------
@@ -636,39 +778,25 @@ struct v4l2_fh
636-------------- 778--------------
637 779
638struct v4l2_fh provides a way to easily keep file handle specific data 780struct v4l2_fh provides a way to easily keep file handle specific data
639that is used by the V4L2 framework. Using v4l2_fh is optional for 781that is used by the V4L2 framework. New drivers must use struct v4l2_fh
640drivers. 782since it is also used to implement priority handling (VIDIOC_G/S_PRIORITY)
783if the video_device flag V4L2_FL_USE_FH_PRIO is also set.
641 784
642The users of v4l2_fh (in the V4L2 framework, not the driver) know 785The users of v4l2_fh (in the V4L2 framework, not the driver) know
643whether a driver uses v4l2_fh as its file->private_data pointer by 786whether a driver uses v4l2_fh as its file->private_data pointer by
644testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. 787testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. This bit is
645 788set whenever v4l2_fh_init() is called.
646Useful functions:
647
648- v4l2_fh_init()
649
650 Initialise the file handle. This *MUST* be performed in the driver's
651 v4l2_file_operations->open() handler.
652
653- v4l2_fh_add()
654 789
655 Add a v4l2_fh to video_device file handle list. May be called after 790struct v4l2_fh is allocated as a part of the driver's own file handle
656 initialising the file handle. 791structure and file->private_data is set to it in the driver's open
657 792function by the driver.
658- v4l2_fh_del()
659
660 Unassociate the file handle from video_device(). The file handle
661 exit function may now be called.
662 793
663- v4l2_fh_exit() 794In many cases the struct v4l2_fh will be embedded in a larger structure.
795In that case you should call v4l2_fh_init+v4l2_fh_add in open() and
796v4l2_fh_del+v4l2_fh_exit in release().
664 797
665 Uninitialise the file handle. After uninitialisation the v4l2_fh 798Drivers can extract their own file handle structure by using the container_of
666 memory can be freed. 799macro. Example:
667
668struct v4l2_fh is allocated as a part of the driver's own file handle
669structure and is set to file->private_data in the driver's open
670function by the driver. Drivers can extract their own file handle
671structure by using the container_of macro. Example:
672 800
673struct my_fh { 801struct my_fh {
674 int blah; 802 int blah;
@@ -685,15 +813,21 @@ int my_open(struct file *file)
685 813
686 ... 814 ...
687 815
816 my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
817
818 ...
819
688 ret = v4l2_fh_init(&my_fh->fh, vfd); 820 ret = v4l2_fh_init(&my_fh->fh, vfd);
689 if (ret) 821 if (ret) {
822 kfree(my_fh);
690 return ret; 823 return ret;
824 }
691 825
692 v4l2_fh_add(&my_fh->fh); 826 ...
693 827
694 file->private_data = &my_fh->fh; 828 file->private_data = &my_fh->fh;
695 829 v4l2_fh_add(&my_fh->fh);
696 ... 830 return 0;
697} 831}
698 832
699int my_release(struct file *file) 833int my_release(struct file *file)
@@ -702,8 +836,65 @@ int my_release(struct file *file)
702 struct my_fh *my_fh = container_of(fh, struct my_fh, fh); 836 struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
703 837
704 ... 838 ...
839 v4l2_fh_del(&my_fh->fh);
840 v4l2_fh_exit(&my_fh->fh);
841 kfree(my_fh);
842 return 0;
705} 843}
706 844
845Below is a short description of the v4l2_fh functions used:
846
847int v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
848
849 Initialise the file handle. This *MUST* be performed in the driver's
850 v4l2_file_operations->open() handler.
851
852void v4l2_fh_add(struct v4l2_fh *fh)
853
854 Add a v4l2_fh to video_device file handle list. Must be called once the
855 file handle is completely initialized.
856
857void v4l2_fh_del(struct v4l2_fh *fh)
858
859 Unassociate the file handle from video_device(). The file handle
860 exit function may now be called.
861
862void v4l2_fh_exit(struct v4l2_fh *fh)
863
864 Uninitialise the file handle. After uninitialisation the v4l2_fh
865 memory can be freed.
866
867
868If struct v4l2_fh is not embedded, then you can use these helper functions:
869
870int v4l2_fh_open(struct file *filp)
871
872 This allocates a struct v4l2_fh, initializes it and adds it to the struct
873 video_device associated with the file struct.
874
875int v4l2_fh_release(struct file *filp)
876
877 This deletes it from the struct video_device associated with the file
878 struct, uninitialised the v4l2_fh and frees it.
879
880These two functions can be plugged into the v4l2_file_operation's open() and
881release() ops.
882
883
884Several drivers need to do something when the first file handle is opened and
885when the last file handle closes. Two helper functions were added to check
886whether the v4l2_fh struct is the only open filehandle of the associated
887device node:
888
889int v4l2_fh_is_singular(struct v4l2_fh *fh)
890
891 Returns 1 if the file handle is the only open file handle, else 0.
892
893int v4l2_fh_is_singular_file(struct file *filp)
894
895 Same, but it calls v4l2_fh_is_singular with filp->private_data.
896
897
707V4L2 events 898V4L2 events
708----------- 899-----------
709 900
generated by cgit v1.2.2 (git 2.25.0) at 2024-12-26 02:55:34 -0500