aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/media
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@redhat.com>2011-05-31 15:27:44 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2011-07-27 16:52:05 -0400
commit4266129964b8238526936d723de65b419d8069c6 (patch)
tree38c6b5cd3dc99b8599391ffad3b87e399bef56a2 /Documentation/DocBook/media
parent04893043ae9ea8aa82b712491ed25ba6c4ffbca3 (diff)
[media] DocBook: Move all media docbook stuff into its own directory
This patch addresses several issues pointed by Randy Dunlap <rdunlap@xenotime.net> at changeset ece722c: - In the generated index.html file, "media" is listed first, but it should be listed in alphabetical order, not first. - The generated files are (hidden) in .tmpmedia/ - The link from the top-level index.html file to "media" is to media/index.html, but the file is actually in .tmpmedia/media/index.html - Please build docs with and without using "O=builddir" and test that. - Would it be possible for media to have its own Makefile instead of merging into this one? Due to the way cleandocs target works, I had to rename the media DocBook to media_api, otherwise cleandocs would remove the /media directory. Thanks-to: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat (limited to 'Documentation/DocBook/media')
-rw-r--r--Documentation/DocBook/media/Makefile259
-rw-r--r--Documentation/DocBook/media/dvb/.gitignore1
-rw-r--r--Documentation/DocBook/media/dvb/audio.xml1473
-rw-r--r--Documentation/DocBook/media/dvb/ca.xml221
-rw-r--r--Documentation/DocBook/media/dvb/demux.xml973
-rw-r--r--Documentation/DocBook/media/dvb/dvbapi.xml121
-rw-r--r--Documentation/DocBook/media/dvb/dvbproperty.xml590
-rw-r--r--Documentation/DocBook/media/dvb/dvbstb.pdfbin0 -> 1881 bytes
-rw-r--r--Documentation/DocBook/media/dvb/dvbstb.pngbin0 -> 22655 bytes
-rw-r--r--Documentation/DocBook/media/dvb/examples.xml365
-rw-r--r--Documentation/DocBook/media/dvb/frontend.xml1851
-rw-r--r--Documentation/DocBook/media/dvb/intro.xml191
-rw-r--r--Documentation/DocBook/media/dvb/kdapi.xml2309
-rw-r--r--Documentation/DocBook/media/dvb/net.xml12
-rw-r--r--Documentation/DocBook/media/dvb/video.xml1971
-rw-r--r--Documentation/DocBook/media/v4l/.gitignore1
-rw-r--r--Documentation/DocBook/media/v4l/bayer.pdfbin0 -> 12116 bytes
-rw-r--r--Documentation/DocBook/media/v4l/bayer.pngbin0 -> 9725 bytes
-rw-r--r--Documentation/DocBook/media/v4l/biblio.xml188
-rw-r--r--Documentation/DocBook/media/v4l/capture.c.xml659
-rw-r--r--Documentation/DocBook/media/v4l/common.xml1197
-rw-r--r--Documentation/DocBook/media/v4l/compat.xml2500
-rw-r--r--Documentation/DocBook/media/v4l/controls.xml2103
-rw-r--r--Documentation/DocBook/media/v4l/crop.gifbin0 -> 5967 bytes
-rw-r--r--Documentation/DocBook/media/v4l/crop.pdfbin0 -> 5846 bytes
-rw-r--r--Documentation/DocBook/media/v4l/dev-capture.xml118
-rw-r--r--Documentation/DocBook/media/v4l/dev-codec.xml26
-rw-r--r--Documentation/DocBook/media/v4l/dev-effect.xml25
-rw-r--r--Documentation/DocBook/media/v4l/dev-event.xml31
-rw-r--r--Documentation/DocBook/media/v4l/dev-osd.xml164
-rw-r--r--Documentation/DocBook/media/v4l/dev-output.xml114
-rw-r--r--Documentation/DocBook/media/v4l/dev-overlay.xml379
-rw-r--r--Documentation/DocBook/media/v4l/dev-radio.xml57
-rw-r--r--Documentation/DocBook/media/v4l/dev-raw-vbi.xml347
-rw-r--r--Documentation/DocBook/media/v4l/dev-rds.xml204
-rw-r--r--Documentation/DocBook/media/v4l/dev-sliced-vbi.xml708
-rw-r--r--Documentation/DocBook/media/v4l/dev-subdev.xml313
-rw-r--r--Documentation/DocBook/media/v4l/dev-teletext.xml37
-rw-r--r--Documentation/DocBook/media/v4l/driver.xml208
-rw-r--r--Documentation/DocBook/media/v4l/fdl-appendix.xml671
-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_bt.gifbin0 -> 25430 bytes
-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_bt.pdfbin0 -> 9185 bytes
-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_tb.gifbin0 -> 25323 bytes
-rw-r--r--Documentation/DocBook/media/v4l/fieldseq_tb.pdfbin0 -> 9173 bytes
-rw-r--r--Documentation/DocBook/media/v4l/func-close.xml70
-rw-r--r--Documentation/DocBook/media/v4l/func-ioctl.xml145
-rw-r--r--Documentation/DocBook/media/v4l/func-mmap.xml191
-rw-r--r--Documentation/DocBook/media/v4l/func-munmap.xml84
-rw-r--r--Documentation/DocBook/media/v4l/func-open.xml121
-rw-r--r--Documentation/DocBook/media/v4l/func-poll.xml127
-rw-r--r--Documentation/DocBook/media/v4l/func-read.xml189
-rw-r--r--Documentation/DocBook/media/v4l/func-select.xml138
-rw-r--r--Documentation/DocBook/media/v4l/func-write.xml136
-rw-r--r--Documentation/DocBook/media/v4l/io.xml1265
-rw-r--r--Documentation/DocBook/media/v4l/keytable.c.xml172
-rw-r--r--Documentation/DocBook/media/v4l/libv4l.xml167
-rw-r--r--Documentation/DocBook/media/v4l/lirc_device_interface.xml251
-rw-r--r--Documentation/DocBook/media/v4l/media-controller.xml89
-rw-r--r--Documentation/DocBook/media/v4l/media-func-close.xml59
-rw-r--r--Documentation/DocBook/media/v4l/media-func-ioctl.xml116
-rw-r--r--Documentation/DocBook/media/v4l/media-func-open.xml94
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-device-info.xml133
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml308
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-enum-links.xml207
-rw-r--r--Documentation/DocBook/media/v4l/media-ioc-setup-link.xml93
-rw-r--r--Documentation/DocBook/media/v4l/nv12mt.gifbin0 -> 2108 bytes
-rw-r--r--Documentation/DocBook/media/v4l/nv12mt_example.gifbin0 -> 6858 bytes
-rw-r--r--Documentation/DocBook/media/v4l/pipeline.pdfbin0 -> 20276 bytes
-rw-r--r--Documentation/DocBook/media/v4l/pipeline.pngbin0 -> 12130 bytes
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-grey.xml70
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-m420.xml147
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12.xml151
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12m.xml154
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml74
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-nv16.xml174
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml940
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml244
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml91
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml75
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml75
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml75
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb10.xml90
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb12.xml90
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-srggb8.xml67
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-uyvy.xml128
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-vyuy.xml128
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y10.xml79
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y10b.xml43
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y12.xml79
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y16.xml89
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-y41p.xml157
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv410.xml141
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml155
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv420.xml157
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml162
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml161
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yuyv.xml128
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-yvyu.xml128
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt.xml951
-rw-r--r--Documentation/DocBook/media/v4l/planar-apis.xml62
-rw-r--r--Documentation/DocBook/media/v4l/remote_controllers.xml177
-rw-r--r--Documentation/DocBook/media/v4l/subdev-formats.xml2572
-rw-r--r--Documentation/DocBook/media/v4l/v4l2.xml539
-rw-r--r--Documentation/DocBook/media/v4l/v4l2grab.c.xml164
-rw-r--r--Documentation/DocBook/media/v4l/vbi_525.gifbin0 -> 4741 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vbi_525.pdfbin0 -> 3395 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vbi_625.gifbin0 -> 5095 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vbi_625.pdfbin0 -> 3683 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vbi_hsync.gifbin0 -> 2400 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vbi_hsync.pdfbin0 -> 7405 bytes
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-cropcap.xml174
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml275
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml275
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dqevent.xml131
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml204
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml238
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml166
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml270
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml282
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumaudio.xml86
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml89
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enuminput.xml321
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumoutput.xml206
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumstd.xml391
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-audio.xml188
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-audioout.xml154
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-crop.xml143
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml130
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml110
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml223
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml213
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml307
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml473
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-fmt.xml212
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-frequency.xml145
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-input.xml100
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml180
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-modulator.xml246
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-output.xml100
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-parm.xml332
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-priority.xml144
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml264
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-std.xml105
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-tuner.xml535
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-log-status.xml58
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-overlay.xml83
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-qbuf.xml194
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml87
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querybuf.xml110
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querycap.xml303
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-queryctrl.xml434
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-querystd.xml89
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-reqbufs.xml150
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml135
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-streamon.xml115
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml152
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml154
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml119
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml155
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml180
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml141
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml133
162 files changed, 43463 insertions, 0 deletions
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
new file mode 100644
index 000000000000..baeea174fdc6
--- /dev/null
+++ b/Documentation/DocBook/media/Makefile
@@ -0,0 +1,259 @@
1###
2# Media build rules - Auto-generates media contents/indexes and *.h xml's
3#
4
5SHELL=/bin/bash
6
7MEDIA_OBJ_DIR=$(objtree)/Documentation/DocBook/
8MEDIA_SRC_DIR=$(srctree)/Documentation/DocBook/media
9
10MEDIA_TEMP = media-entities.tmpl \
11 media-indices.tmpl \
12 videodev2.h.xml \
13 v4l2.xml \
14 frontend.h.xml
15
16IMGFILES := $(addprefix $(MEDIA_OBJ_DIR)/media/, $(notdir $(shell ls $(MEDIA_SRC_DIR)/*/*.gif $(MEDIA_SRC_DIR)/*/*.png)))
17GENFILES := $(addprefix $(MEDIA_OBJ_DIR)/, $(MEDIA_TEMP))
18
19PHONY += cleanmediadocs mediaindexdocs
20
21cleanmediadocs:
22 -@rm `find $(MEDIA_OBJ_DIR) -type l` $(GENFILES) $(IMGFILES)
23
24$(obj)/media_api.xml: $(GENFILES) FORCE
25
26#$(MEDIA_OBJ_DIR)/media_api.html: $(MEDIA_OBJ_DIR)/media_api.xml
27#$(MEDIA_OBJ_DIR)/media_api.pdf: $(MEDIA_OBJ_DIR)/media_api.xml
28#$(MEDIA_OBJ_DIR)/media_api.ps: $(MEDIA_OBJ_DIR)/media_api.xml
29
30V4L_SGMLS = \
31 $(shell ls $(MEDIA_SRC_DIR)/v4l/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)') \
32 capture.c.xml \
33 keytable.c.xml \
34 v4l2grab.c.xml
35
36DVB_SGMLS = \
37 $(shell ls $(MEDIA_SRC_DIR)/dvb/*.xml|perl -ne 'print "$$1 " if (m,.*/(.*)\n,)')
38
39MEDIA_SGMLS = $(addprefix ./,$(V4L_SGMLS)) $(addprefix ./,$(DVB_SGMLS)) $(addprefix ./,$(MEDIA_TEMP))
40
41FUNCS = \
42 close \
43 ioctl \
44 mmap \
45 munmap \
46 open \
47 poll \
48 read \
49 select \
50 write \
51
52IOCTLS = \
53 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/videodev2.h) \
54 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/media.h) \
55 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/v4l2-subdev.h) \
56 VIDIOC_SUBDEV_G_FRAME_INTERVAL \
57 VIDIOC_SUBDEV_S_FRAME_INTERVAL \
58 VIDIOC_SUBDEV_ENUM_MBUS_CODE \
59 VIDIOC_SUBDEV_ENUM_FRAME_SIZE \
60 VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \
61
62TYPES = \
63 $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h)
64
65ENUMS = \
66 $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \
67 $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \
68 $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h) \
69 $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h)
70
71STRUCTS = \
72 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \
73 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \
74 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h) \
75 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h)
76
77ERRORS = \
78 EACCES \
79 EAGAIN \
80 EBADF \
81 EBUSY \
82 EFAULT \
83 EIO \
84 EINTR \
85 EINVAL \
86 ENFILE \
87 ENOMEM \
88 ENOSPC \
89 ENOTTY \
90 ENXIO \
91 EMFILE \
92 EPERM \
93 ERANGE \
94 EPIPE \
95
96ESCAPE = \
97 -e "s/&/\\&amp;/g" \
98 -e "s/</\\&lt;/g" \
99 -e "s/>/\\&gt;/g"
100
101FILENAME = \
102 -e s,"^[^\/]*/",, \
103 -e s/"\\.xml"// \
104 -e s/"\\.tmpl"// \
105 -e s/\\\./-/g \
106 -e s/"^func-"// \
107 -e s/"^pixfmt-"// \
108 -e s/"^vidioc-"//
109
110# Generate references to these structs in videodev2.h.xml.
111DOCUMENTED = \
112 -e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \
113 -e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \
114 -e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \
115 -e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
116 -e "s/v4l2\-mpeg\-vbi\-ITV0/v4l2-mpeg-vbi-itv0-1/g"
117
118DVB_DOCUMENTED = \
119 -e "s,\(define \)\([A-Z0-9_]\+\)\(\s\+_IO\),\1\<link linkend=\"\2\">\2\<\/link\>\3,g" \
120 -e "s/\(linkend\=\"\)FE_SET_PROPERTY/\1FE_GET_PROPERTY/g"
121
122
123#
124# Media targets and dependencies
125#
126
127$(MEDIA_OBJ_DIR)/v4l2.xml:
128 @$($(quiet)gen_xml)
129 @(mkdir -p $(MEDIA_OBJ_DIR)/media)
130 @(cp $(MEDIA_SRC_DIR)/dvb/*.png $(MEDIA_SRC_DIR)/v4l/*.gif $(MEDIA_OBJ_DIR)/media/)
131 @(ln -sf $(MEDIA_SRC_DIR)/v4l/*xml $(MEDIA_OBJ_DIR)/)
132 @(ln -sf $(MEDIA_SRC_DIR)/dvb/*xml $(MEDIA_OBJ_DIR)/)
133
134$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml
135 @$($(quiet)gen_xml)
136 @( \
137 echo "<programlisting>") > $@
138 @( \
139 expand --tabs=8 < $< | \
140 sed $(ESCAPE) $(DOCUMENTED) | \
141 sed 's/i\.e\./&ie;/') >> $@
142 @( \
143 echo "</programlisting>") >> $@
144
145$(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/linux/dvb/frontend.h $(MEDIA_OBJ_DIR)/v4l2.xml
146 @$($(quiet)gen_xml)
147 @( \
148 echo "<programlisting>") > $@
149 @( \
150 expand --tabs=8 < $< | \
151 sed $(ESCAPE) $(DVB_DOCUMENTED) | \
152 sed 's/i\.e\./&ie;/') >> $@
153 @( \
154 echo "</programlisting>") >> $@
155
156$(MEDIA_OBJ_DIR)/media-entities.tmpl: $(MEDIA_OBJ_DIR)/v4l2.xml
157 @$($(quiet)gen_xml)
158 @( \
159 echo "<!-- Generated file! Do not edit. -->") >$@
160 @( \
161 echo -e "\n<!-- Functions -->") >>$@
162 @( \
163 for ident in $(FUNCS) ; do \
164 entity=`echo $$ident | tr _ -` ; \
165 echo "<!ENTITY func-$$entity \"<link" \
166 "linkend='func-$$entity'><function>$$ident()</function></link>\">" \
167 >>$@ ; \
168 done)
169 @( \
170 echo -e "\n<!-- Ioctls -->") >>$@
171 @( \
172 for ident in $(IOCTLS) ; do \
173 entity=`echo $$ident | tr _ -` ; \
174 id=`grep "<refname>$$ident" $(MEDIA_OBJ_DIR)/vidioc-*.xml | sed -r s,"^.*/(.*).xml.*","\1",` ; \
175 echo "<!ENTITY $$entity \"<link" \
176 "linkend='$$id'><constant>$$ident</constant></link>\">" \
177 >>$@ ; \
178 done)
179 @( \
180 echo -e "\n<!-- Types -->") >>$@
181 @( \
182 for ident in $(TYPES) ; do \
183 entity=`echo $$ident | tr _ -` ; \
184 echo "<!ENTITY $$entity \"<link" \
185 "linkend='$$entity'>$$ident</link>\">" >>$@ ; \
186 done)
187 @( \
188 echo -e "\n<!-- Enums -->") >>$@
189 @( \
190 for ident in $(ENUMS) ; do \
191 entity=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -` ; \
192 echo "<!ENTITY $$entity \"enum&nbsp;<link" \
193 "linkend='$$entity'>$$ident</link>\">" >>$@ ; \
194 done)
195 @( \
196 echo -e "\n<!-- Structures -->") >>$@
197 @( \
198 for ident in $(STRUCTS) ; do \
199 entity=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \
200 echo "<!ENTITY $$entity \"struct&nbsp;<link" \
201 "linkend='$$entity'>$$ident</link>\">" >>$@ ; \
202 done)
203 @( \
204 echo -e "\n<!-- Error Codes -->") >>$@
205 @( \
206 for ident in $(ERRORS) ; do \
207 echo "<!ENTITY $$ident \"<errorcode>$$ident</errorcode>" \
208 "error code\">" >>$@ ; \
209 done)
210 @( \
211 echo -e "\n<!-- Subsections -->") >>$@
212 @( \
213 for file in $(MEDIA_SGMLS) ; do \
214 entity=`echo "$$file" | sed $(FILENAME) -e s/"^([^-]*)"/sub\1/` ; \
215 if ! echo "$$file" | \
216 grep -q -E -e '^(func|vidioc|pixfmt)-' ; then \
217 echo "<!ENTITY sub-$$entity SYSTEM \"$$file\">" >>$@ ; \
218 fi ; \
219 done)
220 @( \
221 echo -e "\n<!-- Function Reference -->") >>$@
222 @( \
223 for file in $(MEDIA_SGMLS) ; do \
224 if echo "$$file" | \
225 grep -q -E -e '(func|vidioc|pixfmt)-' ; then \
226 entity=`echo "$$file" |sed $(FILENAME)` ; \
227 echo "<!ENTITY $$entity SYSTEM \"$$file\">" >>$@ ; \
228 fi ; \
229 done)
230
231# Jade can auto-generate a list-of-tables, which includes all structs,
232# but we only want data types, all types, and sorted please.
233$(MEDIA_OBJ_DIR)/media-indices.tmpl: $(MEDIA_OBJ_DIR)/v4l2.xml
234 @$($(quiet)gen_xml)
235 @( \
236 echo "<!-- Generated file! Do not edit. -->") >$@
237 @( \
238 echo -e "\n<index><title>List of Types</title>") >>$@
239 @( \
240 for ident in $(TYPES) ; do \
241 id=`echo $$ident | tr _ -` ; \
242 echo "<indexentry><primaryie><link" \
243 "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
244 done)
245 @( \
246 for ident in $(ENUMS) ; do \
247 id=`echo $$ident | sed -e "s/v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1/" | tr _ -`; \
248 echo "<indexentry><primaryie>enum&nbsp;<link" \
249 "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
250 done)
251 @( \
252 for ident in $(STRUCTS) ; do \
253 id=`echo $$ident | tr _ - | sed s/v4l2-mpeg-vbi-ITV0/v4l2-mpeg-vbi-itv0-1/g` ; \
254 echo "<indexentry><primaryie>struct&nbsp;<link" \
255 "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
256 done)
257 @( \
258 echo "</index>") >>$@
259
diff --git a/Documentation/DocBook/media/dvb/.gitignore b/Documentation/DocBook/media/dvb/.gitignore
new file mode 100644
index 000000000000..d7ec32eafac9
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/.gitignore
@@ -0,0 +1 @@
!*.xml
diff --git a/Documentation/DocBook/media/dvb/audio.xml b/Documentation/DocBook/media/dvb/audio.xml
new file mode 100644
index 000000000000..eeb96b8a0864
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/audio.xml
@@ -0,0 +1,1473 @@
1<title>DVB Audio Device</title>
2<para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It
3can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and
4ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your
5application.
6</para>
7<para>Please note that some DVB cards don&#8217;t have their own MPEG decoder, which results in
8the omission of the audio and video device.
9</para>
10
11<section id="audio_data_types">
12<title>Audio Data Types</title>
13<para>This section describes the structures, data types and defines used when talking to the
14audio device.
15</para>
16
17<section id="audio_stream_source_t">
18<title>audio_stream_source_t</title>
19<para>The audio stream source is set through the AUDIO_SELECT_SOURCE call and can take
20the following values, depending on whether we are replaying from an internal (demux) or
21external (user write) source.
22</para>
23<programlisting>
24 typedef enum {
25 AUDIO_SOURCE_DEMUX,
26 AUDIO_SOURCE_MEMORY
27 } audio_stream_source_t;
28</programlisting>
29<para>AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
30DVR device) as the source of the video stream. If AUDIO_SOURCE_MEMORY
31is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
32call.
33</para>
34
35</section>
36<section id="audio_play_state_t">
37<title>audio_play_state_t</title>
38<para>The following values can be returned by the AUDIO_GET_STATUS call representing the
39state of audio playback.
40</para>
41<programlisting>
42 typedef enum {
43 AUDIO_STOPPED,
44 AUDIO_PLAYING,
45 AUDIO_PAUSED
46 } audio_play_state_t;
47</programlisting>
48
49</section>
50<section id="audio_channel_select_t">
51<title>audio_channel_select_t</title>
52<para>The audio channel selected via AUDIO_CHANNEL_SELECT is determined by the
53following values.
54</para>
55<programlisting>
56 typedef enum {
57 AUDIO_STEREO,
58 AUDIO_MONO_LEFT,
59 AUDIO_MONO_RIGHT,
60 } audio_channel_select_t;
61</programlisting>
62
63</section>
64<section id="struct_audio_status">
65<title>struct audio_status</title>
66<para>The AUDIO_GET_STATUS call returns the following structure informing about various
67states of the playback operation.
68</para>
69<programlisting>
70 typedef struct audio_status {
71 boolean AV_sync_state;
72 boolean mute_state;
73 audio_play_state_t play_state;
74 audio_stream_source_t stream_source;
75 audio_channel_select_t channel_select;
76 boolean bypass_mode;
77 } audio_status_t;
78</programlisting>
79
80</section>
81<section id="struct_audio_mixer">
82<title>struct audio_mixer</title>
83<para>The following structure is used by the AUDIO_SET_MIXER call to set the audio
84volume.
85</para>
86<programlisting>
87 typedef struct audio_mixer {
88 unsigned int volume_left;
89 unsigned int volume_right;
90 } audio_mixer_t;
91</programlisting>
92
93</section>
94<section id="audio_encodings">
95<title>audio encodings</title>
96<para>A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the following
97bits set according to the hardwares capabilities.
98</para>
99<programlisting>
100 #define AUDIO_CAP_DTS 1
101 #define AUDIO_CAP_LPCM 2
102 #define AUDIO_CAP_MP1 4
103 #define AUDIO_CAP_MP2 8
104 #define AUDIO_CAP_MP3 16
105 #define AUDIO_CAP_AAC 32
106 #define AUDIO_CAP_OGG 64
107 #define AUDIO_CAP_SDDS 128
108 #define AUDIO_CAP_AC3 256
109</programlisting>
110
111</section>
112<section id="struct_audio_karaoke">
113<title>struct audio_karaoke</title>
114<para>The ioctl AUDIO_SET_KARAOKE uses the following format:
115</para>
116<programlisting>
117 typedef
118 struct audio_karaoke{
119 int vocal1;
120 int vocal2;
121 int melody;
122 } audio_karaoke_t;
123</programlisting>
124<para>If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t at 70% each. If both,
125Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed into the left channel and Vocal2 into the
126right channel at 100% each. Ff Melody is non-zero, the melody channel gets mixed into left
127and right.
128</para>
129
130</section>
131<section id="audio_attributes">
132<title>audio attributes</title>
133<para>The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES:
134</para>
135<programlisting>
136 typedef uint16_t audio_attributes_t;
137 /&#x22C6; bits: descr. &#x22C6;/
138 /&#x22C6; 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, &#x22C6;/
139 /&#x22C6; 12 multichannel extension &#x22C6;/
140 /&#x22C6; 11-10 audio type (0=not spec, 1=language included) &#x22C6;/
141 /&#x22C6; 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) &#x22C6;/
142 /&#x22C6; 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, &#x22C6;/
143 /&#x22C6; 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) &#x22C6;/
144 /&#x22C6; 2- 0 number of audio channels (n+1 channels) &#x22C6;/
145</programlisting>
146 </section></section>
147<section id="audio_function_calls">
148<title>Audio Function Calls</title>
149
150
151<section id="audio_fopen">
152<title>open()</title>
153<para>DESCRIPTION
154</para>
155<informaltable><tgroup cols="1"><tbody><row><entry
156 align="char">
157<para>This system call opens a named audio device (e.g. /dev/dvb/adapter0/audio0)
158 for subsequent use. When an open() call has succeeded, the device will be ready
159 for use. The significance of blocking or non-blocking mode is described in the
160 documentation for functions where there is a difference. It does not affect the
161 semantics of the open() call itself. A device opened in blocking mode can later
162 be put into non-blocking mode (and vice versa) using the F_SETFL command
163 of the fcntl system call. This is a standard system call, documented in the Linux
164 manual page for fcntl. Only one user can open the Audio Device in O_RDWR
165 mode. All other attempts to open the device in this mode will fail, and an error
166 code will be returned. If the Audio Device is opened in O_RDONLY mode, the
167 only ioctl call that can be used is AUDIO_GET_STATUS. All other call will
168 return with an error code.</para>
169</entry>
170 </row></tbody></tgroup></informaltable>
171<para>SYNOPSIS
172</para>
173<informaltable><tgroup cols="1"><tbody><row><entry
174 align="char">
175<para>int open(const char &#x22C6;deviceName, int flags);</para>
176</entry>
177 </row></tbody></tgroup></informaltable>
178<para>PARAMETERS
179</para>
180<informaltable><tgroup cols="2"><tbody><row><entry
181 align="char">
182<para>const char
183 *deviceName</para>
184</entry><entry
185 align="char">
186<para>Name of specific audio device.</para>
187</entry>
188 </row><row><entry
189 align="char">
190<para>int flags</para>
191</entry><entry
192 align="char">
193<para>A bit-wise OR of the following flags:</para>
194</entry>
195 </row><row><entry
196 align="char">
197</entry><entry
198 align="char">
199<para>O_RDONLY read-only access</para>
200</entry>
201 </row><row><entry
202 align="char">
203</entry><entry
204 align="char">
205<para>O_RDWR read/write access</para>
206</entry>
207 </row><row><entry
208 align="char">
209</entry><entry
210 align="char">
211<para>O_NONBLOCK open in non-blocking mode</para>
212</entry>
213 </row><row><entry
214 align="char">
215</entry><entry
216 align="char">
217<para>(blocking mode is the default)</para>
218</entry>
219 </row></tbody></tgroup></informaltable>
220<para>ERRORS
221</para>
222<informaltable><tgroup cols="2"><tbody><row><entry
223 align="char">
224<para>ENODEV</para>
225</entry><entry
226 align="char">
227<para>Device driver not loaded/available.</para>
228</entry>
229 </row><row><entry
230 align="char">
231<para>EINTERNAL</para>
232</entry><entry
233 align="char">
234<para>Internal error.</para>
235</entry>
236 </row><row><entry
237 align="char">
238<para>EBUSY</para>
239</entry><entry
240 align="char">
241<para>Device or resource busy.</para>
242</entry>
243 </row><row><entry
244 align="char">
245<para>EINVAL</para>
246</entry><entry
247 align="char">
248<para>Invalid argument.</para>
249</entry>
250 </row></tbody></tgroup></informaltable>
251
252</section>
253<section id="audio_fclose">
254<title>close()</title>
255<para>DESCRIPTION
256</para>
257<informaltable><tgroup cols="1"><tbody><row><entry
258 align="char">
259<para>This system call closes a previously opened audio device.</para>
260</entry>
261 </row></tbody></tgroup></informaltable>
262<para>SYNOPSIS
263</para>
264<informaltable><tgroup cols="1"><tbody><row><entry
265 align="char">
266<para>int close(int fd);</para>
267</entry>
268 </row></tbody></tgroup></informaltable>
269<para>PARAMETERS
270</para>
271<informaltable><tgroup cols="2"><tbody><row><entry
272 align="char">
273<para>int fd</para>
274</entry><entry
275 align="char">
276<para>File descriptor returned by a previous call to open().</para>
277</entry>
278 </row></tbody></tgroup></informaltable>
279<para>ERRORS
280</para>
281<informaltable><tgroup cols="2"><tbody><row><entry
282 align="char">
283<para>EBADF</para>
284</entry><entry
285 align="char">
286<para>fd is not a valid open file descriptor.</para>
287</entry>
288 </row></tbody></tgroup></informaltable>
289
290</section>
291<section id="audio_fwrite">
292<title>write()</title>
293<para>DESCRIPTION
294</para>
295<informaltable><tgroup cols="1"><tbody><row><entry
296 align="char">
297<para>This system call can only be used if AUDIO_SOURCE_MEMORY is selected
298 in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
299 PES format. If O_NONBLOCK is not specified the function will block until
300 buffer space is available. The amount of data to be transferred is implied by
301 count.</para>
302</entry>
303 </row></tbody></tgroup></informaltable>
304<para>SYNOPSIS
305</para>
306<informaltable><tgroup cols="1"><tbody><row><entry
307 align="char">
308<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
309</entry>
310 </row></tbody></tgroup></informaltable>
311<para>PARAMETERS
312</para>
313<informaltable><tgroup cols="2"><tbody><row><entry
314 align="char">
315<para>int fd</para>
316</entry><entry
317 align="char">
318<para>File descriptor returned by a previous call to open().</para>
319</entry>
320 </row><row><entry
321 align="char">
322<para>void *buf</para>
323</entry><entry
324 align="char">
325<para>Pointer to the buffer containing the PES data.</para>
326</entry>
327 </row><row><entry
328 align="char">
329<para>size_t count</para>
330</entry><entry
331 align="char">
332<para>Size of buf.</para>
333</entry>
334 </row></tbody></tgroup></informaltable>
335<para>ERRORS
336</para>
337<informaltable><tgroup cols="2"><tbody><row><entry
338 align="char">
339<para>EPERM</para>
340</entry><entry
341 align="char">
342<para>Mode AUDIO_SOURCE_MEMORY not selected.</para>
343</entry>
344 </row><row><entry
345 align="char">
346<para>ENOMEM</para>
347</entry><entry
348 align="char">
349<para>Attempted to write more data than the internal buffer can
350 hold.</para>
351</entry>
352 </row><row><entry
353 align="char">
354<para>EBADF</para>
355</entry><entry
356 align="char">
357<para>fd is not a valid open file descriptor.</para>
358</entry>
359 </row></tbody></tgroup></informaltable>
360
361</section><section
362role="subsection"><title>AUDIO_STOP</title>
363<para>DESCRIPTION
364</para>
365<informaltable><tgroup cols="1"><tbody><row><entry
366 align="char">
367<para>This ioctl call asks the Audio Device to stop playing the current stream.</para>
368</entry>
369 </row></tbody></tgroup></informaltable>
370<para>SYNOPSIS
371</para>
372<informaltable><tgroup cols="1"><tbody><row><entry
373 align="char">
374<para>int ioctl(int fd, int request = AUDIO_STOP);</para>
375</entry>
376 </row></tbody></tgroup></informaltable>
377<para>PARAMETERS
378</para>
379<informaltable><tgroup cols="2"><tbody><row><entry
380 align="char">
381<para>int fd</para>
382</entry><entry
383 align="char">
384<para>File descriptor returned by a previous call to open().</para>
385</entry>
386 </row><row><entry
387 align="char">
388<para>int request</para>
389</entry><entry
390 align="char">
391<para>Equals AUDIO_STOP for this command.</para>
392</entry>
393 </row></tbody></tgroup></informaltable>
394<para>ERRORS
395</para>
396<informaltable><tgroup cols="2"><tbody><row><entry
397 align="char">
398<para>EBADF</para>
399</entry><entry
400 align="char">
401<para>fd is not a valid open file descriptor</para>
402</entry>
403 </row><row><entry
404 align="char">
405<para>EINTERNAL</para>
406</entry><entry
407 align="char">
408<para>Internal error.</para>
409</entry>
410 </row></tbody></tgroup></informaltable>
411
412</section><section
413role="subsection"><title>AUDIO_PLAY</title>
414<para>DESCRIPTION
415</para>
416<informaltable><tgroup cols="1"><tbody><row><entry
417 align="char">
418<para>This ioctl call asks the Audio Device to start playing an audio stream from the
419 selected source.</para>
420</entry>
421 </row></tbody></tgroup></informaltable>
422<para>SYNOPSIS
423</para>
424<informaltable><tgroup cols="1"><tbody><row><entry
425 align="char">
426<para>int ioctl(int fd, int request = AUDIO_PLAY);</para>
427</entry>
428 </row></tbody></tgroup></informaltable>
429<para>PARAMETERS
430</para>
431<informaltable><tgroup cols="2"><tbody><row><entry
432 align="char">
433<para>int fd</para>
434</entry><entry
435 align="char">
436<para>File descriptor returned by a previous call to open().</para>
437</entry>
438 </row><row><entry
439 align="char">
440<para>int request</para>
441</entry><entry
442 align="char">
443<para>Equals AUDIO_PLAY for this command.</para>
444</entry>
445 </row></tbody></tgroup></informaltable>
446<para>ERRORS
447</para>
448<informaltable><tgroup cols="2"><tbody><row><entry
449 align="char">
450<para>EBADF</para>
451</entry><entry
452 align="char">
453<para>fd is not a valid open file descriptor</para>
454</entry>
455 </row><row><entry
456 align="char">
457<para>EINTERNAL</para>
458</entry><entry
459 align="char">
460<para>Internal error.</para>
461</entry>
462 </row></tbody></tgroup></informaltable>
463
464</section><section
465role="subsection"><title>AUDIO_PAUSE</title>
466<para>DESCRIPTION
467</para>
468<informaltable><tgroup cols="1"><tbody><row><entry
469 align="char">
470<para>This ioctl call suspends the audio stream being played. Decoding and playing
471 are paused. It is then possible to restart again decoding and playing process of
472 the audio stream using AUDIO_CONTINUE command.</para>
473</entry>
474 </row><row><entry
475 align="char">
476<para>If AUDIO_SOURCE_MEMORY is selected in the ioctl call
477 AUDIO_SELECT_SOURCE, the DVB-subsystem will not decode (consume)
478 any more data until the ioctl call AUDIO_CONTINUE or AUDIO_PLAY is
479 performed.</para>
480</entry>
481 </row></tbody></tgroup></informaltable>
482<para>SYNOPSIS
483</para>
484<informaltable><tgroup cols="1"><tbody><row><entry
485 align="char">
486<para>int ioctl(int fd, int request = AUDIO_PAUSE);</para>
487</entry>
488 </row></tbody></tgroup></informaltable>
489<para>PARAMETERS
490</para>
491<informaltable><tgroup cols="2"><tbody><row><entry
492 align="char">
493<para>int fd</para>
494</entry><entry
495 align="char">
496<para>File descriptor returned by a previous call to open().</para>
497</entry>
498 </row><row><entry
499 align="char">
500<para>int request</para>
501</entry><entry
502 align="char">
503<para>Equals AUDIO_PAUSE for this command.</para>
504</entry>
505 </row></tbody></tgroup></informaltable>
506<para>ERRORS
507</para>
508<informaltable><tgroup cols="2"><tbody><row><entry
509 align="char">
510<para>EBADF</para>
511</entry><entry
512 align="char">
513<para>fd is not a valid open file descriptor.</para>
514</entry>
515 </row><row><entry
516 align="char">
517<para>EINTERNAL</para>
518</entry><entry
519 align="char">
520<para>Internal error.</para>
521</entry>
522 </row></tbody></tgroup></informaltable>
523
524</section><section
525role="subsection"><title>AUDIO_SELECT_SOURCE</title>
526<para>DESCRIPTION
527</para>
528<informaltable><tgroup cols="1"><tbody><row><entry
529 align="char">
530<para>This ioctl call informs the audio device which source shall be used
531 for the input data. The possible sources are demux or memory. If
532 AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
533 through the write command.</para>
534</entry>
535 </row></tbody></tgroup></informaltable>
536<para>SYNOPSIS
537</para>
538<informaltable><tgroup cols="1"><tbody><row><entry
539 align="char">
540<para>int ioctl(int fd, int request = AUDIO_SELECT_SOURCE,
541 audio_stream_source_t source);</para>
542</entry>
543 </row></tbody></tgroup></informaltable>
544<para>PARAMETERS
545</para>
546<informaltable><tgroup cols="2"><tbody><row><entry
547 align="char">
548<para>int fd</para>
549</entry><entry
550 align="char">
551<para>File descriptor returned by a previous call to open().</para>
552</entry>
553 </row><row><entry
554 align="char">
555<para>int request</para>
556</entry><entry
557 align="char">
558<para>Equals AUDIO_SELECT_SOURCE for this command.</para>
559</entry>
560 </row><row><entry
561 align="char">
562<para>audio_stream_source_t
563 source</para>
564</entry><entry
565 align="char">
566<para>Indicates the source that shall be used for the Audio
567 stream.</para>
568</entry>
569 </row></tbody></tgroup></informaltable>
570<para>ERRORS
571</para>
572<informaltable><tgroup cols="2"><tbody><row><entry
573 align="char">
574<para>EBADF</para>
575</entry><entry
576 align="char">
577<para>fd is not a valid open file descriptor.</para>
578</entry>
579 </row><row><entry
580 align="char">
581<para>EINTERNAL</para>
582</entry><entry
583 align="char">
584<para>Internal error.</para>
585</entry>
586 </row><row><entry
587 align="char">
588<para>EINVAL</para>
589</entry><entry
590 align="char">
591<para>Illegal input parameter.</para>
592</entry>
593 </row></tbody></tgroup></informaltable>
594
595</section><section
596role="subsection"><title>AUDIO_SET_MUTE</title>
597<para>DESCRIPTION
598</para>
599<informaltable><tgroup cols="1"><tbody><row><entry
600 align="char">
601<para>This ioctl call asks the audio device to mute the stream that is currently being
602 played.</para>
603</entry>
604 </row></tbody></tgroup></informaltable>
605<para>SYNOPSIS
606</para>
607<informaltable><tgroup cols="1"><tbody><row><entry
608 align="char">
609<para>int ioctl(int fd, int request = AUDIO_SET_MUTE,
610 boolean state);</para>
611</entry>
612 </row></tbody></tgroup></informaltable>
613<para>PARAMETERS
614</para>
615<informaltable><tgroup cols="2"><tbody><row><entry
616 align="char">
617<para>int fd</para>
618</entry><entry
619 align="char">
620<para>File descriptor returned by a previous call to open().</para>
621</entry>
622 </row><row><entry
623 align="char">
624<para>int request</para>
625</entry><entry
626 align="char">
627<para>Equals AUDIO_SET_MUTE for this command.</para>
628</entry>
629 </row><row><entry
630 align="char">
631<para>boolean state</para>
632</entry><entry
633 align="char">
634<para>Indicates if audio device shall mute or not.</para>
635</entry>
636 </row><row><entry
637 align="char">
638</entry><entry
639 align="char">
640<para>TRUE Audio Mute</para>
641</entry>
642 </row><row><entry
643 align="char">
644</entry><entry
645 align="char">
646<para>FALSE Audio Un-mute</para>
647</entry>
648 </row></tbody></tgroup></informaltable>
649<para>ERRORS
650</para>
651<informaltable><tgroup cols="2"><tbody><row><entry
652 align="char">
653<para>EBADF</para>
654</entry><entry
655 align="char">
656<para>fd is not a valid open file descriptor.</para>
657</entry>
658 </row><row><entry
659 align="char">
660<para>EINTERNAL</para>
661</entry><entry
662 align="char">
663<para>Internal error.</para>
664</entry>
665 </row><row><entry
666 align="char">
667<para>EINVAL</para>
668</entry><entry
669 align="char">
670<para>Illegal input parameter.</para>
671</entry>
672 </row></tbody></tgroup></informaltable>
673
674</section><section
675role="subsection"><title>AUDIO_SET_AV_SYNC</title>
676<para>DESCRIPTION
677</para>
678<informaltable><tgroup cols="1"><tbody><row><entry
679 align="char">
680<para>This ioctl call asks the Audio Device to turn ON or OFF A/V synchronization.</para>
681</entry>
682 </row></tbody></tgroup></informaltable>
683<para>SYNOPSIS
684</para>
685<informaltable><tgroup cols="1"><tbody><row><entry
686 align="char">
687<para>int ioctl(int fd, int request = AUDIO_SET_AV_SYNC,
688 boolean state);</para>
689</entry>
690 </row></tbody></tgroup></informaltable>
691<para>PARAMETERS
692</para>
693<informaltable><tgroup cols="2"><tbody><row><entry
694 align="char">
695<para>int fd</para>
696</entry><entry
697 align="char">
698<para>File descriptor returned by a previous call to open().</para>
699</entry>
700 </row><row><entry
701 align="char">
702<para>int request</para>
703</entry><entry
704 align="char">
705<para>Equals AUDIO_AV_SYNC for this command.</para>
706</entry>
707 </row><row><entry
708 align="char">
709<para>boolean state</para>
710</entry><entry
711 align="char">
712<para>Tells the DVB subsystem if A/V synchronization shall be
713 ON or OFF.</para>
714</entry>
715 </row><row><entry
716 align="char">
717</entry><entry
718 align="char">
719<para>TRUE AV-sync ON</para>
720</entry>
721 </row><row><entry
722 align="char">
723</entry><entry
724 align="char">
725<para>FALSE AV-sync OFF</para>
726</entry>
727 </row></tbody></tgroup></informaltable>
728<para>ERRORS
729</para>
730<informaltable><tgroup cols="2"><tbody><row><entry
731 align="char">
732<para>EBADF</para>
733</entry><entry
734 align="char">
735<para>fd is not a valid open file descriptor.</para>
736</entry>
737 </row><row><entry
738 align="char">
739<para>EINTERNAL</para>
740</entry><entry
741 align="char">
742<para>Internal error.</para>
743</entry>
744 </row><row><entry
745 align="char">
746<para>EINVAL</para>
747</entry><entry
748 align="char">
749<para>Illegal input parameter.</para>
750</entry>
751 </row></tbody></tgroup></informaltable>
752
753</section><section
754role="subsection"><title>AUDIO_SET_BYPASS_MODE</title>
755<para>DESCRIPTION
756</para>
757<informaltable><tgroup cols="1"><tbody><row><entry
758 align="char">
759<para>This ioctl call asks the Audio Device to bypass the Audio decoder and forward
760 the stream without decoding. This mode shall be used if streams that can&#8217;t be
761 handled by the DVB system shall be decoded. Dolby DigitalTM streams are
762 automatically forwarded by the DVB subsystem if the hardware can handle it.</para>
763</entry>
764 </row></tbody></tgroup></informaltable>
765<para>SYNOPSIS
766</para>
767<informaltable><tgroup cols="1"><tbody><row><entry
768 align="char">
769<para>int ioctl(int fd, int request =
770 AUDIO_SET_BYPASS_MODE, boolean mode);</para>
771</entry>
772 </row></tbody></tgroup></informaltable>
773<para>PARAMETERS
774</para>
775<informaltable><tgroup cols="2"><tbody><row><entry
776 align="char">
777<para>int fd</para>
778</entry><entry
779 align="char">
780<para>File descriptor returned by a previous call to open().</para>
781</entry>
782 </row><row><entry
783 align="char">
784<para>int request</para>
785</entry><entry
786 align="char">
787<para>Equals AUDIO_SET_BYPASS_MODE for this
788 command.</para>
789</entry>
790 </row><row><entry
791 align="char">
792<para>boolean mode</para>
793</entry><entry
794 align="char">
795<para>Enables or disables the decoding of the current Audio
796 stream in the DVB subsystem.</para>
797</entry>
798 </row><row><entry
799 align="char">
800</entry><entry
801 align="char">
802<para>TRUE Bypass is disabled</para>
803</entry>
804 </row><row><entry
805 align="char">
806</entry><entry
807 align="char">
808<para>FALSE Bypass is enabled</para>
809</entry>
810 </row></tbody></tgroup></informaltable>
811<para>ERRORS
812</para>
813<informaltable><tgroup cols="2"><tbody><row><entry
814 align="char">
815<para>EBADF</para>
816</entry><entry
817 align="char">
818<para>fd is not a valid open file descriptor.</para>
819</entry>
820 </row><row><entry
821 align="char">
822<para>EINTERNAL</para>
823</entry><entry
824 align="char">
825<para>Internal error.</para>
826</entry>
827 </row><row><entry
828 align="char">
829<para>EINVAL</para>
830</entry><entry
831 align="char">
832<para>Illegal input parameter.</para>
833</entry>
834 </row></tbody></tgroup></informaltable>
835
836</section><section
837role="subsection"><title>AUDIO_CHANNEL_SELECT</title>
838<para>DESCRIPTION
839</para>
840<informaltable><tgroup cols="1"><tbody><row><entry
841 align="char">
842<para>This ioctl call asks the Audio Device to select the requested channel if possible.</para>
843</entry>
844 </row></tbody></tgroup></informaltable>
845<para>SYNOPSIS
846</para>
847<informaltable><tgroup cols="1"><tbody><row><entry
848 align="char">
849<para>int ioctl(int fd, int request =
850 AUDIO_CHANNEL_SELECT, audio_channel_select_t);</para>
851</entry>
852 </row></tbody></tgroup></informaltable>
853<para>PARAMETERS
854</para>
855<informaltable><tgroup cols="2"><tbody><row><entry
856 align="char">
857<para>int fd</para>
858</entry><entry
859 align="char">
860<para>File descriptor returned by a previous call to open().</para>
861</entry>
862 </row><row><entry
863 align="char">
864<para>int request</para>
865</entry><entry
866 align="char">
867<para>Equals AUDIO_CHANNEL_SELECT for this
868 command.</para>
869</entry>
870 </row><row><entry
871 align="char">
872<para>audio_channel_select_t
873 ch</para>
874</entry><entry
875 align="char">
876<para>Select the output format of the audio (mono left/right,
877 stereo).</para>
878</entry>
879 </row></tbody></tgroup></informaltable>
880<para>ERRORS
881</para>
882<informaltable><tgroup cols="2"><tbody><row><entry
883 align="char">
884<para>EBADF</para>
885</entry><entry
886 align="char">
887<para>fd is not a valid open file descriptor.</para>
888</entry>
889 </row><row><entry
890 align="char">
891<para>EINTERNAL</para>
892</entry><entry
893 align="char">
894<para>Internal error.</para>
895</entry>
896 </row><row><entry
897 align="char">
898<para>EINVAL</para>
899</entry><entry
900 align="char">
901<para>Illegal input parameter ch.</para>
902</entry>
903 </row></tbody></tgroup></informaltable>
904
905</section><section
906role="subsection"><title>AUDIO_GET_STATUS</title>
907<para>DESCRIPTION
908</para>
909<informaltable><tgroup cols="1"><tbody><row><entry
910 align="char">
911<para>This ioctl call asks the Audio Device to return the current state of the Audio
912 Device.</para>
913</entry>
914 </row></tbody></tgroup></informaltable>
915<para>SYNOPSIS
916</para>
917<informaltable><tgroup cols="1"><tbody><row><entry
918 align="char">
919<para>int ioctl(int fd, int request = AUDIO_GET_STATUS,
920 struct audio_status &#x22C6;status);</para>
921</entry>
922 </row></tbody></tgroup></informaltable>
923<para>PARAMETERS
924</para>
925<informaltable><tgroup cols="2"><tbody><row><entry
926 align="char">
927<para>int fd</para>
928</entry><entry
929 align="char">
930<para>File descriptor returned by a previous call to open().</para>
931</entry>
932 </row><row><entry
933 align="char">
934<para>int request</para>
935</entry><entry
936 align="char">
937<para>Equals AUDIO_GET_STATUS for this command.</para>
938</entry>
939 </row><row><entry
940 align="char">
941<para>struct audio_status
942 *status</para>
943</entry><entry
944 align="char">
945<para>Returns the current state of Audio Device.</para>
946</entry>
947 </row></tbody></tgroup></informaltable>
948<para>ERRORS
949</para>
950<informaltable><tgroup cols="2"><tbody><row><entry
951 align="char">
952<para>EBADF</para>
953</entry><entry
954 align="char">
955<para>fd is not a valid open file descriptor.</para>
956</entry>
957 </row><row><entry
958 align="char">
959<para>EINTERNAL</para>
960</entry><entry
961 align="char">
962<para>Internal error.</para>
963</entry>
964 </row><row><entry
965 align="char">
966<para>EFAULT</para>
967</entry><entry
968 align="char">
969<para>status points to invalid address.</para>
970</entry>
971 </row></tbody></tgroup></informaltable>
972
973</section><section
974role="subsection"><title>AUDIO_GET_CAPABILITIES</title>
975<para>DESCRIPTION
976</para>
977<informaltable><tgroup cols="1"><tbody><row><entry
978 align="char">
979<para>This ioctl call asks the Audio Device to tell us about the decoding capabilities
980 of the audio hardware.</para>
981</entry>
982 </row></tbody></tgroup></informaltable>
983<para>SYNOPSIS
984</para>
985<informaltable><tgroup cols="1"><tbody><row><entry
986 align="char">
987<para>int ioctl(int fd, int request =
988 AUDIO_GET_CAPABILITIES, unsigned int &#x22C6;cap);</para>
989</entry>
990 </row></tbody></tgroup></informaltable>
991<para>PARAMETERS
992</para>
993<informaltable><tgroup cols="2"><tbody><row><entry
994 align="char">
995<para>int fd</para>
996</entry><entry
997 align="char">
998<para>File descriptor returned by a previous call to open().</para>
999</entry>
1000 </row><row><entry
1001 align="char">
1002<para>int request</para>
1003</entry><entry
1004 align="char">
1005<para>Equals AUDIO_GET_CAPABILITIES for this
1006 command.</para>
1007</entry>
1008 </row><row><entry
1009 align="char">
1010<para>unsigned int *cap</para>
1011</entry><entry
1012 align="char">
1013<para>Returns a bit array of supported sound formats.</para>
1014</entry>
1015 </row></tbody></tgroup></informaltable>
1016<para>ERRORS
1017</para>
1018<informaltable><tgroup cols="2"><tbody><row><entry
1019 align="char">
1020<para>EBADF</para>
1021</entry><entry
1022 align="char">
1023<para>fd is not a valid open file descriptor.</para>
1024</entry>
1025 </row><row><entry
1026 align="char">
1027<para>EINTERNAL</para>
1028</entry><entry
1029 align="char">
1030<para>Internal error.</para>
1031</entry>
1032 </row><row><entry
1033 align="char">
1034<para>EFAULT</para>
1035</entry><entry
1036 align="char">
1037<para>cap points to an invalid address.</para>
1038</entry>
1039 </row></tbody></tgroup></informaltable>
1040
1041</section><section
1042role="subsection"><title>AUDIO_CLEAR_BUFFER</title>
1043<para>DESCRIPTION
1044</para>
1045<informaltable><tgroup cols="1"><tbody><row><entry
1046 align="char">
1047<para>This ioctl call asks the Audio Device to clear all software and hardware buffers
1048 of the audio decoder device.</para>
1049</entry>
1050 </row></tbody></tgroup></informaltable>
1051<para>SYNOPSIS
1052</para>
1053<informaltable><tgroup cols="1"><tbody><row><entry
1054 align="char">
1055<para>int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER);</para>
1056</entry>
1057 </row></tbody></tgroup></informaltable>
1058<para>PARAMETERS
1059</para>
1060<informaltable><tgroup cols="2"><tbody><row><entry
1061 align="char">
1062<para>int fd</para>
1063</entry><entry
1064 align="char">
1065<para>File descriptor returned by a previous call to open().</para>
1066</entry>
1067 </row><row><entry
1068 align="char">
1069<para>int request</para>
1070</entry><entry
1071 align="char">
1072<para>Equals AUDIO_CLEAR_BUFFER for this command.</para>
1073</entry>
1074 </row></tbody></tgroup></informaltable>
1075<para>ERRORS
1076</para>
1077<informaltable><tgroup cols="2"><tbody><row><entry
1078 align="char">
1079<para>EBADF</para>
1080</entry><entry
1081 align="char">
1082<para>fd is not a valid open file descriptor.</para>
1083</entry>
1084 </row><row><entry
1085 align="char">
1086<para>EINTERNAL</para>
1087</entry><entry
1088 align="char">
1089<para>Internal error.</para>
1090</entry>
1091 </row></tbody></tgroup></informaltable>
1092
1093</section><section
1094role="subsection"><title>AUDIO_SET_ID</title>
1095<para>DESCRIPTION
1096</para>
1097<informaltable><tgroup cols="1"><tbody><row><entry
1098 align="char">
1099<para>This ioctl selects which sub-stream is to be decoded if a program or system
1100 stream is sent to the video device. If no audio stream type is set the id has to be
1101 in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for AC3 and in [0xA0,0xA7]
1102 for LPCM. More specifications may follow for other stream types. If the stream
1103 type is set the id just specifies the substream id of the audio stream and only
1104 the first 5 bits are recognized.</para>
1105</entry>
1106 </row></tbody></tgroup></informaltable>
1107<para>SYNOPSIS
1108</para>
1109<informaltable><tgroup cols="1"><tbody><row><entry
1110 align="char">
1111<para>int ioctl(int fd, int request = AUDIO_SET_ID, int
1112 id);</para>
1113</entry>
1114 </row></tbody></tgroup></informaltable>
1115<para>PARAMETERS
1116</para>
1117<informaltable><tgroup cols="2"><tbody><row><entry
1118 align="char">
1119<para>int fd</para>
1120</entry><entry
1121 align="char">
1122<para>File descriptor returned by a previous call to open().</para>
1123</entry>
1124 </row><row><entry
1125 align="char">
1126<para>int request</para>
1127</entry><entry
1128 align="char">
1129<para>Equals AUDIO_SET_ID for this command.</para>
1130</entry>
1131 </row><row><entry
1132 align="char">
1133<para>int id</para>
1134</entry><entry
1135 align="char">
1136<para>audio sub-stream id</para>
1137</entry>
1138 </row></tbody></tgroup></informaltable>
1139<para>ERRORS
1140</para>
1141<informaltable><tgroup cols="2"><tbody><row><entry
1142 align="char">
1143<para>EBADF</para>
1144</entry><entry
1145 align="char">
1146<para>fd is not a valid open file descriptor.</para>
1147</entry>
1148 </row><row><entry
1149 align="char">
1150<para>EINTERNAL</para>
1151</entry><entry
1152 align="char">
1153<para>Internal error.</para>
1154</entry>
1155 </row><row><entry
1156 align="char">
1157<para>EINVAL</para>
1158</entry><entry
1159 align="char">
1160<para>Invalid sub-stream id.</para>
1161</entry>
1162 </row></tbody></tgroup></informaltable>
1163
1164</section><section
1165role="subsection"><title>AUDIO_SET_MIXER</title>
1166<para>DESCRIPTION
1167</para>
1168<informaltable><tgroup cols="1"><tbody><row><entry
1169 align="char">
1170<para>This ioctl lets you adjust the mixer settings of the audio decoder.</para>
1171</entry>
1172 </row></tbody></tgroup></informaltable>
1173<para>SYNOPSIS
1174</para>
1175<informaltable><tgroup cols="1"><tbody><row><entry
1176 align="char">
1177<para>int ioctl(int fd, int request = AUDIO_SET_MIXER,
1178 audio_mixer_t &#x22C6;mix);</para>
1179</entry>
1180 </row></tbody></tgroup></informaltable>
1181<para>PARAMETERS
1182</para>
1183<informaltable><tgroup cols="2"><tbody><row><entry
1184 align="char">
1185<para>int fd</para>
1186</entry><entry
1187 align="char">
1188<para>File descriptor returned by a previous call to open().</para>
1189</entry>
1190 </row><row><entry
1191 align="char">
1192<para>int request</para>
1193</entry><entry
1194 align="char">
1195<para>Equals AUDIO_SET_ID for this command.</para>
1196</entry>
1197 </row><row><entry
1198 align="char">
1199<para>audio_mixer_t *mix</para>
1200</entry><entry
1201 align="char">
1202<para>mixer settings.</para>
1203</entry>
1204 </row></tbody></tgroup></informaltable>
1205<para>ERRORS
1206</para>
1207<informaltable><tgroup cols="2"><tbody><row><entry
1208 align="char">
1209<para>EBADF</para>
1210</entry><entry
1211 align="char">
1212<para>fd is not a valid open file descriptor.</para>
1213</entry>
1214 </row><row><entry
1215 align="char">
1216<para>EINTERNAL</para>
1217</entry><entry
1218 align="char">
1219<para>Internal error.</para>
1220</entry>
1221 </row><row><entry
1222 align="char">
1223<para>EFAULT</para>
1224</entry><entry
1225 align="char">
1226<para>mix points to an invalid address.</para>
1227</entry>
1228 </row></tbody></tgroup></informaltable>
1229
1230</section><section
1231role="subsection"><title>AUDIO_SET_STREAMTYPE</title>
1232<para>DESCRIPTION
1233</para>
1234<informaltable><tgroup cols="1"><tbody><row><entry
1235 align="char">
1236<para>This ioctl tells the driver which kind of audio stream to expect. This is useful
1237 if the stream offers several audio sub-streams like LPCM and AC3.</para>
1238</entry>
1239 </row></tbody></tgroup></informaltable>
1240<para>SYNOPSIS
1241</para>
1242<informaltable><tgroup cols="1"><tbody><row><entry
1243 align="char">
1244<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE,
1245 int type);</para>
1246</entry>
1247 </row></tbody></tgroup></informaltable>
1248<para>PARAMETERS
1249</para>
1250<informaltable><tgroup cols="2"><tbody><row><entry
1251 align="char">
1252<para>int fd</para>
1253</entry><entry
1254 align="char">
1255<para>File descriptor returned by a previous call to open().</para>
1256</entry>
1257 </row><row><entry
1258 align="char">
1259<para>int request</para>
1260</entry><entry
1261 align="char">
1262<para>Equals AUDIO_SET_STREAMTYPE for this
1263 command.</para>
1264</entry>
1265 </row><row><entry
1266 align="char">
1267<para>int type</para>
1268</entry><entry
1269 align="char">
1270<para>stream type</para>
1271</entry>
1272 </row></tbody></tgroup></informaltable>
1273<para>ERRORS
1274</para>
1275<informaltable><tgroup cols="2"><tbody><row><entry
1276 align="char">
1277<para>EBADF</para>
1278</entry><entry
1279 align="char">
1280<para>fd is not a valid open file descriptor</para>
1281</entry>
1282 </row><row><entry
1283 align="char">
1284<para>EINVAL</para>
1285</entry><entry
1286 align="char">
1287<para>type is not a valid or supported stream type.</para>
1288</entry>
1289 </row></tbody></tgroup></informaltable>
1290
1291</section><section
1292role="subsection"><title>AUDIO_SET_EXT_ID</title>
1293<para>DESCRIPTION
1294</para>
1295<informaltable><tgroup cols="1"><tbody><row><entry
1296 align="char">
1297<para>This ioctl can be used to set the extension id for MPEG streams in DVD
1298 playback. Only the first 3 bits are recognized.</para>
1299</entry>
1300 </row></tbody></tgroup></informaltable>
1301<para>SYNOPSIS
1302</para>
1303<informaltable><tgroup cols="1"><tbody><row><entry
1304 align="char">
1305<para>int ioctl(fd, int request = AUDIO_SET_EXT_ID, int
1306 id);</para>
1307</entry>
1308 </row></tbody></tgroup></informaltable>
1309<para>PARAMETERS
1310</para>
1311<informaltable><tgroup cols="2"><tbody><row><entry
1312 align="char">
1313<para>int fd</para>
1314</entry><entry
1315 align="char">
1316<para>File descriptor returned by a previous call to open().</para>
1317</entry>
1318 </row><row><entry
1319 align="char">
1320<para>int request</para>
1321</entry><entry
1322 align="char">
1323<para>Equals AUDIO_SET_EXT_ID for this command.</para>
1324</entry>
1325 </row><row><entry
1326 align="char">
1327<para>int id</para>
1328</entry><entry
1329 align="char">
1330<para>audio sub_stream_id</para>
1331</entry>
1332 </row></tbody></tgroup></informaltable>
1333<para>ERRORS
1334</para>
1335<informaltable><tgroup cols="2"><tbody><row><entry
1336 align="char">
1337<para>EBADF</para>
1338</entry><entry
1339 align="char">
1340<para>fd is not a valid open file descriptor</para>
1341</entry>
1342 </row><row><entry
1343 align="char">
1344<para>EINVAL</para>
1345</entry><entry
1346 align="char">
1347<para>id is not a valid id.</para>
1348</entry>
1349 </row></tbody></tgroup></informaltable>
1350
1351</section><section
1352role="subsection"><title>AUDIO_SET_ATTRIBUTES</title>
1353<para>DESCRIPTION
1354</para>
1355<informaltable><tgroup cols="1"><tbody><row><entry
1356 align="char">
1357<para>This ioctl is intended for DVD playback and allows you to set certain
1358 information about the audio stream.</para>
1359</entry>
1360 </row></tbody></tgroup></informaltable>
1361<para>SYNOPSIS
1362</para>
1363<informaltable><tgroup cols="1"><tbody><row><entry
1364 align="char">
1365<para>int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES,
1366 audio_attributes_t attr );</para>
1367</entry>
1368 </row></tbody></tgroup></informaltable>
1369<para>PARAMETERS
1370</para>
1371<informaltable><tgroup cols="2"><tbody><row><entry
1372 align="char">
1373<para>int fd</para>
1374</entry><entry
1375 align="char">
1376<para>File descriptor returned by a previous call to open().</para>
1377</entry>
1378 </row><row><entry
1379 align="char">
1380<para>int request</para>
1381</entry><entry
1382 align="char">
1383<para>Equals AUDIO_SET_ATTRIBUTES for this command.</para>
1384</entry>
1385 </row><row><entry
1386 align="char">
1387<para>audio_attributes_t
1388 attr</para>
1389</entry><entry
1390 align="char">
1391<para>audio attributes according to section ??</para>
1392</entry>
1393 </row></tbody></tgroup></informaltable>
1394<para>ERRORS
1395</para>
1396<informaltable><tgroup cols="2"><tbody><row><entry
1397 align="char">
1398<para>EBADF</para>
1399</entry><entry
1400 align="char">
1401<para>fd is not a valid open file descriptor</para>
1402</entry>
1403 </row><row><entry
1404 align="char">
1405<para>EINVAL</para>
1406</entry><entry
1407 align="char">
1408<para>attr is not a valid or supported attribute setting.</para>
1409</entry>
1410 </row></tbody></tgroup></informaltable>
1411
1412</section><section
1413role="subsection"><title>AUDIO_SET_KARAOKE</title>
1414<para>DESCRIPTION
1415</para>
1416<informaltable><tgroup cols="1"><tbody><row><entry
1417 align="char">
1418<para>This ioctl allows one to set the mixer settings for a karaoke DVD.</para>
1419</entry>
1420 </row></tbody></tgroup></informaltable>
1421<para>SYNOPSIS
1422</para>
1423<informaltable><tgroup cols="1"><tbody><row><entry
1424 align="char">
1425<para>int ioctl(fd, int request = AUDIO_SET_STREAMTYPE,
1426 audio_karaoke_t &#x22C6;karaoke);</para>
1427</entry>
1428 </row></tbody></tgroup></informaltable>
1429<para>PARAMETERS
1430</para>
1431<informaltable><tgroup cols="2"><tbody><row><entry
1432 align="char">
1433<para>int fd</para>
1434</entry><entry
1435 align="char">
1436<para>File descriptor returned by a previous call to open().</para>
1437</entry>
1438 </row><row><entry
1439 align="char">
1440<para>int request</para>
1441</entry><entry
1442 align="char">
1443<para>Equals AUDIO_SET_STREAMTYPE for this
1444 command.</para>
1445</entry>
1446 </row><row><entry
1447 align="char">
1448<para>audio_karaoke_t
1449 *karaoke</para>
1450</entry><entry
1451 align="char">
1452<para>karaoke settings according to section ??.</para>
1453</entry>
1454 </row></tbody></tgroup></informaltable>
1455<para>ERRORS
1456</para>
1457<informaltable><tgroup cols="2"><tbody><row><entry
1458 align="char">
1459<para>EBADF</para>
1460</entry><entry
1461 align="char">
1462<para>fd is not a valid open file descriptor</para>
1463</entry>
1464 </row><row><entry
1465 align="char">
1466<para>EINVAL</para>
1467</entry><entry
1468 align="char">
1469<para>karaoke is not a valid or supported karaoke setting.</para>
1470</entry>
1471 </row></tbody></tgroup></informaltable>
1472 </section>
1473</section>
diff --git a/Documentation/DocBook/media/dvb/ca.xml b/Documentation/DocBook/media/dvb/ca.xml
new file mode 100644
index 000000000000..b1f1d2fad654
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/ca.xml
@@ -0,0 +1,221 @@
1<title>DVB CA Device</title>
2<para>The DVB CA device controls the conditional access hardware. It can be accessed through
3<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by
4including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application.
5</para>
6
7<section id="ca_data_types">
8<title>CA Data Types</title>
9
10
11<section id="ca_slot_info_t">
12<title>ca_slot_info_t</title>
13 <programlisting>
14 /&#x22C6; slot interface types and info &#x22C6;/
15
16 typedef struct ca_slot_info_s {
17 int num; /&#x22C6; slot number &#x22C6;/
18
19 int type; /&#x22C6; CA interface this slot supports &#x22C6;/
20 #define CA_CI 1 /&#x22C6; CI high level interface &#x22C6;/
21 #define CA_CI_LINK 2 /&#x22C6; CI link layer level interface &#x22C6;/
22 #define CA_CI_PHYS 4 /&#x22C6; CI physical layer level interface &#x22C6;/
23 #define CA_SC 128 /&#x22C6; simple smart card interface &#x22C6;/
24
25 unsigned int flags;
26 #define CA_CI_MODULE_PRESENT 1 /&#x22C6; module (or card) inserted &#x22C6;/
27 #define CA_CI_MODULE_READY 2
28 } ca_slot_info_t;
29</programlisting>
30
31</section>
32<section id="ca_descr_info_t">
33<title>ca_descr_info_t</title>
34 <programlisting>
35 typedef struct ca_descr_info_s {
36 unsigned int num; /&#x22C6; number of available descramblers (keys) &#x22C6;/
37 unsigned int type; /&#x22C6; type of supported scrambling system &#x22C6;/
38 #define CA_ECD 1
39 #define CA_NDS 2
40 #define CA_DSS 4
41 } ca_descr_info_t;
42</programlisting>
43
44</section>
45<section id="ca_cap_t">
46<title>ca_cap_t</title>
47 <programlisting>
48 typedef struct ca_cap_s {
49 unsigned int slot_num; /&#x22C6; total number of CA card and module slots &#x22C6;/
50 unsigned int slot_type; /&#x22C6; OR of all supported types &#x22C6;/
51 unsigned int descr_num; /&#x22C6; total number of descrambler slots (keys) &#x22C6;/
52 unsigned int descr_type;/&#x22C6; OR of all supported types &#x22C6;/
53 } ca_cap_t;
54</programlisting>
55
56</section>
57<section id="ca_msg_t">
58<title>ca_msg_t</title>
59 <programlisting>
60 /&#x22C6; a message to/from a CI-CAM &#x22C6;/
61 typedef struct ca_msg_s {
62 unsigned int index;
63 unsigned int type;
64 unsigned int length;
65 unsigned char msg[256];
66 } ca_msg_t;
67</programlisting>
68
69</section>
70<section id="ca_descr_t">
71<title>ca_descr_t</title>
72 <programlisting>
73 typedef struct ca_descr_s {
74 unsigned int index;
75 unsigned int parity;
76 unsigned char cw[8];
77 } ca_descr_t;
78</programlisting>
79 </section></section>
80<section id="ca_function_calls">
81<title>CA Function Calls</title>
82
83
84<section id="ca_fopen">
85<title>open()</title>
86<para>DESCRIPTION
87</para>
88<informaltable><tgroup cols="1"><tbody><row><entry
89 align="char">
90<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para>
91<para>When an open() call has succeeded, the device will be ready for use.
92 The significance of blocking or non-blocking mode is described in the
93 documentation for functions where there is a difference. It does not affect the
94 semantics of the open() call itself. A device opened in blocking mode can later
95 be put into non-blocking mode (and vice versa) using the F_SETFL command
96 of the fcntl system call. This is a standard system call, documented in the Linux
97 manual page for fcntl. Only one user can open the CA Device in O_RDWR
98 mode. All other attempts to open the device in this mode will fail, and an error
99 code will be returned.</para>
100</entry>
101 </row></tbody></tgroup></informaltable>
102<para>SYNOPSIS
103</para>
104<informaltable><tgroup cols="1"><tbody><row><entry
105 align="char">
106<para>int open(const char &#x22C6;deviceName, int flags);</para>
107</entry>
108 </row></tbody></tgroup></informaltable>
109<para>PARAMETERS
110</para>
111<informaltable><tgroup cols="2"><tbody><row><entry
112 align="char">
113<para>const char
114 *deviceName</para>
115</entry><entry
116 align="char">
117<para>Name of specific video device.</para>
118</entry>
119 </row><row><entry
120 align="char">
121<para>int flags</para>
122</entry><entry
123 align="char">
124<para>A bit-wise OR of the following flags:</para>
125</entry>
126 </row><row><entry
127 align="char">
128</entry><entry
129 align="char">
130<para>O_RDONLY read-only access</para>
131</entry>
132 </row><row><entry
133 align="char">
134</entry><entry
135 align="char">
136<para>O_RDWR read/write access</para>
137</entry>
138 </row><row><entry
139 align="char">
140</entry><entry
141 align="char">
142<para>O_NONBLOCK open in non-blocking mode</para>
143</entry>
144 </row><row><entry
145 align="char">
146</entry><entry
147 align="char">
148<para>(blocking mode is the default)</para>
149</entry>
150 </row></tbody></tgroup></informaltable>
151<para>ERRORS
152</para>
153<informaltable><tgroup cols="2"><tbody><row><entry
154 align="char">
155<para>ENODEV</para>
156</entry><entry
157 align="char">
158<para>Device driver not loaded/available.</para>
159</entry>
160 </row><row><entry
161 align="char">
162<para>EINTERNAL</para>
163</entry><entry
164 align="char">
165<para>Internal error.</para>
166</entry>
167 </row><row><entry
168 align="char">
169<para>EBUSY</para>
170</entry><entry
171 align="char">
172<para>Device or resource busy.</para>
173</entry>
174 </row><row><entry
175 align="char">
176<para>EINVAL</para>
177</entry><entry
178 align="char">
179<para>Invalid argument.</para>
180</entry>
181 </row></tbody></tgroup></informaltable>
182
183</section>
184<section id="ca_fclose">
185<title>close()</title>
186<para>DESCRIPTION
187</para>
188<informaltable><tgroup cols="1"><tbody><row><entry
189 align="char">
190<para>This system call closes a previously opened audio device.</para>
191</entry>
192 </row></tbody></tgroup></informaltable>
193<para>SYNOPSIS
194</para>
195<informaltable><tgroup cols="1"><tbody><row><entry
196 align="char">
197<para>int close(int fd);</para>
198</entry>
199 </row></tbody></tgroup></informaltable>
200<para>PARAMETERS
201</para>
202<informaltable><tgroup cols="2"><tbody><row><entry
203 align="char">
204<para>int fd</para>
205</entry><entry
206 align="char">
207<para>File descriptor returned by a previous call to open().</para>
208</entry>
209 </row></tbody></tgroup></informaltable>
210<para>ERRORS
211</para>
212<informaltable><tgroup cols="2"><tbody><row><entry
213 align="char">
214<para>EBADF</para>
215</entry><entry
216 align="char">
217<para>fd is not a valid open file descriptor.</para>
218</entry>
219 </row></tbody></tgroup></informaltable>
220 </section>
221</section>
diff --git a/Documentation/DocBook/media/dvb/demux.xml b/Documentation/DocBook/media/dvb/demux.xml
new file mode 100644
index 000000000000..1b8c4e9835b9
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/demux.xml
@@ -0,0 +1,973 @@
1<title>DVB Demux Device</title>
2
3<para>The DVB demux device controls the filters of the DVB hardware/software. It can be
4accessed through <emphasis role="tt">/dev/adapter0/demux0</emphasis>. Data types and and ioctl definitions can be
5accessed by including <emphasis role="tt">linux/dvb/dmx.h</emphasis> in your application.
6</para>
7<section id="dmx_types">
8<title>Demux Data Types</title>
9
10<section id="dmx_output_t">
11<title>dmx_output_t</title>
12 <programlisting>
13 typedef enum
14 {
15 DMX_OUT_DECODER,
16 DMX_OUT_TAP,
17 DMX_OUT_TS_TAP
18 } dmx_output_t;
19</programlisting>
20<para><emphasis role="tt">DMX_OUT_TAP</emphasis> delivers the stream output to the demux device on which the ioctl is
21called.
22</para>
23<para><emphasis role="tt">DMX_OUT_TS_TAP</emphasis> routes output to the logical DVR device <emphasis role="tt">/dev/dvb/adapter0/dvr0</emphasis>,
24which delivers a TS multiplexed from all filters for which <emphasis role="tt">DMX_OUT_TS_TAP</emphasis> was
25specified.
26</para>
27</section>
28
29<section id="dmx_input_t">
30<title>dmx_input_t</title>
31 <programlisting>
32 typedef enum
33 {
34 DMX_IN_FRONTEND,
35 DMX_IN_DVR
36 } dmx_input_t;
37</programlisting>
38</section>
39
40<section id="dmx_pes_type_t">
41<title>dmx_pes_type_t</title>
42 <programlisting>
43 typedef enum
44 {
45 DMX_PES_AUDIO,
46 DMX_PES_VIDEO,
47 DMX_PES_TELETEXT,
48 DMX_PES_SUBTITLE,
49 DMX_PES_PCR,
50 DMX_PES_OTHER
51 } dmx_pes_type_t;
52</programlisting>
53</section>
54
55<section id="dmx_event_t">
56<title>dmx_event_t</title>
57 <programlisting>
58 typedef enum
59 {
60 DMX_SCRAMBLING_EV,
61 DMX_FRONTEND_EV
62 } dmx_event_t;
63</programlisting>
64</section>
65
66<section id="dmx_scrambling_status_t">
67<title>dmx_scrambling_status_t</title>
68 <programlisting>
69 typedef enum
70 {
71 DMX_SCRAMBLING_OFF,
72 DMX_SCRAMBLING_ON
73 } dmx_scrambling_status_t;
74</programlisting>
75</section>
76
77<section id="dmx_filter">
78<title>struct dmx_filter</title>
79 <programlisting>
80 typedef struct dmx_filter
81 {
82 uint8_t filter[DMX_FILTER_SIZE];
83 uint8_t mask[DMX_FILTER_SIZE];
84 } dmx_filter_t;
85</programlisting>
86</section>
87
88<section id="dmx_sct_filter_params">
89<title>struct dmx_sct_filter_params</title>
90 <programlisting>
91 struct dmx_sct_filter_params
92 {
93 uint16_t pid;
94 dmx_filter_t filter;
95 uint32_t timeout;
96 uint32_t flags;
97 #define DMX_CHECK_CRC 1
98 #define DMX_ONESHOT 2
99 #define DMX_IMMEDIATE_START 4
100 };
101</programlisting>
102</section>
103
104<section id="dmx_pes_filter_params">
105<title>struct dmx_pes_filter_params</title>
106 <programlisting>
107 struct dmx_pes_filter_params
108 {
109 uint16_t pid;
110 dmx_input_t input;
111 dmx_output_t output;
112 dmx_pes_type_t pes_type;
113 uint32_t flags;
114 };
115</programlisting>
116</section>
117
118<section id="dmx_event">
119<title>struct dmx_event</title>
120 <programlisting>
121 struct dmx_event
122 {
123 dmx_event_t event;
124 time_t timeStamp;
125 union
126 {
127 dmx_scrambling_status_t scrambling;
128 } u;
129 };
130</programlisting>
131</section>
132
133<section id="dmx_stc">
134<title>struct dmx_stc</title>
135 <programlisting>
136 struct dmx_stc {
137 unsigned int num; /&#x22C6; input : which STC? 0..N &#x22C6;/
138 unsigned int base; /&#x22C6; output: divisor for stc to get 90 kHz clock &#x22C6;/
139 uint64_t stc; /&#x22C6; output: stc in 'base'&#x22C6;90 kHz units &#x22C6;/
140 };
141</programlisting>
142 </section>
143
144</section>
145
146<section id="dmx_fcalls">
147<title>Demux Function Calls</title>
148
149<section id="dmx_fopen">
150<title>open()</title>
151<para>DESCRIPTION
152</para>
153<informaltable><tgroup cols="1"><tbody><row><entry
154 align="char">
155<para>This system call, used with a device name of /dev/dvb/adapter0/demux0,
156 allocates a new filter and returns a handle which can be used for subsequent
157 control of that filter. This call has to be made for each filter to be used, i.e. every
158 returned file descriptor is a reference to a single filter. /dev/dvb/adapter0/dvr0
159 is a logical device to be used for retrieving Transport Streams for digital
160 video recording. When reading from this device a transport stream containing
161 the packets from all PES filters set in the corresponding demux device
162 (/dev/dvb/adapter0/demux0) having the output set to DMX_OUT_TS_TAP. A
163 recorded Transport Stream is replayed by writing to this device. </para>
164<para>The significance of blocking or non-blocking mode is described in the
165 documentation for functions where there is a difference. It does not affect the
166 semantics of the open() call itself. A device opened in blocking mode can later
167 be put into non-blocking mode (and vice versa) using the F_SETFL command
168 of the fcntl system call.</para>
169</entry>
170 </row></tbody></tgroup></informaltable>
171<para>SYNOPSIS
172</para>
173<informaltable><tgroup cols="1"><tbody><row><entry
174 align="char">
175<para>int open(const char &#x22C6;deviceName, int flags);</para>
176</entry>
177 </row></tbody></tgroup></informaltable>
178<para>PARAMETERS
179</para>
180<informaltable><tgroup cols="2"><tbody><row><entry
181 align="char">
182<para>const char
183 *deviceName</para>
184</entry><entry
185 align="char">
186<para>Name of demux device.</para>
187</entry>
188 </row><row><entry
189 align="char">
190<para>int flags</para>
191</entry><entry
192 align="char">
193<para>A bit-wise OR of the following flags:</para>
194</entry>
195 </row><row><entry
196 align="char">
197</entry><entry
198 align="char">
199<para>O_RDWR read/write access</para>
200</entry>
201 </row><row><entry
202 align="char">
203</entry><entry
204 align="char">
205<para>O_NONBLOCK open in non-blocking mode</para>
206</entry>
207 </row><row><entry
208 align="char">
209</entry><entry
210 align="char">
211<para>(blocking mode is the default)</para>
212</entry>
213 </row></tbody></tgroup></informaltable>
214<para>ERRORS
215</para>
216<informaltable><tgroup cols="2"><tbody><row><entry
217 align="char">
218<para>ENODEV</para>
219</entry><entry
220 align="char">
221<para>Device driver not loaded/available.</para>
222</entry>
223 </row><row><entry
224 align="char">
225<para>EINVAL</para>
226</entry><entry
227 align="char">
228<para>Invalid argument.</para>
229</entry>
230 </row><row><entry
231 align="char">
232<para>EMFILE</para>
233</entry><entry
234 align="char">
235<para>&#8220;Too many open files&#8221;, i.e. no more filters available.</para>
236</entry>
237 </row><row><entry
238 align="char">
239<para>ENOMEM</para>
240</entry><entry
241 align="char">
242<para>The driver failed to allocate enough memory.</para>
243</entry>
244 </row></tbody></tgroup></informaltable>
245</section>
246
247<section id="dmx_fclose">
248<title>close()</title>
249<para>DESCRIPTION
250</para>
251<informaltable><tgroup cols="1"><tbody><row><entry
252 align="char">
253<para>This system call deactivates and deallocates a filter that was previously
254 allocated via the open() call.</para>
255</entry>
256 </row></tbody></tgroup></informaltable>
257<para>SYNOPSIS
258</para>
259<informaltable><tgroup cols="1"><tbody><row><entry
260 align="char">
261<para>int close(int fd);</para>
262</entry>
263 </row></tbody></tgroup></informaltable>
264<para>PARAMETERS
265</para>
266<informaltable><tgroup cols="2"><tbody><row><entry
267 align="char">
268<para>int fd</para>
269</entry><entry
270 align="char">
271<para>File descriptor returned by a previous call to open().</para>
272</entry>
273 </row></tbody></tgroup></informaltable>
274<para>ERRORS
275</para>
276<informaltable><tgroup cols="2"><tbody><row><entry
277 align="char">
278<para>EBADF</para>
279</entry><entry
280 align="char">
281<para>fd is not a valid open file descriptor.</para>
282</entry>
283 </row></tbody></tgroup></informaltable>
284</section>
285
286<section id="dmx_fread">
287<title>read()</title>
288<para>DESCRIPTION
289</para>
290<informaltable><tgroup cols="1"><tbody><row><entry
291 align="char">
292<para>This system call returns filtered data, which might be section or PES data. The
293 filtered data is transferred from the driver&#8217;s internal circular buffer to buf. The
294 maximum amount of data to be transferred is implied by count.</para>
295</entry>
296 </row><row><entry
297 align="char">
298<para>When returning section data the driver always tries to return a complete single
299 section (even though buf would provide buffer space for more data). If the size
300 of the buffer is smaller than the section as much as possible will be returned,
301 and the remaining data will be provided in subsequent calls.</para>
302</entry>
303 </row><row><entry
304 align="char">
305<para>The size of the internal buffer is 2 * 4096 bytes (the size of two maximum
306 sized sections) by default. The size of this buffer may be changed by using the
307 DMX_SET_BUFFER_SIZE function. If the buffer is not large enough, or if
308 the read operations are not performed fast enough, this may result in a buffer
309 overflow error. In this case EOVERFLOW will be returned, and the circular
310 buffer will be emptied. This call is blocking if there is no data to return, i.e. the
311 process will be put to sleep waiting for data, unless the O_NONBLOCK flag
312 is specified.</para>
313</entry>
314 </row><row><entry
315 align="char">
316<para>Note that in order to be able to read, the filtering process has to be started
317 by defining either a section or a PES filter by means of the ioctl functions,
318 and then starting the filtering process via the DMX_START ioctl function
319 or by setting the DMX_IMMEDIATE_START flag. If the reading is done
320 from a logical DVR demux device, the data will constitute a Transport Stream
321 including the packets from all PES filters in the corresponding demux device
322 /dev/dvb/adapter0/demux0 having the output set to DMX_OUT_TS_TAP.</para>
323</entry>
324 </row></tbody></tgroup></informaltable>
325<para>SYNOPSIS
326</para>
327<informaltable><tgroup cols="1"><tbody><row><entry
328 align="char">
329<para>size_t read(int fd, void &#x22C6;buf, size_t count);</para>
330</entry>
331 </row></tbody></tgroup></informaltable>
332<para>PARAMETERS
333</para>
334<informaltable><tgroup cols="2"><tbody><row><entry
335 align="char">
336<para>int fd</para>
337</entry><entry
338 align="char">
339<para>File descriptor returned by a previous call to open().</para>
340</entry>
341 </row><row><entry
342 align="char">
343<para>void *buf</para>
344</entry><entry
345 align="char">
346<para>Pointer to the buffer to be used for returned filtered data.</para>
347</entry>
348 </row><row><entry
349 align="char">
350<para>size_t count</para>
351</entry><entry
352 align="char">
353<para>Size of buf.</para>
354</entry>
355 </row></tbody></tgroup></informaltable>
356<para>ERRORS
357</para>
358<informaltable><tgroup cols="2"><tbody><row><entry
359 align="char">
360<para>EWOULDBLOCK</para>
361</entry><entry
362 align="char">
363<para>No data to return and O_NONBLOCK was specified.</para>
364</entry>
365 </row><row><entry
366 align="char">
367<para>EBADF</para>
368</entry><entry
369 align="char">
370<para>fd is not a valid open file descriptor.</para>
371</entry>
372 </row><row><entry
373 align="char">
374<para>ECRC</para>
375</entry><entry
376 align="char">
377<para>Last section had a CRC error - no data returned. The
378 buffer is flushed.</para>
379</entry>
380 </row><row><entry
381 align="char">
382<para>EOVERFLOW</para>
383</entry><entry
384 align="char">
385</entry>
386 </row><row><entry
387 align="char">
388</entry><entry
389 align="char">
390<para>The filtered data was not read from the buffer in due
391 time, resulting in non-read data being lost. The buffer is
392 flushed.</para>
393</entry>
394 </row><row><entry
395 align="char">
396<para>ETIMEDOUT</para>
397</entry><entry
398 align="char">
399<para>The section was not loaded within the stated timeout
400 period. See ioctl DMX_SET_FILTER for how to set a
401 timeout.</para>
402</entry>
403 </row><row><entry
404 align="char">
405<para>EFAULT</para>
406</entry><entry
407 align="char">
408<para>The driver failed to write to the callers buffer due to an
409 invalid *buf pointer.</para>
410</entry>
411 </row></tbody></tgroup></informaltable>
412</section>
413
414<section id="dmx_fwrite">
415<title>write()</title>
416<para>DESCRIPTION
417</para>
418<informaltable><tgroup cols="1"><tbody><row><entry
419 align="char">
420<para>This system call is only provided by the logical device /dev/dvb/adapter0/dvr0,
421 associated with the physical demux device that provides the actual DVR
422 functionality. It is used for replay of a digitally recorded Transport Stream.
423 Matching filters have to be defined in the corresponding physical demux
424 device, /dev/dvb/adapter0/demux0. The amount of data to be transferred is
425 implied by count.</para>
426</entry>
427 </row></tbody></tgroup></informaltable>
428<para>SYNOPSIS
429</para>
430<informaltable><tgroup cols="1"><tbody><row><entry
431 align="char">
432<para>ssize_t write(int fd, const void &#x22C6;buf, size_t
433 count);</para>
434</entry>
435 </row></tbody></tgroup></informaltable>
436<para>PARAMETERS
437</para>
438<informaltable><tgroup cols="2"><tbody><row><entry
439 align="char">
440<para>int fd</para>
441</entry><entry
442 align="char">
443<para>File descriptor returned by a previous call to open().</para>
444</entry>
445 </row><row><entry
446 align="char">
447<para>void *buf</para>
448</entry><entry
449 align="char">
450<para>Pointer to the buffer containing the Transport Stream.</para>
451</entry>
452 </row><row><entry
453 align="char">
454<para>size_t count</para>
455</entry><entry
456 align="char">
457<para>Size of buf.</para>
458</entry>
459 </row></tbody></tgroup></informaltable>
460<para>ERRORS
461</para>
462<informaltable><tgroup cols="2"><tbody><row><entry
463 align="char">
464<para>EWOULDBLOCK</para>
465</entry><entry
466 align="char">
467<para>No data was written. This
468 might happen if O_NONBLOCK was specified and there
469 is no more buffer space available (if O_NONBLOCK is
470 not specified the function will block until buffer space is
471 available).</para>
472</entry>
473 </row><row><entry
474 align="char">
475<para>EBUSY</para>
476</entry><entry
477 align="char">
478<para>This error code indicates that there are conflicting
479 requests. The corresponding demux device is setup to
480 receive data from the front- end. Make sure that these
481 filters are stopped and that the filters with input set to
482 DMX_IN_DVR are started.</para>
483</entry>
484 </row><row><entry
485 align="char">
486<para>EBADF</para>
487</entry><entry
488 align="char">
489<para>fd is not a valid open file descriptor.</para>
490</entry>
491 </row></tbody></tgroup></informaltable>
492</section>
493
494<section id="dmx_start">
495<title>DMX_START</title>
496<para>DESCRIPTION
497</para>
498<informaltable><tgroup cols="1"><tbody><row><entry
499 align="char">
500<para>This ioctl call is used to start the actual filtering operation defined via the ioctl
501 calls DMX_SET_FILTER or DMX_SET_PES_FILTER.</para>
502</entry>
503 </row></tbody></tgroup></informaltable>
504<para>SYNOPSIS
505</para>
506<informaltable><tgroup cols="1"><tbody><row><entry
507 align="char">
508<para>int ioctl( int fd, int request = DMX_START);</para>
509</entry>
510 </row></tbody></tgroup></informaltable>
511<para>PARAMETERS
512</para>
513<informaltable><tgroup cols="2"><tbody><row><entry
514 align="char">
515<para>int fd</para>
516</entry><entry
517 align="char">
518<para>File descriptor returned by a previous call to open().</para>
519</entry>
520 </row><row><entry
521 align="char">
522<para>int request</para>
523</entry><entry
524 align="char">
525<para>Equals DMX_START for this command.</para>
526</entry>
527 </row></tbody></tgroup></informaltable>
528<para>ERRORS
529</para>
530<informaltable><tgroup cols="2"><tbody><row><entry
531 align="char">
532<para>EBADF</para>
533</entry><entry
534 align="char">
535<para>fd is not a valid file descriptor.</para>
536</entry>
537 </row><row><entry
538 align="char">
539<para>EINVAL</para>
540</entry><entry
541 align="char">
542<para>Invalid argument, i.e. no filtering parameters provided via
543 the DMX_SET_FILTER or DMX_SET_PES_FILTER
544 functions.</para>
545</entry>
546 </row><row><entry
547 align="char">
548<para>EBUSY</para>
549</entry><entry
550 align="char">
551<para>This error code indicates that there are conflicting
552 requests. There are active filters filtering data from
553 another input source. Make sure that these filters are
554 stopped before starting this filter.</para>
555</entry>
556 </row></tbody></tgroup></informaltable>
557</section>
558
559<section id="dmx_stop">
560<title>DMX_STOP</title>
561<para>DESCRIPTION
562</para>
563<informaltable><tgroup cols="1"><tbody><row><entry
564 align="char">
565<para>This ioctl call is used to stop the actual filtering operation defined via the
566 ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and started via
567 the DMX_START command.</para>
568</entry>
569 </row></tbody></tgroup></informaltable>
570<para>SYNOPSIS
571</para>
572<informaltable><tgroup cols="1"><tbody><row><entry
573 align="char">
574<para>int ioctl( int fd, int request = DMX_STOP);</para>
575</entry>
576 </row></tbody></tgroup></informaltable>
577<para>PARAMETERS
578</para>
579<informaltable><tgroup cols="2"><tbody><row><entry
580 align="char">
581<para>int fd</para>
582</entry><entry
583 align="char">
584<para>File descriptor returned by a previous call to open().</para>
585</entry>
586 </row><row><entry
587 align="char">
588<para>int request</para>
589</entry><entry
590 align="char">
591<para>Equals DMX_STOP for this command.</para>
592</entry>
593 </row></tbody></tgroup></informaltable>
594<para>ERRORS
595</para>
596<informaltable><tgroup cols="2"><tbody><row><entry
597 align="char">
598<para>EBADF</para>
599</entry><entry
600 align="char">
601<para>fd is not a valid file descriptor.</para>
602</entry>
603 </row></tbody></tgroup></informaltable>
604</section>
605
606<section id="dmx_set_filter">
607<title>DMX_SET_FILTER</title>
608<para>DESCRIPTION
609</para>
610<informaltable><tgroup cols="1"><tbody><row><entry
611 align="char">
612<para>This ioctl call sets up a filter according to the filter and mask parameters
613 provided. A timeout may be defined stating number of seconds to wait for a
614 section to be loaded. A value of 0 means that no timeout should be applied.
615 Finally there is a flag field where it is possible to state whether a section should
616 be CRC-checked, whether the filter should be a &#8221;one-shot&#8221; filter, i.e. if the
617 filtering operation should be stopped after the first section is received, and
618 whether the filtering operation should be started immediately (without waiting
619 for a DMX_START ioctl call). If a filter was previously set-up, this filter will
620 be canceled, and the receive buffer will be flushed.</para>
621</entry>
622 </row></tbody></tgroup></informaltable>
623<para>SYNOPSIS
624</para>
625<informaltable><tgroup cols="1"><tbody><row><entry
626 align="char">
627<para>int ioctl( int fd, int request = DMX_SET_FILTER,
628 struct dmx_sct_filter_params &#x22C6;params);</para>
629</entry>
630 </row></tbody></tgroup></informaltable>
631<para>PARAMETERS
632</para>
633<informaltable><tgroup cols="2"><tbody><row><entry
634 align="char">
635<para>int fd</para>
636</entry><entry
637 align="char">
638<para>File descriptor returned by a previous call to open().</para>
639</entry>
640 </row><row><entry
641 align="char">
642<para>int request</para>
643</entry><entry
644 align="char">
645<para>Equals DMX_SET_FILTER for this command.</para>
646</entry>
647 </row><row><entry
648 align="char">
649<para>struct
650 dmx_sct_filter_params
651 *params</para>
652</entry><entry
653 align="char">
654<para>Pointer to structure containing filter parameters.</para>
655</entry>
656 </row></tbody></tgroup></informaltable>
657<para>ERRORS
658</para>
659<informaltable><tgroup cols="2"><tbody><row><entry
660 align="char">
661<para>EBADF</para>
662</entry><entry
663 align="char">
664<para>fd is not a valid file descriptor.</para>
665</entry>
666 </row><row><entry
667 align="char">
668<para>EINVAL</para>
669</entry><entry
670 align="char">
671<para>Invalid argument.</para>
672</entry>
673 </row></tbody></tgroup></informaltable>
674</section>
675
676<section id="dmx_set_pes_filter">
677<title>DMX_SET_PES_FILTER</title>
678<para>DESCRIPTION
679</para>
680<informaltable><tgroup cols="1"><tbody><row><entry
681 align="char">
682<para>This ioctl call sets up a PES filter according to the parameters provided. By a
683 PES filter is meant a filter that is based just on the packet identifier (PID), i.e.
684 no PES header or payload filtering capability is supported.</para>
685</entry>
686 </row><row><entry
687 align="char">
688<para>The transport stream destination for the filtered output may be set. Also the
689 PES type may be stated in order to be able to e.g. direct a video stream directly
690 to the video decoder. Finally there is a flag field where it is possible to state
691 whether the filtering operation should be started immediately (without waiting
692 for a DMX_START ioctl call). If a filter was previously set-up, this filter will
693 be cancelled, and the receive buffer will be flushed.</para>
694</entry>
695 </row></tbody></tgroup></informaltable>
696<para>SYNOPSIS
697</para>
698<informaltable><tgroup cols="1"><tbody><row><entry
699 align="char">
700<para>int ioctl( int fd, int request = DMX_SET_PES_FILTER,
701 struct dmx_pes_filter_params &#x22C6;params);</para>
702</entry>
703 </row></tbody></tgroup></informaltable>
704<para>PARAMETERS
705</para>
706<informaltable><tgroup cols="2"><tbody><row><entry
707 align="char">
708<para>int fd</para>
709</entry><entry
710 align="char">
711<para>File descriptor returned by a previous call to open().</para>
712</entry>
713 </row><row><entry
714 align="char">
715<para>int request</para>
716</entry><entry
717 align="char">
718<para>Equals DMX_SET_PES_FILTER for this command.</para>
719</entry>
720 </row><row><entry
721 align="char">
722<para>struct
723 dmx_pes_filter_params
724 *params</para>
725</entry><entry
726 align="char">
727<para>Pointer to structure containing filter parameters.</para>
728</entry>
729 </row></tbody></tgroup></informaltable>
730<para>ERRORS
731</para>
732<informaltable><tgroup cols="2"><tbody><row><entry
733 align="char">
734<para>EBADF</para>
735</entry><entry
736 align="char">
737<para>fd is not a valid file descriptor.</para>
738</entry>
739 </row><row><entry
740 align="char">
741<para>EINVAL</para>
742</entry><entry
743 align="char">
744<para>Invalid argument.</para>
745</entry>
746 </row><row><entry
747 align="char">
748<para>EBUSY</para>
749</entry><entry
750 align="char">
751<para>This error code indicates that there are conflicting
752 requests. There are active filters filtering data from
753 another input source. Make sure that these filters are
754 stopped before starting this filter.</para>
755</entry>
756 </row></tbody></tgroup></informaltable>
757</section>
758
759<section id="dms_set_buffer_size">
760<title>DMX_SET_BUFFER_SIZE</title>
761<para>DESCRIPTION
762</para>
763<informaltable><tgroup cols="1"><tbody><row><entry
764 align="char">
765<para>This ioctl call is used to set the size of the circular buffer used for filtered data.
766 The default size is two maximum sized sections, i.e. if this function is not called
767 a buffer size of 2 * 4096 bytes will be used.</para>
768</entry>
769 </row></tbody></tgroup></informaltable>
770<para>SYNOPSIS
771</para>
772<informaltable><tgroup cols="1"><tbody><row><entry
773 align="char">
774<para>int ioctl( int fd, int request =
775 DMX_SET_BUFFER_SIZE, unsigned long size);</para>
776</entry>
777 </row></tbody></tgroup></informaltable>
778<para>PARAMETERS
779</para>
780<informaltable><tgroup cols="2"><tbody><row><entry
781 align="char">
782<para>int fd</para>
783</entry><entry
784 align="char">
785<para>File descriptor returned by a previous call to open().</para>
786</entry>
787 </row><row><entry
788 align="char">
789<para>int request</para>
790</entry><entry
791 align="char">
792<para>Equals DMX_SET_BUFFER_SIZE for this command.</para>
793</entry>
794 </row><row><entry
795 align="char">
796<para>unsigned long size</para>
797</entry><entry
798 align="char">
799<para>Size of circular buffer.</para>
800</entry>
801 </row></tbody></tgroup></informaltable>
802<para>ERRORS
803</para>
804<informaltable><tgroup cols="2"><tbody><row><entry
805 align="char">
806<para>EBADF</para>
807</entry><entry
808 align="char">
809<para>fd is not a valid file descriptor.</para>
810</entry>
811 </row><row><entry
812 align="char">
813<para>ENOMEM</para>
814</entry><entry
815 align="char">
816<para>The driver was not able to allocate a buffer of the
817 requested size.</para>
818</entry>
819 </row></tbody></tgroup></informaltable>
820</section>
821
822<section id="dmx_get_event">
823<title>DMX_GET_EVENT</title>
824<para>DESCRIPTION
825</para>
826<informaltable><tgroup cols="1"><tbody><row><entry
827 align="char">
828<para>This ioctl call returns an event if available. If an event is not available,
829 the behavior depends on whether the device is in blocking or non-blocking
830 mode. In the latter case, the call fails immediately with errno set to
831 EWOULDBLOCK. In the former case, the call blocks until an event becomes
832 available.</para>
833</entry>
834 </row><row><entry
835 align="char">
836<para>The standard Linux poll() and/or select() system calls can be used with the
837 device file descriptor to watch for new events. For select(), the file descriptor
838 should be included in the exceptfds argument, and for poll(), POLLPRI should
839 be specified as the wake-up condition. Only the latest event for each filter is
840 saved.</para>
841</entry>
842 </row></tbody></tgroup></informaltable>
843<para>SYNOPSIS
844</para>
845<informaltable><tgroup cols="1"><tbody><row><entry
846 align="char">
847<para>int ioctl( int fd, int request = DMX_GET_EVENT,
848 struct dmx_event &#x22C6;ev);</para>
849</entry>
850 </row></tbody></tgroup></informaltable>
851<para>PARAMETERS
852</para>
853<informaltable><tgroup cols="2"><tbody><row><entry
854 align="char">
855<para>int fd</para>
856</entry><entry
857 align="char">
858<para>File descriptor returned by a previous call to open().</para>
859</entry>
860 </row><row><entry
861 align="char">
862<para>int request</para>
863</entry><entry
864 align="char">
865<para>Equals DMX_GET_EVENT for this command.</para>
866</entry>
867 </row><row><entry
868 align="char">
869<para>struct dmx_event *ev</para>
870</entry><entry
871 align="char">
872<para>Pointer to the location where the event is to be stored.</para>
873</entry>
874 </row></tbody></tgroup></informaltable>
875<para>ERRORS
876</para>
877<informaltable><tgroup cols="2"><tbody><row><entry
878 align="char">
879<para>EBADF</para>
880</entry><entry
881 align="char">
882<para>fd is not a valid file descriptor.</para>
883</entry>
884 </row><row><entry
885 align="char">
886<para>EFAULT</para>
887</entry><entry
888 align="char">
889<para>ev points to an invalid address.</para>
890</entry>
891 </row><row><entry
892 align="char">
893<para>EWOULDBLOCK</para>
894</entry><entry
895 align="char">
896<para>There is no event pending, and the device is in
897 non-blocking mode.</para>
898</entry>
899 </row></tbody></tgroup></informaltable>
900</section>
901
902<section id="dmx_get_stc">
903<title>DMX_GET_STC</title>
904<para>DESCRIPTION
905</para>
906<informaltable><tgroup cols="1"><tbody><row><entry
907 align="char">
908<para>This ioctl call returns the current value of the system time counter (which is driven
909 by a PES filter of type DMX_PES_PCR). Some hardware supports more than one
910 STC, so you must specify which one by setting the num field of stc before the ioctl
911 (range 0...n). The result is returned in form of a ratio with a 64 bit numerator
912 and a 32 bit denominator, so the real 90kHz STC value is stc-&#x003E;stc /
913 stc-&#x003E;base
914 .</para>
915</entry>
916 </row></tbody></tgroup></informaltable>
917<para>SYNOPSIS
918</para>
919<informaltable><tgroup cols="1"><tbody><row><entry
920 align="char">
921<para>int ioctl( int fd, int request = DMX_GET_STC, struct
922 dmx_stc &#x22C6;stc);</para>
923</entry>
924 </row></tbody></tgroup></informaltable>
925<para>PARAMETERS
926</para>
927<informaltable><tgroup cols="2"><tbody><row><entry
928 align="char">
929<para>int fd</para>
930</entry><entry
931 align="char">
932<para>File descriptor returned by a previous call to open().</para>
933</entry>
934 </row><row><entry
935 align="char">
936<para>int request</para>
937</entry><entry
938 align="char">
939<para>Equals DMX_GET_STC for this command.</para>
940</entry>
941 </row><row><entry
942 align="char">
943<para>struct dmx_stc *stc</para>
944</entry><entry
945 align="char">
946<para>Pointer to the location where the stc is to be stored.</para>
947</entry>
948 </row></tbody></tgroup></informaltable>
949<para>ERRORS
950</para>
951<informaltable><tgroup cols="2"><tbody><row><entry
952 align="char">
953<para>EBADF</para>
954</entry><entry
955 align="char">
956<para>fd is not a valid file descriptor.</para>
957</entry>
958 </row><row><entry
959 align="char">
960<para>EFAULT</para>
961</entry><entry
962 align="char">
963<para>stc points to an invalid address.</para>
964</entry>
965 </row><row><entry
966 align="char">
967<para>EINVAL</para>
968</entry><entry
969 align="char">
970<para>Invalid stc number.</para>
971</entry>
972 </row></tbody></tgroup></informaltable>
973 </section></section>
diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml
new file mode 100644
index 000000000000..9fad86ce7f5e
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbapi.xml
@@ -0,0 +1,121 @@
1<partinfo>
2<authorgroup>
3<author>
4<firstname>Ralph</firstname>
5<surname>Metzler</surname>
6<othername role="mi">J. K.</othername>
7<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
8</author>
9<author>
10<firstname>Marcus</firstname>
11<surname>Metzler</surname>
12<othername role="mi">O. C.</othername>
13<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
14</author>
15</authorgroup>
16<authorgroup>
17<author>
18<firstname>Mauro</firstname>
19<othername role="mi">Carvalho</othername>
20<surname>Chehab</surname>
21<affiliation><address><email>mchehab@redhat.com</email></address></affiliation>
22<contrib>Ported document to Docbook XML.</contrib>
23</author>
24</authorgroup>
25<copyright>
26 <year>2002</year>
27 <year>2003</year>
28 <holder>Convergence GmbH</holder>
29</copyright>
30<copyright>
31 <year>2009-2011</year>
32 <holder>Mauro Carvalho Chehab</holder>
33</copyright>
34
35<revhistory>
36<!-- Put document revisions here, newest first. -->
37<revision>
38 <revnumber>2.0.4</revnumber>
39 <date>2011-05-06</date>
40 <authorinitials>mcc</authorinitials>
41 <revremark>
42 Add more information about DVB APIv5, better describing the frontend GET/SET props ioctl's.
43 </revremark>
44</revision>
45<revision>
46 <revnumber>2.0.3</revnumber>
47 <date>2010-07-03</date>
48 <authorinitials>mcc</authorinitials>
49 <revremark>
50 Add some frontend capabilities flags, present on kernel, but missing at the specs.
51 </revremark>
52</revision>
53<revision>
54 <revnumber>2.0.2</revnumber>
55 <date>2009-10-25</date>
56 <authorinitials>mcc</authorinitials>
57 <revremark>
58 documents FE_SET_FRONTEND_TUNE_MODE and FE_DISHETWORK_SEND_LEGACY_CMD ioctls.
59 </revremark>
60</revision>
61<revision>
62<revnumber>2.0.1</revnumber>
63<date>2009-09-16</date>
64<authorinitials>mcc</authorinitials>
65<revremark>
66Added ISDB-T test originally written by Patrick Boettcher
67</revremark>
68</revision>
69<revision>
70<revnumber>2.0.0</revnumber>
71<date>2009-09-06</date>
72<authorinitials>mcc</authorinitials>
73<revremark>Conversion from LaTex to DocBook XML. The
74 contents is the same as the original LaTex version.</revremark>
75</revision>
76<revision>
77<revnumber>1.0.0</revnumber>
78<date>2003-07-24</date>
79<authorinitials>rjkm</authorinitials>
80<revremark>Initial revision on LaTEX.</revremark>
81</revision>
82</revhistory>
83</partinfo>
84
85
86<title>LINUX DVB API</title>
87<subtitle>Version 5.2</subtitle>
88<!-- ADD THE CHAPTERS HERE -->
89 <chapter id="dvb_introdution">
90 &sub-intro;
91 </chapter>
92 <chapter id="dvb_frontend">
93 &sub-frontend;
94 </chapter>
95 <chapter id="dvb_demux">
96 &sub-demux;
97 </chapter>
98 <chapter id="dvb_video">
99 &sub-video;
100 </chapter>
101 <chapter id="dvb_audio">
102 &sub-audio;
103 </chapter>
104 <chapter id="dvb_ca">
105 &sub-ca;
106 </chapter>
107 <chapter id="dvb_net">
108 &sub-net;
109 </chapter>
110 <chapter id="dvb_kdapi">
111 &sub-kdapi;
112 </chapter>
113 <chapter id="dvb_examples">
114 &sub-examples;
115 </chapter>
116<!-- END OF CHAPTERS -->
117 <appendix id="frontend_h">
118 <title>DVB Frontend Header File</title>
119 &sub-frontend-h;
120 </appendix>
121
diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml
new file mode 100644
index 000000000000..b5365f61d69b
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbproperty.xml
@@ -0,0 +1,590 @@
1<section id="FE_GET_SET_PROPERTY">
2<title>FE_GET_PROPERTY/FE_SET_PROPERTY</title>
3
4<programlisting>
5/* Reserved fields should be set to 0 */
6struct dtv_property {
7 __u32 cmd;
8 union {
9 __u32 data;
10 struct {
11 __u8 data[32];
12 __u32 len;
13 __u32 reserved1[3];
14 void *reserved2;
15 } buffer;
16 } u;
17 int result;
18} __attribute__ ((packed));
19
20/* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */
21#define DTV_IOCTL_MAX_MSGS 64
22
23struct dtv_properties {
24 __u32 num;
25 struct dtv_property *props;
26};
27</programlisting>
28
29<section id="FE_GET_PROPERTY">
30<title>FE_GET_PROPERTY</title>
31<para>DESCRIPTION
32</para>
33<informaltable><tgroup cols="1"><tbody><row><entry
34 align="char">
35<para>This ioctl call returns one or more frontend properties. This call only
36 requires read-only access to the device.</para>
37</entry>
38 </row></tbody></tgroup></informaltable>
39<para>SYNOPSIS
40</para>
41<informaltable><tgroup cols="1"><tbody><row><entry
42 align="char">
43<para>int ioctl(int fd, int request = <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>,
44 dtv_properties &#x22C6;props);</para>
45</entry>
46 </row></tbody></tgroup></informaltable>
47<para>PARAMETERS
48</para>
49<informaltable><tgroup cols="2"><tbody><row><entry align="char">
50<para>int fd</para>
51</entry><entry
52 align="char">
53<para>File descriptor returned by a previous call to open().</para>
54</entry>
55 </row><row><entry
56 align="char">
57<para>int num</para>
58</entry><entry
59 align="char">
60<para>Equals <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link> for this command.</para>
61</entry>
62 </row><row><entry
63 align="char">
64<para>struct dtv_property *props</para>
65</entry><entry
66 align="char">
67<para>Points to the location where the front-end property commands are stored.</para>
68</entry>
69 </row></tbody></tgroup></informaltable>
70<para>ERRORS</para>
71<informaltable><tgroup cols="2"><tbody><row>
72 <entry align="char"><para>EINVAL</para></entry>
73 <entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry>
74 </row><row>
75 <entry align="char"><para>ENOMEM</para></entry>
76 <entry align="char"><para>Out of memory.</para></entry>
77 </row><row>
78 <entry align="char"><para>EFAULT</para></entry>
79 <entry align="char"><para>Failure while copying data from/to userspace.</para></entry>
80 </row><row>
81 <entry align="char"><para>EOPNOTSUPP</para></entry>
82 <entry align="char"><para>Property type not supported.</para></entry>
83 </row></tbody></tgroup></informaltable>
84</section>
85
86<section id="FE_SET_PROPERTY">
87<title>FE_SET_PROPERTY</title>
88<para>DESCRIPTION
89</para>
90<informaltable><tgroup cols="1"><tbody><row><entry
91 align="char">
92<para>This ioctl call sets one or more frontend properties. This call only
93 requires read-only access to the device.</para>
94</entry>
95 </row></tbody></tgroup></informaltable>
96<para>SYNOPSIS
97</para>
98<informaltable><tgroup cols="1"><tbody><row><entry
99 align="char">
100<para>int ioctl(int fd, int request = <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
101 dtv_properties &#x22C6;props);</para>
102</entry>
103 </row></tbody></tgroup></informaltable>
104<para>PARAMETERS
105</para>
106<informaltable><tgroup cols="2"><tbody><row><entry align="char">
107<para>int fd</para>
108</entry><entry
109 align="char">
110<para>File descriptor returned by a previous call to open().</para>
111</entry>
112 </row><row><entry
113 align="char">
114<para>int num</para>
115</entry><entry
116 align="char">
117<para>Equals <link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link> for this command.</para>
118</entry>
119 </row><row><entry
120 align="char">
121<para>struct dtv_property *props</para>
122</entry><entry
123 align="char">
124<para>Points to the location where the front-end property commands are stored.</para>
125</entry>
126 </row></tbody></tgroup></informaltable>
127<para>ERRORS
128</para>
129<informaltable><tgroup cols="2"><tbody><row>
130 <entry align="char"><para>EINVAL</para></entry>
131 <entry align="char"><para>Invalid parameter(s) received or number of parameters out of the range.</para></entry>
132 </row><row>
133 <entry align="char"><para>ENOMEM</para></entry>
134 <entry align="char"><para>Out of memory.</para></entry>
135 </row><row>
136 <entry align="char"><para>EFAULT</para></entry>
137 <entry align="char"><para>Failure while copying data from/to userspace.</para></entry>
138 </row><row>
139 <entry align="char"><para>EOPNOTSUPP</para></entry>
140 <entry align="char"><para>Property type not supported.</para></entry>
141 </row></tbody></tgroup></informaltable>
142</section>
143
144<section>
145 <title>Property types</title>
146<para>
147On <link linkend="FE_GET_PROPERTY">FE_GET_PROPERTY</link>/<link linkend="FE_SET_PROPERTY">FE_SET_PROPERTY</link>,
148the actual action is determined by the dtv_property cmd/data pairs. With one single ioctl, is possible to
149get/set up to 64 properties. The actual meaning of each property is described on the next sections.
150</para>
151
152<para>The available frontend property types are:</para>
153<programlisting>
154#define DTV_UNDEFINED 0
155#define DTV_TUNE 1
156#define DTV_CLEAR 2
157#define DTV_FREQUENCY 3
158#define DTV_MODULATION 4
159#define DTV_BANDWIDTH_HZ 5
160#define DTV_INVERSION 6
161#define DTV_DISEQC_MASTER 7
162#define DTV_SYMBOL_RATE 8
163#define DTV_INNER_FEC 9
164#define DTV_VOLTAGE 10
165#define DTV_TONE 11
166#define DTV_PILOT 12
167#define DTV_ROLLOFF 13
168#define DTV_DISEQC_SLAVE_REPLY 14
169#define DTV_FE_CAPABILITY_COUNT 15
170#define DTV_FE_CAPABILITY 16
171#define DTV_DELIVERY_SYSTEM 17
172#define DTV_ISDBT_PARTIAL_RECEPTION 18
173#define DTV_ISDBT_SOUND_BROADCASTING 19
174#define DTV_ISDBT_SB_SUBCHANNEL_ID 20
175#define DTV_ISDBT_SB_SEGMENT_IDX 21
176#define DTV_ISDBT_SB_SEGMENT_COUNT 22
177#define DTV_ISDBT_LAYERA_FEC 23
178#define DTV_ISDBT_LAYERA_MODULATION 24
179#define DTV_ISDBT_LAYERA_SEGMENT_COUNT 25
180#define DTV_ISDBT_LAYERA_TIME_INTERLEAVING 26
181#define DTV_ISDBT_LAYERB_FEC 27
182#define DTV_ISDBT_LAYERB_MODULATION 28
183#define DTV_ISDBT_LAYERB_SEGMENT_COUNT 29
184#define DTV_ISDBT_LAYERB_TIME_INTERLEAVING 30
185#define DTV_ISDBT_LAYERC_FEC 31
186#define DTV_ISDBT_LAYERC_MODULATION 32
187#define DTV_ISDBT_LAYERC_SEGMENT_COUNT 33
188#define DTV_ISDBT_LAYERC_TIME_INTERLEAVING 34
189#define DTV_API_VERSION 35
190#define DTV_CODE_RATE_HP 36
191#define DTV_CODE_RATE_LP 37
192#define DTV_GUARD_INTERVAL 38
193#define DTV_TRANSMISSION_MODE 39
194#define DTV_HIERARCHY 40
195#define DTV_ISDBT_LAYER_ENABLED 41
196#define DTV_ISDBS_TS_ID 42
197</programlisting>
198</section>
199
200<section id="fe_property_common">
201 <title>Parameters that are common to all Digital TV standards</title>
202 <section id="DTV_FREQUENCY">
203 <title><constant>DTV_FREQUENCY</constant></title>
204
205 <para>Central frequency of the channel, in HZ.</para>
206
207 <para>Notes:</para>
208 <para>1)For ISDB-T, the channels are usually transmitted with an offset of 143kHz.
209 E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of
210 the channel which is 6MHz.</para>
211
212 <para>2)As in ISDB-Tsb the channel consists of only one or three segments the
213 frequency step is 429kHz, 3*429 respectively. As for ISDB-T the
214 central frequency of the channel is expected.</para>
215 </section>
216
217 <section id="DTV_BANDWIDTH_HZ">
218 <title><constant>DTV_BANDWIDTH_HZ</constant></title>
219
220 <para>Bandwidth for the channel, in HZ.</para>
221
222 <para>Possible values:
223 <constant>1712000</constant>,
224 <constant>5000000</constant>,
225 <constant>6000000</constant>,
226 <constant>7000000</constant>,
227 <constant>8000000</constant>,
228 <constant>10000000</constant>.
229 </para>
230
231 <para>Notes:</para>
232
233 <para>1) For ISDB-T it should be always 6000000Hz (6MHz)</para>
234 <para>2) For ISDB-Tsb it can vary depending on the number of connected segments</para>
235 <para>3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth
236 for DVB-C depends on the symbol rate</para>
237 <para>4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from
238 other parameters (DTV_ISDBT_SB_SEGMENT_IDX,
239 DTV_ISDBT_SB_SEGMENT_COUNT).</para>
240 <para>5) DVB-T supports 6, 7 and 8MHz.</para>
241 <para>6) In addition, DVB-T2 supports 1.172, 5 and 10MHz.</para>
242 </section>
243
244 <section id="DTV_DELIVERY_SYSTEM">
245 <title><constant>DTV_DELIVERY_SYSTEM</constant></title>
246
247 <para>Specifies the type of Delivery system</para>
248
249 <para>Possible values: </para>
250<programlisting>
251typedef enum fe_delivery_system {
252 SYS_UNDEFINED,
253 SYS_DVBC_ANNEX_AC,
254 SYS_DVBC_ANNEX_B,
255 SYS_DVBT,
256 SYS_DSS,
257 SYS_DVBS,
258 SYS_DVBS2,
259 SYS_DVBH,
260 SYS_ISDBT,
261 SYS_ISDBS,
262 SYS_ISDBC,
263 SYS_ATSC,
264 SYS_ATSCMH,
265 SYS_DMBTH,
266 SYS_CMMB,
267 SYS_DAB,
268 SYS_DVBT2,
269} fe_delivery_system_t;
270</programlisting>
271
272 </section>
273
274 <section id="DTV_TRANSMISSION_MODE">
275 <title><constant>DTV_TRANSMISSION_MODE</constant></title>
276
277 <para>Specifies the number of carriers used by the standard</para>
278
279 <para>Possible values are:</para>
280<programlisting>
281typedef enum fe_transmit_mode {
282 TRANSMISSION_MODE_2K,
283 TRANSMISSION_MODE_8K,
284 TRANSMISSION_MODE_AUTO,
285 TRANSMISSION_MODE_4K,
286 TRANSMISSION_MODE_1K,
287 TRANSMISSION_MODE_16K,
288 TRANSMISSION_MODE_32K,
289} fe_transmit_mode_t;
290</programlisting>
291
292 <para>Notes:</para>
293 <para>1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called
294 'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K</para>
295
296 <para>2) If <constant>DTV_TRANSMISSION_MODE</constant> is set the <constant>TRANSMISSION_MODE_AUTO</constant> the
297 hardware will try to find the correct FFT-size (if capable) and will
298 use TMCC to fill in the missing parameters.</para>
299 <para>3) DVB-T specifies 2K and 8K as valid sizes.</para>
300 <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para>
301 </section>
302
303 <section id="DTV_GUARD_INTERVAL">
304 <title><constant>DTV_GUARD_INTERVAL</constant></title>
305
306 <para>Possible values are:</para>
307<programlisting>
308typedef enum fe_guard_interval {
309 GUARD_INTERVAL_1_32,
310 GUARD_INTERVAL_1_16,
311 GUARD_INTERVAL_1_8,
312 GUARD_INTERVAL_1_4,
313 GUARD_INTERVAL_AUTO,
314 GUARD_INTERVAL_1_128,
315 GUARD_INTERVAL_19_128,
316 GUARD_INTERVAL_19_256,
317} fe_guard_interval_t;
318</programlisting>
319
320 <para>Notes:</para>
321 <para>1) If <constant>DTV_GUARD_INTERVAL</constant> is set the <constant>GUARD_INTERVAL_AUTO</constant> the hardware will
322 try to find the correct guard interval (if capable) and will use TMCC to fill
323 in the missing parameters.</para>
324 <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para>
325 </section>
326</section>
327
328<section id="isdbt">
329 <title>ISDB-T frontend</title>
330 <para>This section describes shortly what are the possible parameters in the Linux
331 DVB-API called "S2API" and now DVB API 5 in order to tune an ISDB-T/ISDB-Tsb
332 demodulator:</para>
333
334 <para>This ISDB-T/ISDB-Tsb API extension should reflect all information
335 needed to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible
336 that some very sophisticated devices won't need certain parameters to
337 tune.</para>
338
339 <para>The information given here should help application writers to know how
340 to handle ISDB-T and ISDB-Tsb hardware using the Linux DVB-API.</para>
341
342 <para>The details given here about ISDB-T and ISDB-Tsb are just enough to
343 basically show the dependencies between the needed parameter values,
344 but surely some information is left out. For more detailed information
345 see the following documents:</para>
346
347 <para>ARIB STD-B31 - "Transmission System for Digital Terrestrial
348 Television Broadcasting" and</para>
349 <para>ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial
350 Television Broadcasting".</para>
351
352 <para>In order to read this document one has to have some knowledge the
353 channel structure in ISDB-T and ISDB-Tsb. I.e. it has to be known to
354 the reader that an ISDB-T channel consists of 13 segments, that it can
355 have up to 3 layer sharing those segments, and things like that.</para>
356
357 <para>Parameters used by ISDB-T and ISDB-Tsb.</para>
358
359 <section id="isdbt-new-parms">
360 <title>ISDB-T only parameters</title>
361
362 <section id="isdbt-part-rec">
363 <title><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></title>
364
365 <para><constant>If DTV_ISDBT_SOUND_BROADCASTING</constant> is '0' this bit-field represents whether
366 the channel is in partial reception mode or not.</para>
367
368 <para>If '1' <constant>DTV_ISDBT_LAYERA_*</constant> values are assigned to the center segment and
369 <constant>DTV_ISDBT_LAYERA_SEGMENT_COUNT</constant> has to be '1'.</para>
370
371 <para>If in addition <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'
372 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> represents whether this ISDB-Tsb channel
373 is consisting of one segment and layer or three segments and two layers.</para>
374
375 <para>Possible values: 0, 1, -1 (AUTO)</para>
376 </section>
377
378 <section id="isdbt-sound-bcast">
379 <title><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></title>
380
381 <para>This field represents whether the other DTV_ISDBT_*-parameters are
382 referring to an ISDB-T and an ISDB-Tsb channel. (See also
383 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>).</para>
384
385 <para>Possible values: 0, 1, -1 (AUTO)</para>
386 </section>
387
388 <section id="isdbt-sb-ch-id">
389 <title><constant>DTV_ISDBT_SB_SUBCHANNEL_ID</constant></title>
390
391 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
392
393 <para>(Note of the author: This might not be the correct description of the
394 <constant>SUBCHANNEL-ID</constant> in all details, but it is my understanding of the technical
395 background needed to program a device)</para>
396
397 <para>An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a
398 set of connected ISDB-Tsb channels. In this set of channels every
399 channel can be received independently. The number of connected
400 ISDB-Tsb segment can vary, e.g. depending on the frequency spectrum
401 bandwidth available.</para>
402
403 <para>Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The
404 broadcaster has several possibilities to put those channels in the
405 air: Assuming a normal 13-segment ISDB-T spectrum he can align the 8
406 segments from position 1-8 to 5-13 or anything in between.</para>
407
408 <para>The underlying layer of segments are subchannels: each segment is
409 consisting of several subchannels with a predefined IDs. A sub-channel
410 is used to help the demodulator to synchronize on the channel.</para>
411
412 <para>An ISDB-T channel is always centered over all sub-channels. As for
413 the example above, in ISDB-Tsb it is no longer as simple as that.</para>
414
415 <para><constant>The DTV_ISDBT_SB_SUBCHANNEL_ID</constant> parameter is used to give the
416 sub-channel ID of the segment to be demodulated.</para>
417
418 <para>Possible values: 0 .. 41, -1 (AUTO)</para>
419 </section>
420
421 <section id="isdbt-sb-seg-idx">
422
423 <title><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant></title>
424
425 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
426
427 <para><constant>DTV_ISDBT_SB_SEGMENT_IDX</constant> gives the index of the segment to be
428 demodulated for an ISDB-Tsb channel where several of them are
429 transmitted in the connected manner.</para>
430
431 <para>Possible values: 0 .. <constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> - 1</para>
432
433 <para>Note: This value cannot be determined by an automatic channel search.</para>
434 </section>
435
436 <section id="isdbt-sb-seg-cnt">
437 <title><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant></title>
438
439 <para>This field only applies if <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> is '1'.</para>
440
441 <para><constant>DTV_ISDBT_SB_SEGMENT_COUNT</constant> gives the total count of connected ISDB-Tsb
442 channels.</para>
443
444 <para>Possible values: 1 .. 13</para>
445
446 <para>Note: This value cannot be determined by an automatic channel search.</para>
447 </section>
448
449 <section id="isdb-hierq-layers">
450 <title>Hierarchical layers</title>
451
452 <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in
453 ISDB-T hierarchical layers can be decoded simultaneously. For that
454 reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para>
455
456 <para>ISDB-T has 3 hierarchical layers which each can use a part of the
457 available segments. The total number of segments over all layers has
458 to 13 in ISDB-T.</para>
459
460 <section id="isdbt-layer-ena">
461 <title><constant>DTV_ISDBT_LAYER_ENABLED</constant></title>
462
463 <para>Hierarchical reception in ISDB-T is achieved by enabling or disabling
464 layers in the decoding process. Setting all bits of
465 <constant>DTV_ISDBT_LAYER_ENABLED</constant> to '1' forces all layers (if applicable) to be
466 demodulated. This is the default.</para>
467
468 <para>If the channel is in the partial reception mode
469 (<constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> = 1) the central segment can be decoded
470 independently of the other 12 segments. In that mode layer A has to
471 have a <constant>SEGMENT_COUNT</constant> of 1.</para>
472
473 <para>In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb
474 according to <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>. <constant>SEGMENT_COUNT</constant> must be filled
475 accordingly.</para>
476
477 <para>Possible values: 0x1, 0x2, 0x4 (|-able)</para>
478
479 <para><constant>DTV_ISDBT_LAYER_ENABLED[0:0]</constant> - layer A</para>
480 <para><constant>DTV_ISDBT_LAYER_ENABLED[1:1]</constant> - layer B</para>
481 <para><constant>DTV_ISDBT_LAYER_ENABLED[2:2]</constant> - layer C</para>
482 <para><constant>DTV_ISDBT_LAYER_ENABLED[31:3]</constant> unused</para>
483 </section>
484
485 <section id="isdbt-layer-fec">
486 <title><constant>DTV_ISDBT_LAYER*_FEC</constant></title>
487
488 <para>Possible values: <constant>FEC_AUTO</constant>, <constant>FEC_1_2</constant>, <constant>FEC_2_3</constant>, <constant>FEC_3_4</constant>, <constant>FEC_5_6</constant>, <constant>FEC_7_8</constant></para>
489 </section>
490
491 <section id="isdbt-layer-mod">
492 <title><constant>DTV_ISDBT_LAYER*_MODULATION</constant></title>
493
494 <para>Possible values: <constant>QAM_AUTO</constant>, QP<constant>SK, QAM_16</constant>, <constant>QAM_64</constant>, <constant>DQPSK</constant></para>
495
496 <para>Note: If layer C is <constant>DQPSK</constant> layer B has to be <constant>DQPSK</constant>. If layer B is <constant>DQPSK</constant>
497 and <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant>=0 layer has to be <constant>DQPSK</constant>.</para>
498 </section>
499
500 <section id="isdbt-layer-seg-cnt">
501 <title><constant>DTV_ISDBT_LAYER*_SEGMENT_COUNT</constant></title>
502
503 <para>Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO)</para>
504
505 <para>Note: Truth table for <constant>DTV_ISDBT_SOUND_BROADCASTING</constant> and
506 <constant>DTV_ISDBT_PARTIAL_RECEPTION</constant> and <constant>LAYER</constant>*_SEGMENT_COUNT</para>
507
508 <informaltable id="isdbt-layer_seg-cnt-table">
509 <tgroup cols="6">
510
511 <tbody>
512 <row>
513 <entry>PR</entry>
514 <entry>SB</entry>
515 <entry>Layer A width</entry>
516 <entry>Layer B width</entry>
517 <entry>Layer C width</entry>
518 <entry>total width</entry>
519 </row>
520
521 <row>
522 <entry>0</entry>
523 <entry>0</entry>
524 <entry>1 .. 13</entry>
525 <entry>1 .. 13</entry>
526 <entry>1 .. 13</entry>
527 <entry>13</entry>
528 </row>
529
530 <row>
531 <entry>1</entry>
532 <entry>0</entry>
533 <entry>1</entry>
534 <entry>1 .. 13</entry>
535 <entry>1 .. 13</entry>
536 <entry>13</entry>
537 </row>
538
539 <row>
540 <entry>0</entry>
541 <entry>1</entry>
542 <entry>1</entry>
543 <entry>0</entry>
544 <entry>0</entry>
545 <entry>1</entry>
546 </row>
547
548 <row>
549 <entry>1</entry>
550 <entry>1</entry>
551 <entry>1</entry>
552 <entry>2</entry>
553 <entry>0</entry>
554 <entry>13</entry>
555 </row>
556 </tbody>
557
558 </tgroup>
559 </informaltable>
560
561 </section>
562
563 <section id="isdbt_layer_t_interl">
564 <title><constant>DTV_ISDBT_LAYER*_TIME_INTERLEAVING</constant></title>
565
566 <para>Possible values: 0, 1, 2, 3, -1 (AUTO)</para>
567
568 <para>Note: The real inter-leaver depth-names depend on the mode (fft-size); the values
569 here are referring to what can be found in the TMCC-structure -
570 independent of the mode.</para>
571 </section>
572 </section>
573 </section>
574 <section id="dvbt2-params">
575 <title>DVB-T2 parameters</title>
576
577 <para>This section covers parameters that apply only to the DVB-T2 delivery method. DVB-T2
578 support is currently in the early stages development so expect this section to grow
579 and become more detailed with time.</para>
580
581 <section id="dvbt2-plp-id">
582 <title><constant>DTV_DVBT2_PLP_ID</constant></title>
583
584 <para>DVB-T2 supports Physical Layer Pipes (PLP) to allow transmission of
585 many data types via a single multiplex. The API will soon support this
586 at which point this section will be expanded.</para>
587 </section>
588 </section>
589</section>
590</section>
diff --git a/Documentation/DocBook/media/dvb/dvbstb.pdf b/Documentation/DocBook/media/dvb/dvbstb.pdf
new file mode 100644
index 000000000000..0fa75d90c3eb
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbstb.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/dvb/dvbstb.png b/Documentation/DocBook/media/dvb/dvbstb.png
new file mode 100644
index 000000000000..9b8f372e7afd
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/dvbstb.png
Binary files differ
diff --git a/Documentation/DocBook/media/dvb/examples.xml b/Documentation/DocBook/media/dvb/examples.xml
new file mode 100644
index 000000000000..f037e568eb6e
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/examples.xml
@@ -0,0 +1,365 @@
1<title>Examples</title>
2<para>In this section we would like to present some examples for using the DVB API.
3</para>
4<para>Maintainer note: This section is out of date. Please refer to the sample programs packaged
5with the driver distribution from <ulink url="http://linuxtv.org/hg/dvb-apps" />.
6</para>
7
8<section id="tuning">
9<title>Tuning</title>
10<para>We will start with a generic tuning subroutine that uses the frontend and SEC, as well as
11the demux devices. The example is given for QPSK tuners, but can easily be adjusted for
12QAM.
13</para>
14<programlisting>
15 #include &#x003C;sys/ioctl.h&#x003E;
16 #include &#x003C;stdio.h&#x003E;
17 #include &#x003C;stdint.h&#x003E;
18 #include &#x003C;sys/types.h&#x003E;
19 #include &#x003C;sys/stat.h&#x003E;
20 #include &#x003C;fcntl.h&#x003E;
21 #include &#x003C;time.h&#x003E;
22 #include &#x003C;unistd.h&#x003E;
23
24 #include &#x003C;linux/dvb/dmx.h&#x003E;
25 #include &#x003C;linux/dvb/frontend.h&#x003E;
26 #include &#x003C;linux/dvb/sec.h&#x003E;
27 #include &#x003C;sys/poll.h&#x003E;
28
29 #define DMX "/dev/dvb/adapter0/demux1"
30 #define FRONT "/dev/dvb/adapter0/frontend1"
31 #define SEC "/dev/dvb/adapter0/sec1"
32
33 /&#x22C6; routine for checking if we have a signal and other status information&#x22C6;/
34 int FEReadStatus(int fd, fe_status_t &#x22C6;stat)
35 {
36 int ans;
37
38 if ( (ans = ioctl(fd,FE_READ_STATUS,stat) &#x003C; 0)){
39 perror("FE READ STATUS: ");
40 return -1;
41 }
42
43 if (&#x22C6;stat &amp; FE_HAS_POWER)
44 printf("FE HAS POWER\n");
45
46 if (&#x22C6;stat &amp; FE_HAS_SIGNAL)
47 printf("FE HAS SIGNAL\n");
48
49 if (&#x22C6;stat &amp; FE_SPECTRUM_INV)
50 printf("SPEKTRUM INV\n");
51
52 return 0;
53 }
54
55
56 /&#x22C6; tune qpsk &#x22C6;/
57 /&#x22C6; freq: frequency of transponder &#x22C6;/
58 /&#x22C6; vpid, apid, tpid: PIDs of video, audio and teletext TS packets &#x22C6;/
59 /&#x22C6; diseqc: DiSEqC address of the used LNB &#x22C6;/
60 /&#x22C6; pol: Polarisation &#x22C6;/
61 /&#x22C6; srate: Symbol Rate &#x22C6;/
62 /&#x22C6; fec. FEC &#x22C6;/
63 /&#x22C6; lnb_lof1: local frequency of lower LNB band &#x22C6;/
64 /&#x22C6; lnb_lof2: local frequency of upper LNB band &#x22C6;/
65 /&#x22C6; lnb_slof: switch frequency of LNB &#x22C6;/
66
67 int set_qpsk_channel(int freq, int vpid, int apid, int tpid,
68 int diseqc, int pol, int srate, int fec, int lnb_lof1,
69 int lnb_lof2, int lnb_slof)
70 {
71 struct secCommand scmd;
72 struct secCmdSequence scmds;
73 struct dmx_pes_filter_params pesFilterParams;
74 FrontendParameters frp;
75 struct pollfd pfd[1];
76 FrontendEvent event;
77 int demux1, demux2, demux3, front;
78
79 frequency = (uint32_t) freq;
80 symbolrate = (uint32_t) srate;
81
82 if((front = open(FRONT,O_RDWR)) &#x003C; 0){
83 perror("FRONTEND DEVICE: ");
84 return -1;
85 }
86
87 if((sec = open(SEC,O_RDWR)) &#x003C; 0){
88 perror("SEC DEVICE: ");
89 return -1;
90 }
91
92 if (demux1 &#x003C; 0){
93 if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
94 &#x003C; 0){
95 perror("DEMUX DEVICE: ");
96 return -1;
97 }
98 }
99
100 if (demux2 &#x003C; 0){
101 if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
102 &#x003C; 0){
103 perror("DEMUX DEVICE: ");
104 return -1;
105 }
106 }
107
108 if (demux3 &#x003C; 0){
109 if ((demux3=open(DMX, O_RDWR|O_NONBLOCK))
110 &#x003C; 0){
111 perror("DEMUX DEVICE: ");
112 return -1;
113 }
114 }
115
116 if (freq &#x003C; lnb_slof) {
117 frp.Frequency = (freq - lnb_lof1);
118 scmds.continuousTone = SEC_TONE_OFF;
119 } else {
120 frp.Frequency = (freq - lnb_lof2);
121 scmds.continuousTone = SEC_TONE_ON;
122 }
123 frp.Inversion = INVERSION_AUTO;
124 if (pol) scmds.voltage = SEC_VOLTAGE_18;
125 else scmds.voltage = SEC_VOLTAGE_13;
126
127 scmd.type=0;
128 scmd.u.diseqc.addr=0x10;
129 scmd.u.diseqc.cmd=0x38;
130 scmd.u.diseqc.numParams=1;
131 scmd.u.diseqc.params[0] = 0xF0 | ((diseqc &#x22C6; 4) &amp; 0x0F) |
132 (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) |
133 (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0);
134
135 scmds.miniCommand=SEC_MINI_NONE;
136 scmds.numCommands=1;
137 scmds.commands=&amp;scmd;
138 if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
139 perror("SEC SEND: ");
140 return -1;
141 }
142
143 if (ioctl(sec, SEC_SEND_SEQUENCE, &amp;scmds) &#x003C; 0){
144 perror("SEC SEND: ");
145 return -1;
146 }
147
148 frp.u.qpsk.SymbolRate = srate;
149 frp.u.qpsk.FEC_inner = fec;
150
151 if (ioctl(front, FE_SET_FRONTEND, &amp;frp) &#x003C; 0){
152 perror("QPSK TUNE: ");
153 return -1;
154 }
155
156 pfd[0].fd = front;
157 pfd[0].events = POLLIN;
158
159 if (poll(pfd,1,3000)){
160 if (pfd[0].revents &amp; POLLIN){
161 printf("Getting QPSK event\n");
162 if ( ioctl(front, FE_GET_EVENT, &amp;event)
163
164 == -EOVERFLOW){
165 perror("qpsk get event");
166 return -1;
167 }
168 printf("Received ");
169 switch(event.type){
170 case FE_UNEXPECTED_EV:
171 printf("unexpected event\n");
172 return -1;
173 case FE_FAILURE_EV:
174 printf("failure event\n");
175 return -1;
176
177 case FE_COMPLETION_EV:
178 printf("completion event\n");
179 }
180 }
181 }
182
183
184 pesFilterParams.pid = vpid;
185 pesFilterParams.input = DMX_IN_FRONTEND;
186 pesFilterParams.output = DMX_OUT_DECODER;
187 pesFilterParams.pes_type = DMX_PES_VIDEO;
188 pesFilterParams.flags = DMX_IMMEDIATE_START;
189 if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
190 perror("set_vpid");
191 return -1;
192 }
193
194 pesFilterParams.pid = apid;
195 pesFilterParams.input = DMX_IN_FRONTEND;
196 pesFilterParams.output = DMX_OUT_DECODER;
197 pesFilterParams.pes_type = DMX_PES_AUDIO;
198 pesFilterParams.flags = DMX_IMMEDIATE_START;
199 if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
200 perror("set_apid");
201 return -1;
202 }
203
204 pesFilterParams.pid = tpid;
205 pesFilterParams.input = DMX_IN_FRONTEND;
206 pesFilterParams.output = DMX_OUT_DECODER;
207 pesFilterParams.pes_type = DMX_PES_TELETEXT;
208 pesFilterParams.flags = DMX_IMMEDIATE_START;
209 if (ioctl(demux3, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
210 perror("set_tpid");
211 return -1;
212 }
213
214 return has_signal(fds);
215 }
216
217</programlisting>
218<para>The program assumes that you are using a universal LNB and a standard DiSEqC
219switch with up to 4 addresses. Of course, you could build in some more checking if
220tuning was successful and maybe try to repeat the tuning process. Depending on the
221external hardware, i.e. LNB and DiSEqC switch, and weather conditions this may be
222necessary.
223</para>
224</section>
225
226<section id="the_dvr_device">
227<title>The DVR device</title>
228<para>The following program code shows how to use the DVR device for recording.
229</para>
230<programlisting>
231 #include &#x003C;sys/ioctl.h&#x003E;
232 #include &#x003C;stdio.h&#x003E;
233 #include &#x003C;stdint.h&#x003E;
234 #include &#x003C;sys/types.h&#x003E;
235 #include &#x003C;sys/stat.h&#x003E;
236 #include &#x003C;fcntl.h&#x003E;
237 #include &#x003C;time.h&#x003E;
238 #include &#x003C;unistd.h&#x003E;
239
240 #include &#x003C;linux/dvb/dmx.h&#x003E;
241 #include &#x003C;linux/dvb/video.h&#x003E;
242 #include &#x003C;sys/poll.h&#x003E;
243 #define DVR "/dev/dvb/adapter0/dvr1"
244 #define AUDIO "/dev/dvb/adapter0/audio1"
245 #define VIDEO "/dev/dvb/adapter0/video1"
246
247 #define BUFFY (188&#x22C6;20)
248 #define MAX_LENGTH (1024&#x22C6;1024&#x22C6;5) /&#x22C6; record 5MB &#x22C6;/
249
250
251 /&#x22C6; switch the demuxes to recording, assuming the transponder is tuned &#x22C6;/
252
253 /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
254 /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
255
256 int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid)
257 {
258 struct dmx_pes_filter_params pesFilterParams;
259
260 if (demux1 &#x003C; 0){
261 if ((demux1=open(DMX, O_RDWR|O_NONBLOCK))
262 &#x003C; 0){
263 perror("DEMUX DEVICE: ");
264 return -1;
265 }
266 }
267
268 if (demux2 &#x003C; 0){
269 if ((demux2=open(DMX, O_RDWR|O_NONBLOCK))
270 &#x003C; 0){
271 perror("DEMUX DEVICE: ");
272 return -1;
273 }
274 }
275
276 pesFilterParams.pid = vpid;
277 pesFilterParams.input = DMX_IN_FRONTEND;
278 pesFilterParams.output = DMX_OUT_TS_TAP;
279 pesFilterParams.pes_type = DMX_PES_VIDEO;
280 pesFilterParams.flags = DMX_IMMEDIATE_START;
281 if (ioctl(demux1, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
282 perror("DEMUX DEVICE");
283 return -1;
284 }
285 pesFilterParams.pid = apid;
286 pesFilterParams.input = DMX_IN_FRONTEND;
287 pesFilterParams.output = DMX_OUT_TS_TAP;
288 pesFilterParams.pes_type = DMX_PES_AUDIO;
289 pesFilterParams.flags = DMX_IMMEDIATE_START;
290 if (ioctl(demux2, DMX_SET_PES_FILTER, &amp;pesFilterParams) &#x003C; 0){
291 perror("DEMUX DEVICE");
292 return -1;
293 }
294 return 0;
295 }
296
297 /&#x22C6; start recording MAX_LENGTH , assuming the transponder is tuned &#x22C6;/
298
299 /&#x22C6; demux1, demux2: file descriptor of video and audio filters &#x22C6;/
300 /&#x22C6; vpid, apid: PIDs of video and audio channels &#x22C6;/
301 int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid)
302 {
303 int i;
304 int len;
305 int written;
306 uint8_t buf[BUFFY];
307 uint64_t length;
308 struct pollfd pfd[1];
309 int dvr, dvr_out;
310
311 /&#x22C6; open dvr device &#x22C6;/
312 if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) &#x003C; 0){
313 perror("DVR DEVICE");
314 return -1;
315 }
316
317 /&#x22C6; switch video and audio demuxes to dvr &#x22C6;/
318 printf ("Switching dvr on\n");
319 i = switch_to_record(demux1, demux2, vpid, apid);
320 printf("finished: ");
321
322 printf("Recording %2.0f MB of test file in TS format\n",
323 MAX_LENGTH/(1024.0&#x22C6;1024.0));
324 length = 0;
325
326 /&#x22C6; open output file &#x22C6;/
327 if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT
328 |O_TRUNC, S_IRUSR|S_IWUSR
329 |S_IRGRP|S_IWGRP|S_IROTH|
330 S_IWOTH)) &#x003C; 0){
331 perror("Can't open file for dvr test");
332 return -1;
333 }
334
335 pfd[0].fd = dvr;
336 pfd[0].events = POLLIN;
337
338 /&#x22C6; poll for dvr data and write to file &#x22C6;/
339 while (length &#x003C; MAX_LENGTH ) {
340 if (poll(pfd,1,1)){
341 if (pfd[0].revents &amp; POLLIN){
342 len = read(dvr, buf, BUFFY);
343 if (len &#x003C; 0){
344 perror("recording");
345 return -1;
346 }
347 if (len &#x003E; 0){
348 written = 0;
349 while (written &#x003C; len)
350 written +=
351 write (dvr_out,
352 buf, len);
353 length += len;
354 printf("written %2.0f MB\r",
355 length/1024./1024.);
356 }
357 }
358 }
359 }
360 return 0;
361 }
362
363</programlisting>
364
365</section>
diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml
new file mode 100644
index 000000000000..60c6976fb311
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/frontend.xml
@@ -0,0 +1,1851 @@
1<title>DVB Frontend API</title>
2
3<para>The DVB frontend device controls the tuner and DVB demodulator
4hardware. It can be accessed through <emphasis
5role="tt">/dev/dvb/adapter0/frontend0</emphasis>. Data types and and
6ioctl definitions can be accessed by including <emphasis
7role="tt">linux/dvb/frontend.h</emphasis> in your application.</para>
8
9<para>DVB frontends come in three varieties: DVB-S (satellite), DVB-C
10(cable) and DVB-T (terrestrial). Transmission via the internet (DVB-IP)
11is not yet handled by this API but a future extension is possible. For
12DVB-S the frontend device also supports satellite equipment control
13(SEC) via DiSEqC and V-SEC protocols. The DiSEqC (digital SEC)
14specification is available from
15<ulink url="http://www.eutelsat.com/satellites/4_5_5.html">Eutelsat</ulink>.</para>
16
17<para>Note that the DVB API may also be used for MPEG decoder-only PCI
18cards, in which case there exists no frontend device.</para>
19
20<section id="frontend_types">
21<title>Frontend Data Types</title>
22
23<section id="frontend_type">
24<title>frontend type</title>
25
26<para>For historical reasons frontend types are named after the type of modulation used in
27transmission.</para>
28<programlisting>
29 typedef enum fe_type {
30 FE_QPSK, /&#x22C6; DVB-S &#x22C6;/
31 FE_QAM, /&#x22C6; DVB-C &#x22C6;/
32 FE_OFDM /&#x22C6; DVB-T &#x22C6;/
33 } fe_type_t;
34</programlisting>
35
36</section>
37
38<section id="frontend_caps">
39<title>frontend capabilities</title>
40
41<para>Capabilities describe what a frontend can do. Some capabilities can only be supported for
42a specific frontend type.</para>
43<programlisting>
44 typedef enum fe_caps {
45 FE_IS_STUPID = 0,
46 FE_CAN_INVERSION_AUTO = 0x1,
47 FE_CAN_FEC_1_2 = 0x2,
48 FE_CAN_FEC_2_3 = 0x4,
49 FE_CAN_FEC_3_4 = 0x8,
50 FE_CAN_FEC_4_5 = 0x10,
51 FE_CAN_FEC_5_6 = 0x20,
52 FE_CAN_FEC_6_7 = 0x40,
53 FE_CAN_FEC_7_8 = 0x80,
54 FE_CAN_FEC_8_9 = 0x100,
55 FE_CAN_FEC_AUTO = 0x200,
56 FE_CAN_QPSK = 0x400,
57 FE_CAN_QAM_16 = 0x800,
58 FE_CAN_QAM_32 = 0x1000,
59 FE_CAN_QAM_64 = 0x2000,
60 FE_CAN_QAM_128 = 0x4000,
61 FE_CAN_QAM_256 = 0x8000,
62 FE_CAN_QAM_AUTO = 0x10000,
63 FE_CAN_TRANSMISSION_MODE_AUTO = 0x20000,
64 FE_CAN_BANDWIDTH_AUTO = 0x40000,
65 FE_CAN_GUARD_INTERVAL_AUTO = 0x80000,
66 FE_CAN_HIERARCHY_AUTO = 0x100000,
67 FE_CAN_8VSB = 0x200000,
68 FE_CAN_16VSB = 0x400000,
69 FE_HAS_EXTENDED_CAPS = 0x800000,
70 FE_CAN_TURBO_FEC = 0x8000000,
71 FE_CAN_2G_MODULATION = 0x10000000,
72 FE_NEEDS_BENDING = 0x20000000,
73 FE_CAN_RECOVER = 0x40000000,
74 FE_CAN_MUTE_TS = 0x80000000
75 } fe_caps_t;
76</programlisting>
77</section>
78
79<section id="frontend_info">
80<title>frontend information</title>
81
82<para>Information about the frontend ca be queried with
83 <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
84
85<programlisting>
86 struct dvb_frontend_info {
87 char name[128];
88 fe_type_t type;
89 uint32_t frequency_min;
90 uint32_t frequency_max;
91 uint32_t frequency_stepsize;
92 uint32_t frequency_tolerance;
93 uint32_t symbol_rate_min;
94 uint32_t symbol_rate_max;
95 uint32_t symbol_rate_tolerance; /&#x22C6; ppm &#x22C6;/
96 uint32_t notifier_delay; /&#x22C6; ms &#x22C6;/
97 fe_caps_t caps;
98 };
99</programlisting>
100</section>
101
102<section id="frontend_diseqc">
103<title>diseqc master command</title>
104
105<para>A message sent from the frontend to DiSEqC capable equipment.</para>
106<programlisting>
107 struct dvb_diseqc_master_cmd {
108 uint8_t msg [6]; /&#x22C6; { framing, address, command, data[3] } &#x22C6;/
109 uint8_t msg_len; /&#x22C6; valid values are 3...6 &#x22C6;/
110 };
111</programlisting>
112</section>
113<section role="subsection">
114<title>diseqc slave reply</title>
115
116<para>A reply to the frontend from DiSEqC 2.0 capable equipment.</para>
117<programlisting>
118 struct dvb_diseqc_slave_reply {
119 uint8_t msg [4]; /&#x22C6; { framing, data [3] } &#x22C6;/
120 uint8_t msg_len; /&#x22C6; valid values are 0...4, 0 means no msg &#x22C6;/
121 int timeout; /&#x22C6; return from ioctl after timeout ms with &#x22C6;/
122 }; /&#x22C6; errorcode when no message was received &#x22C6;/
123</programlisting>
124</section>
125
126<section id="frontend_diseqc_slave_reply">
127<title>diseqc slave reply</title>
128<para>The voltage is usually used with non-DiSEqC capable LNBs to switch the polarzation
129(horizontal/vertical). When using DiSEqC epuipment this voltage has to be switched
130consistently to the DiSEqC commands as described in the DiSEqC spec.</para>
131<programlisting>
132 typedef enum fe_sec_voltage {
133 SEC_VOLTAGE_13,
134 SEC_VOLTAGE_18
135 } fe_sec_voltage_t;
136</programlisting>
137</section>
138
139<section id="frontend_sec_tone">
140<title>SEC continuous tone</title>
141
142<para>The continuous 22KHz tone is usually used with non-DiSEqC capable LNBs to switch the
143high/low band of a dual-band LNB. When using DiSEqC epuipment this voltage has to
144be switched consistently to the DiSEqC commands as described in the DiSEqC
145spec.</para>
146<programlisting>
147 typedef enum fe_sec_tone_mode {
148 SEC_TONE_ON,
149 SEC_TONE_OFF
150 } fe_sec_tone_mode_t;
151</programlisting>
152</section>
153
154<section id="frontend_sec_burst">
155<title>SEC tone burst</title>
156
157<para>The 22KHz tone burst is usually used with non-DiSEqC capable switches to select
158between two connected LNBs/satellites. When using DiSEqC epuipment this voltage has to
159be switched consistently to the DiSEqC commands as described in the DiSEqC
160spec.</para>
161<programlisting>
162 typedef enum fe_sec_mini_cmd {
163 SEC_MINI_A,
164 SEC_MINI_B
165 } fe_sec_mini_cmd_t;
166</programlisting>
167
168<para></para>
169</section>
170
171<section id="frontend_status">
172<title>frontend status</title>
173<para>Several functions of the frontend device use the fe_status data type defined
174by</para>
175<programlisting>
176 typedef enum fe_status {
177 FE_HAS_SIGNAL = 0x01, /&#x22C6; found something above the noise level &#x22C6;/
178 FE_HAS_CARRIER = 0x02, /&#x22C6; found a DVB signal &#x22C6;/
179 FE_HAS_VITERBI = 0x04, /&#x22C6; FEC is stable &#x22C6;/
180 FE_HAS_SYNC = 0x08, /&#x22C6; found sync bytes &#x22C6;/
181 FE_HAS_LOCK = 0x10, /&#x22C6; everything's working... &#x22C6;/
182 FE_TIMEDOUT = 0x20, /&#x22C6; no lock within the last ~2 seconds &#x22C6;/
183 FE_REINIT = 0x40 /&#x22C6; frontend was reinitialized, &#x22C6;/
184 } fe_status_t; /&#x22C6; application is recommned to reset &#x22C6;/
185</programlisting>
186<para>to indicate the current state and/or state changes of the frontend hardware.
187</para>
188
189</section>
190
191<section id="frontend_params">
192<title>frontend parameters</title>
193<para>The kind of parameters passed to the frontend device for tuning depend on
194the kind of hardware you are using. All kinds of parameters are combined as an
195union in the FrontendParameters structure:</para>
196<programlisting>
197 struct dvb_frontend_parameters {
198 uint32_t frequency; /&#x22C6; (absolute) frequency in Hz for QAM/OFDM &#x22C6;/
199 /&#x22C6; intermediate frequency in kHz for QPSK &#x22C6;/
200 fe_spectral_inversion_t inversion;
201 union {
202 struct dvb_qpsk_parameters qpsk;
203 struct dvb_qam_parameters qam;
204 struct dvb_ofdm_parameters ofdm;
205 } u;
206 };
207</programlisting>
208<para>For satellite QPSK frontends you have to use the <constant>QPSKParameters</constant> member defined by</para>
209<programlisting>
210 struct dvb_qpsk_parameters {
211 uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
212 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
213 };
214</programlisting>
215<para>for cable QAM frontend you use the <constant>QAMParameters</constant> structure</para>
216<programlisting>
217 struct dvb_qam_parameters {
218 uint32_t symbol_rate; /&#x22C6; symbol rate in Symbols per second &#x22C6;/
219 fe_code_rate_t fec_inner; /&#x22C6; forward error correction (see above) &#x22C6;/
220 fe_modulation_t modulation; /&#x22C6; modulation type (see above) &#x22C6;/
221 };
222</programlisting>
223<para>DVB-T frontends are supported by the <constant>OFDMParamters</constant> structure
224</para>
225<programlisting>
226 struct dvb_ofdm_parameters {
227 fe_bandwidth_t bandwidth;
228 fe_code_rate_t code_rate_HP; /&#x22C6; high priority stream code rate &#x22C6;/
229 fe_code_rate_t code_rate_LP; /&#x22C6; low priority stream code rate &#x22C6;/
230 fe_modulation_t constellation; /&#x22C6; modulation type (see above) &#x22C6;/
231 fe_transmit_mode_t transmission_mode;
232 fe_guard_interval_t guard_interval;
233 fe_hierarchy_t hierarchy_information;
234 };
235</programlisting>
236<para>In the case of QPSK frontends the <constant>Frequency</constant> field specifies the intermediate
237frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of
238the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and
239OFDM frontends the Frequency specifies the absolute frequency and is given in
240Hz.
241</para>
242<para>The Inversion field can take one of these values:
243</para>
244<programlisting>
245 typedef enum fe_spectral_inversion {
246 INVERSION_OFF,
247 INVERSION_ON,
248 INVERSION_AUTO
249 } fe_spectral_inversion_t;
250</programlisting>
251<para>It indicates if spectral inversion should be presumed or not. In the automatic setting
252(<constant>INVERSION_AUTO</constant>) the hardware will try to figure out the correct setting by
253itself.
254</para>
255<para>The possible values for the <constant>FEC_inner</constant> field are
256</para>
257<programlisting>
258 typedef enum fe_code_rate {
259 FEC_NONE = 0,
260 FEC_1_2,
261 FEC_2_3,
262 FEC_3_4,
263 FEC_4_5,
264 FEC_5_6,
265 FEC_6_7,
266 FEC_7_8,
267 FEC_8_9,
268 FEC_AUTO
269 } fe_code_rate_t;
270</programlisting>
271<para>which correspond to error correction rates of 1/2, 2/3, etc., no error correction or auto
272detection.
273</para>
274<para>For cable and terrestrial frontends (QAM and OFDM) one also has to specify the quadrature
275modulation mode which can be one of the following:
276</para>
277<programlisting>
278 typedef enum fe_modulation {
279 QPSK,
280 QAM_16,
281 QAM_32,
282 QAM_64,
283 QAM_128,
284 QAM_256,
285 QAM_AUTO
286 } fe_modulation_t;
287</programlisting>
288<para>Finally, there are several more parameters for OFDM:
289</para>
290<programlisting>
291 typedef enum fe_transmit_mode {
292 TRANSMISSION_MODE_2K,
293 TRANSMISSION_MODE_8K,
294 TRANSMISSION_MODE_AUTO
295 } fe_transmit_mode_t;
296</programlisting>
297 <programlisting>
298 typedef enum fe_bandwidth {
299 BANDWIDTH_8_MHZ,
300 BANDWIDTH_7_MHZ,
301 BANDWIDTH_6_MHZ,
302 BANDWIDTH_AUTO
303 } fe_bandwidth_t;
304</programlisting>
305 <programlisting>
306 typedef enum fe_guard_interval {
307 GUARD_INTERVAL_1_32,
308 GUARD_INTERVAL_1_16,
309 GUARD_INTERVAL_1_8,
310 GUARD_INTERVAL_1_4,
311 GUARD_INTERVAL_AUTO
312 } fe_guard_interval_t;
313</programlisting>
314 <programlisting>
315 typedef enum fe_hierarchy {
316 HIERARCHY_NONE,
317 HIERARCHY_1,
318 HIERARCHY_2,
319 HIERARCHY_4,
320 HIERARCHY_AUTO
321 } fe_hierarchy_t;
322</programlisting>
323
324</section>
325
326<section id="frontend_events">
327<title>frontend events</title>
328 <programlisting>
329 struct dvb_frontend_event {
330 fe_status_t status;
331 struct dvb_frontend_parameters parameters;
332 };
333</programlisting>
334 </section>
335</section>
336
337
338<section id="frontend_fcalls">
339<title>Frontend Function Calls</title>
340
341<section id="frontend_f_open">
342<title>open()</title>
343<para>DESCRIPTION</para>
344<informaltable><tgroup cols="1"><tbody><row>
345<entry align="char">
346<para>This system call opens a named frontend device (/dev/dvb/adapter0/frontend0)
347 for subsequent use. Usually the first thing to do after a successful open is to
348 find out the frontend type with <link linkend="FE_GET_INFO">FE_GET_INFO</link>.</para>
349<para>The device can be opened in read-only mode, which only allows monitoring of
350 device status and statistics, or read/write mode, which allows any kind of use
351 (e.g. performing tuning operations.)
352</para>
353<para>In a system with multiple front-ends, it is usually the case that multiple devices
354 cannot be open in read/write mode simultaneously. As long as a front-end
355 device is opened in read/write mode, other open() calls in read/write mode will
356 either fail or block, depending on whether non-blocking or blocking mode was
357 specified. A front-end device opened in blocking mode can later be put into
358 non-blocking mode (and vice versa) using the F_SETFL command of the fcntl
359 system call. This is a standard system call, documented in the Linux manual
360 page for fcntl. When an open() call has succeeded, the device will be ready
361 for use in the specified mode. This implies that the corresponding hardware is
362 powered up, and that other front-ends may have been powered down to make
363 that possible.</para>
364</entry>
365 </row></tbody></tgroup></informaltable>
366
367<para>SYNOPSIS</para>
368<informaltable><tgroup cols="1"><tbody><row><entry
369 align="char">
370<para>int open(const char &#x22C6;deviceName, int flags);</para>
371</entry>
372 </row></tbody></tgroup></informaltable>
373<para>PARAMETERS
374</para>
375<informaltable><tgroup cols="2"><tbody><row><entry
376 align="char">
377<para>const char
378 *deviceName</para>
379</entry><entry
380 align="char">
381<para>Name of specific video device.</para>
382</entry>
383 </row><row><entry
384 align="char">
385<para>int flags</para>
386</entry><entry
387 align="char">
388<para>A bit-wise OR of the following flags:</para>
389</entry>
390 </row><row><entry
391 align="char">
392</entry><entry
393 align="char">
394<para>O_RDONLY read-only access</para>
395</entry>
396 </row><row><entry
397 align="char">
398</entry><entry
399 align="char">
400<para>O_RDWR read/write access</para>
401</entry>
402 </row><row><entry
403 align="char">
404</entry><entry
405 align="char">
406<para>O_NONBLOCK open in non-blocking mode</para>
407</entry>
408 </row><row><entry
409 align="char">
410</entry><entry
411 align="char">
412<para>(blocking mode is the default)</para>
413</entry>
414 </row></tbody></tgroup></informaltable>
415<para>ERRORS
416</para>
417<informaltable><tgroup cols="2"><tbody><row><entry
418 align="char">
419<para>ENODEV</para>
420</entry><entry
421 align="char">
422<para>Device driver not loaded/available.</para>
423</entry>
424 </row><row><entry
425 align="char">
426<para>EINTERNAL</para>
427</entry><entry
428 align="char">
429<para>Internal error.</para>
430</entry>
431 </row><row><entry
432 align="char">
433<para>EBUSY</para>
434</entry><entry
435 align="char">
436<para>Device or resource busy.</para>
437</entry>
438 </row><row><entry
439 align="char">
440<para>EINVAL</para>
441</entry><entry
442 align="char">
443<para>Invalid argument.</para>
444</entry>
445 </row></tbody></tgroup></informaltable>
446</section>
447
448<section id="frontend_f_close">
449<title>close()</title>
450<para>DESCRIPTION
451</para>
452<informaltable><tgroup cols="1"><tbody><row><entry
453 align="char">
454<para>This system call closes a previously opened front-end device. After closing
455 a front-end device, its corresponding hardware might be powered down
456 automatically.</para>
457</entry>
458 </row></tbody></tgroup></informaltable>
459<para>SYNOPSIS
460</para>
461<informaltable><tgroup cols="1"><tbody><row><entry
462 align="char">
463<para>int close(int fd);</para>
464</entry>
465 </row></tbody></tgroup></informaltable>
466<para>PARAMETERS
467</para>
468<informaltable><tgroup cols="2"><tbody><row><entry
469 align="char">
470<para>int fd</para>
471</entry><entry
472 align="char">
473<para>File descriptor returned by a previous call to open().</para>
474</entry>
475 </row></tbody></tgroup></informaltable>
476<para>ERRORS
477</para>
478<informaltable><tgroup cols="2"><tbody><row><entry
479 align="char">
480<para>EBADF</para>
481</entry><entry
482 align="char">
483<para>fd is not a valid open file descriptor.</para>
484</entry>
485 </row></tbody></tgroup></informaltable>
486</section>
487
488<section id="FE_READ_STATUS">
489<title>FE_READ_STATUS</title>
490<para>DESCRIPTION
491</para>
492<informaltable><tgroup cols="1"><tbody><row><entry
493 align="char">
494<para>This ioctl call returns status information about the front-end. This call only
495 requires read-only access to the device.</para>
496</entry>
497 </row></tbody></tgroup></informaltable>
498<para>SYNOPSIS
499</para>
500<informaltable><tgroup cols="1"><tbody><row><entry
501 align="char">
502<para>int ioctl(int fd, int request = <link linkend="FE_READ_STATUS">FE_READ_STATUS</link>,
503 fe_status_t &#x22C6;status);</para>
504</entry>
505 </row></tbody></tgroup></informaltable>
506<para>PARAMETERS
507</para>
508
509<informaltable><tgroup cols="2"><tbody><row><entry
510 align="char">
511<para>int fd</para>
512</entry><entry
513 align="char">
514<para>File descriptor returned by a previous call to open().</para>
515</entry>
516 </row><row><entry
517 align="char">
518<para>int request</para>
519</entry><entry
520 align="char">
521<para>Equals <link linkend="FE_READ_STATUS">FE_READ_STATUS</link> for this command.</para>
522</entry>
523 </row><row><entry
524 align="char">
525<para>struct fe_status_t
526 *status</para>
527</entry><entry
528 align="char">
529<para>Points to the location where the front-end status word is
530 to be stored.</para>
531</entry>
532 </row></tbody></tgroup></informaltable>
533<para>ERRORS
534</para>
535<informaltable><tgroup cols="2"><tbody><row><entry
536 align="char">
537<para>EBADF</para>
538</entry><entry
539 align="char">
540<para>fd is not a valid open file descriptor.</para>
541</entry>
542 </row><row><entry
543 align="char">
544<para>EFAULT</para>
545</entry><entry
546 align="char">
547<para>status points to invalid address.</para>
548</entry>
549 </row></tbody></tgroup></informaltable>
550</section>
551
552<section id="FE_READ_BER">
553<title>FE_READ_BER</title>
554<para>DESCRIPTION
555</para>
556<informaltable><tgroup cols="1"><tbody><row><entry
557 align="char">
558<para>This ioctl call returns the bit error rate for the signal currently
559 received/demodulated by the front-end. For this command, read-only access to
560 the device is sufficient.</para>
561</entry>
562 </row></tbody></tgroup></informaltable>
563<para>SYNOPSIS
564</para>
565<informaltable><tgroup cols="1"><tbody><row><entry
566 align="char">
567<para>int ioctl(int fd, int request = <link linkend="FE_READ_BER">FE_READ_BER</link>,
568 uint32_t &#x22C6;ber);</para>
569</entry>
570 </row></tbody></tgroup></informaltable>
571<para>PARAMETERS
572</para>
573<informaltable><tgroup cols="2"><tbody><row><entry
574 align="char">
575<para>int fd</para>
576</entry><entry
577 align="char">
578<para>File descriptor returned by a previous call to open().</para>
579</entry>
580 </row><row><entry
581 align="char">
582<para>int request</para>
583</entry><entry
584 align="char">
585<para>Equals <link linkend="FE_READ_BER">FE_READ_BER</link> for this command.</para>
586</entry>
587 </row><row><entry
588 align="char">
589<para>uint32_t *ber</para>
590</entry><entry
591 align="char">
592<para>The bit error rate is stored into *ber.</para>
593</entry>
594 </row></tbody></tgroup></informaltable>
595<para>ERRORS
596</para>
597<informaltable><tgroup cols="2"><tbody><row><entry
598 align="char">
599<para>EBADF</para>
600</entry><entry
601 align="char">
602<para>fd is not a valid open file descriptor.</para>
603</entry>
604 </row><row><entry
605 align="char">
606<para>EFAULT</para>
607</entry><entry
608 align="char">
609<para>ber points to invalid address.</para>
610</entry>
611 </row><row><entry
612 align="char">
613<para>ENOSIGNAL</para>
614</entry><entry
615 align="char">
616<para>There is no signal, thus no meaningful bit error rate. Also
617 returned if the front-end is not turned on.</para>
618</entry>
619 </row><row><entry
620 align="char">
621<para>ENOSYS</para>
622</entry><entry
623 align="char">
624<para>Function not available for this device.</para>
625</entry>
626 </row></tbody></tgroup></informaltable>
627</section>
628
629<section id="FE_READ_SNR">
630<title>FE_READ_SNR</title>
631
632<para>DESCRIPTION
633</para>
634<informaltable><tgroup cols="1"><tbody><row><entry
635 align="char">
636<para>This ioctl call returns the signal-to-noise ratio for the signal currently received
637 by the front-end. For this command, read-only access to the device is sufficient.</para>
638</entry>
639 </row></tbody></tgroup></informaltable>
640<para>SYNOPSIS
641</para>
642<informaltable><tgroup cols="1"><tbody><row><entry
643 align="char">
644<para>int ioctl(int fd, int request = <link linkend="FE_READ_SNR">FE_READ_SNR</link>, int16_t
645 &#x22C6;snr);</para>
646</entry>
647 </row></tbody></tgroup></informaltable>
648<para>PARAMETERS
649</para>
650<informaltable><tgroup cols="2"><tbody><row><entry
651 align="char">
652<para>int fd</para>
653</entry><entry
654 align="char">
655<para>File descriptor returned by a previous call to open().</para>
656</entry>
657 </row><row><entry
658 align="char">
659<para>int request</para>
660</entry><entry
661 align="char">
662<para>Equals <link linkend="FE_READ_SNR">FE_READ_SNR</link> for this command.</para>
663</entry>
664 </row><row><entry
665 align="char">
666<para>int16_t *snr</para>
667</entry><entry
668 align="char">
669<para>The signal-to-noise ratio is stored into *snr.</para>
670</entry>
671 </row></tbody></tgroup></informaltable>
672
673<para>ERRORS
674</para>
675<informaltable><tgroup cols="2"><tbody><row><entry
676 align="char">
677<para>EBADF</para>
678</entry><entry
679 align="char">
680<para>fd is not a valid open file descriptor.</para>
681</entry>
682 </row><row><entry
683 align="char">
684<para>EFAULT</para>
685</entry><entry
686 align="char">
687<para>snr points to invalid address.</para>
688</entry>
689 </row><row><entry
690 align="char">
691<para>ENOSIGNAL</para>
692</entry><entry
693 align="char">
694<para>There is no signal, thus no meaningful signal strength
695 value. Also returned if front-end is not turned on.</para>
696</entry>
697 </row><row><entry
698 align="char">
699<para>ENOSYS</para>
700</entry><entry
701 align="char">
702<para>Function not available for this device.</para>
703</entry>
704 </row></tbody></tgroup></informaltable>
705</section>
706
707<section id="FE_READ_SIGNAL_STRENGTH">
708<title>FE_READ_SIGNAL_STRENGTH</title>
709<para>DESCRIPTION
710</para>
711<informaltable><tgroup cols="1"><tbody><row><entry
712 align="char">
713<para>This ioctl call returns the signal strength value for the signal currently received
714 by the front-end. For this command, read-only access to the device is sufficient.</para>
715</entry>
716 </row></tbody></tgroup></informaltable>
717<para>SYNOPSIS
718</para>
719<informaltable><tgroup cols="1"><tbody><row><entry
720 align="char">
721<para>int ioctl( int fd, int request =
722 <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link>, int16_t &#x22C6;strength);</para>
723</entry>
724 </row></tbody></tgroup></informaltable>
725
726<para>PARAMETERS
727</para>
728<informaltable><tgroup cols="2"><tbody><row><entry
729 align="char">
730<para>int fd</para>
731</entry><entry
732 align="char">
733<para>File descriptor returned by a previous call to open().</para>
734</entry>
735 </row><row><entry
736 align="char">
737<para>int request</para>
738</entry><entry
739 align="char">
740<para>Equals <link linkend="FE_READ_SIGNAL_STRENGTH">FE_READ_SIGNAL_STRENGTH</link> for this
741 command.</para>
742</entry>
743 </row><row><entry
744 align="char">
745<para>int16_t *strength</para>
746</entry><entry
747 align="char">
748<para>The signal strength value is stored into *strength.</para>
749</entry>
750 </row></tbody></tgroup></informaltable>
751<para>ERRORS
752</para>
753<informaltable><tgroup cols="2"><tbody><row><entry
754 align="char">
755<para>EBADF</para>
756</entry><entry
757 align="char">
758<para>fd is not a valid open file descriptor.</para>
759</entry>
760 </row><row><entry
761 align="char">
762<para>EFAULT</para>
763</entry><entry
764 align="char">
765<para>status points to invalid address.</para>
766</entry>
767 </row><row><entry
768 align="char">
769<para>ENOSIGNAL</para>
770</entry><entry
771 align="char">
772<para>There is no signal, thus no meaningful signal strength
773 value. Also returned if front-end is not turned on.</para>
774</entry>
775 </row><row><entry
776 align="char">
777<para>ENOSYS</para>
778</entry><entry
779 align="char">
780<para>Function not available for this device.</para>
781</entry>
782 </row></tbody></tgroup></informaltable>
783</section>
784
785<section id="FE_READ_UNCORRECTED_BLOCKS">
786<title>FE_READ_UNCORRECTED_BLOCKS</title>
787<para>DESCRIPTION
788</para>
789<informaltable><tgroup cols="1"><tbody><row><entry
790 align="char">
791<para>This ioctl call returns the number of uncorrected blocks detected by the device
792 driver during its lifetime. For meaningful measurements, the increment in block
793 count during a specific time interval should be calculated. For this command,
794 read-only access to the device is sufficient.</para>
795</entry>
796 </row><row><entry
797 align="char">
798<para>Note that the counter will wrap to zero after its maximum count has been
799 reached.</para>
800</entry>
801 </row></tbody></tgroup></informaltable>
802<para>SYNOPSIS
803</para>
804<informaltable><tgroup cols="1"><tbody><row><entry
805 align="char">
806<para>int ioctl( int fd, int request =
807 <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link>, uint32_t &#x22C6;ublocks);</para>
808</entry>
809 </row></tbody></tgroup></informaltable>
810<para>PARAMETERS
811</para>
812<informaltable><tgroup cols="2"><tbody><row><entry
813 align="char">
814<para>int fd</para>
815</entry><entry
816 align="char">
817<para>File descriptor returned by a previous call to open().</para>
818</entry>
819 </row><row><entry
820 align="char">
821<para>int request</para>
822</entry><entry
823 align="char">
824<para>Equals <link linkend="FE_READ_UNCORRECTED_BLOCKS">FE_READ_UNCORRECTED_BLOCKS</link> for this
825 command.</para>
826</entry>
827 </row><row><entry
828 align="char">
829<para>uint32_t *ublocks</para>
830</entry><entry
831 align="char">
832<para>The total number of uncorrected blocks seen by the driver
833 so far.</para>
834</entry>
835 </row></tbody></tgroup></informaltable>
836<para>ERRORS
837</para>
838<informaltable><tgroup cols="2"><tbody><row><entry
839 align="char">
840<para>EBADF</para>
841</entry><entry
842 align="char">
843<para>fd is not a valid open file descriptor.</para>
844</entry>
845 </row><row><entry
846 align="char">
847<para>EFAULT</para>
848</entry><entry
849 align="char">
850<para>ublocks points to invalid address.</para>
851</entry>
852 </row><row><entry
853 align="char">
854<para>ENOSYS</para>
855</entry><entry
856 align="char">
857<para>Function not available for this device.</para>
858</entry>
859 </row></tbody></tgroup></informaltable>
860</section>
861
862<section id="FE_SET_FRONTEND">
863<title>FE_SET_FRONTEND</title>
864<para>DESCRIPTION
865</para>
866<informaltable><tgroup cols="1"><tbody><row><entry
867 align="char">
868<para>This ioctl call starts a tuning operation using specified parameters. The result
869 of this call will be successful if the parameters were valid and the tuning could
870 be initiated. The result of the tuning operation in itself, however, will arrive
871 asynchronously as an event (see documentation for <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> and
872 FrontendEvent.) If a new <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> operation is initiated before
873 the previous one was completed, the previous operation will be aborted in favor
874 of the new one. This command requires read/write access to the device.</para>
875</entry>
876 </row></tbody></tgroup></informaltable>
877
878<para>SYNOPSIS
879</para>
880<informaltable><tgroup cols="1"><tbody><row><entry
881 align="char">
882<para>int ioctl(int fd, int request = <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link>,
883 struct dvb_frontend_parameters &#x22C6;p);</para>
884</entry>
885 </row></tbody></tgroup></informaltable>
886<para>PARAMETERS
887</para>
888<informaltable><tgroup cols="2"><tbody><row><entry
889 align="char">
890<para>int fd</para>
891</entry><entry
892 align="char">
893<para>File descriptor returned by a previous call to open().</para>
894</entry>
895 </row><row><entry
896 align="char">
897<para>int request</para>
898</entry><entry
899 align="char">
900<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
901</entry>
902 </row><row><entry
903 align="char">
904<para>struct
905 dvb_frontend_parameters
906 *p</para>
907</entry><entry
908 align="char">
909<para>Points to parameters for tuning operation.</para>
910</entry>
911 </row></tbody></tgroup></informaltable>
912<para>ERRORS
913</para>
914<informaltable><tgroup cols="2"><tbody><row><entry
915 align="char">
916<para>EBADF</para>
917</entry><entry
918 align="char">
919<para>fd is not a valid open file descriptor.</para>
920</entry>
921 </row><row><entry
922 align="char">
923<para>EFAULT</para>
924</entry><entry
925 align="char">
926<para>p points to invalid address.</para>
927</entry>
928 </row><row><entry
929 align="char">
930<para>EINVAL</para>
931</entry><entry
932 align="char">
933<para>Maximum supported symbol rate reached.</para>
934</entry>
935</row></tbody></tgroup></informaltable>
936</section>
937
938<section id="FE_GET_FRONTEND">
939<title>FE_GET_FRONTEND</title>
940<para>DESCRIPTION
941</para>
942<informaltable><tgroup cols="1"><tbody><row><entry
943 align="char">
944<para>This ioctl call queries the currently effective frontend parameters. For this
945 command, read-only access to the device is sufficient.</para>
946</entry>
947 </row></tbody></tgroup></informaltable>
948
949<para>SYNOPSIS
950</para>
951<informaltable><tgroup cols="1"><tbody><row><entry
952 align="char">
953<para>int ioctl(int fd, int request = <link linkend="FE_GET_FRONTEND">FE_GET_FRONTEND</link>,
954 struct dvb_frontend_parameters &#x22C6;p);</para>
955</entry>
956 </row></tbody></tgroup></informaltable>
957
958<para>PARAMETERS
959</para>
960<informaltable><tgroup cols="2"><tbody><row><entry
961 align="char">
962<para>int fd</para>
963</entry><entry
964 align="char">
965<para>File descriptor returned by a previous call to open().</para>
966</entry>
967 </row><row><entry
968 align="char">
969<para>int request</para>
970</entry><entry
971 align="char">
972<para>Equals <link linkend="FE_SET_FRONTEND">FE_SET_FRONTEND</link> for this command.</para>
973</entry>
974 </row><row><entry
975 align="char">
976<para>struct
977 dvb_frontend_parameters
978 *p</para>
979</entry><entry
980 align="char">
981<para>Points to parameters for tuning operation.</para>
982</entry>
983 </row></tbody></tgroup></informaltable>
984
985<para>ERRORS
986</para>
987
988<informaltable><tgroup cols="2"><tbody><row><entry
989 align="char">
990<para>EBADF</para>
991</entry><entry
992 align="char">
993<para>fd is not a valid open file descriptor.</para>
994</entry>
995 </row><row><entry
996 align="char">
997<para>EFAULT</para>
998</entry><entry
999 align="char">
1000<para>p points to invalid address.</para>
1001</entry>
1002 </row><row><entry
1003 align="char">
1004<para>EINVAL</para>
1005</entry><entry
1006 align="char">
1007<para>Maximum supported symbol rate reached.</para>
1008</entry>
1009 </row></tbody></tgroup></informaltable>
1010
1011</section>
1012
1013<section id="FE_GET_EVENT">
1014<title>FE_GET_EVENT</title>
1015<para>DESCRIPTION
1016</para>
1017<informaltable><tgroup cols="1"><tbody><row><entry
1018 align="char">
1019<para>This ioctl call returns a frontend event if available. If an event is not
1020 available, the behavior depends on whether the device is in blocking or
1021 non-blocking mode. In the latter case, the call fails immediately with errno
1022 set to EWOULDBLOCK. In the former case, the call blocks until an event
1023 becomes available.</para>
1024</entry>
1025 </row><row><entry
1026 align="char">
1027<para>The standard Linux poll() and/or select() system calls can be used with the
1028 device file descriptor to watch for new events. For select(), the file descriptor
1029 should be included in the exceptfds argument, and for poll(), POLLPRI should
1030 be specified as the wake-up condition. Since the event queue allocated is
1031 rather small (room for 8 events), the queue must be serviced regularly to avoid
1032 overflow. If an overflow happens, the oldest event is discarded from the queue,
1033 and an error (EOVERFLOW) occurs the next time the queue is read. After
1034 reporting the error condition in this fashion, subsequent
1035 <link linkend="FE_GET_EVENT">FE_GET_EVENT</link>
1036 calls will return events from the queue as usual.</para>
1037</entry>
1038 </row><row><entry
1039 align="char">
1040<para>For the sake of implementation simplicity, this command requires read/write
1041 access to the device.</para>
1042</entry>
1043 </row></tbody></tgroup></informaltable>
1044
1045<para>SYNOPSIS
1046</para>
1047<informaltable><tgroup cols="1"><tbody><row><entry
1048 align="char">
1049<para>int ioctl(int fd, int request = QPSK_GET_EVENT,
1050 struct dvb_frontend_event &#x22C6;ev);</para>
1051</entry>
1052 </row></tbody></tgroup></informaltable>
1053
1054<para>PARAMETERS
1055</para>
1056<informaltable><tgroup cols="2"><tbody><row><entry
1057 align="char">
1058<para>int fd</para>
1059</entry><entry
1060 align="char">
1061<para>File descriptor returned by a previous call to open().</para>
1062</entry>
1063 </row><row><entry
1064 align="char">
1065<para>int request</para>
1066</entry><entry
1067 align="char">
1068<para>Equals <link linkend="FE_GET_EVENT">FE_GET_EVENT</link> for this command.</para>
1069</entry>
1070 </row><row><entry
1071 align="char">
1072<para>struct
1073 dvb_frontend_event
1074 *ev</para>
1075</entry><entry
1076 align="char">
1077<para>Points to the location where the event,</para>
1078</entry>
1079 </row><row><entry
1080 align="char">
1081</entry><entry
1082 align="char">
1083<para>if any, is to be stored.</para>
1084</entry>
1085 </row></tbody></tgroup></informaltable>
1086
1087<para>ERRORS
1088</para>
1089<informaltable><tgroup cols="2"><tbody><row><entry
1090 align="char">
1091<para>EBADF</para>
1092</entry><entry
1093 align="char">
1094<para>fd is not a valid open file descriptor.</para>
1095</entry>
1096 </row><row><entry
1097 align="char">
1098<para>EFAULT</para>
1099</entry><entry
1100 align="char">
1101<para>ev points to invalid address.</para>
1102</entry>
1103 </row><row><entry
1104 align="char">
1105<para>EWOULDBLOCK</para>
1106</entry><entry
1107 align="char">
1108<para>There is no event pending, and the device is in
1109 non-blocking mode.</para>
1110</entry>
1111 </row><row><entry
1112 align="char">
1113<para>EOVERFLOW</para>
1114</entry><entry
1115 align="char">
1116</entry>
1117 </row><row><entry
1118 align="char">
1119</entry><entry
1120 align="char">
1121<para>Overflow in event queue - one or more events were lost.</para>
1122</entry>
1123</row></tbody></tgroup></informaltable>
1124</section>
1125
1126<section id="FE_GET_INFO">
1127<title>FE_GET_INFO</title>
1128<para>DESCRIPTION
1129</para>
1130<informaltable><tgroup cols="1"><tbody><row><entry
1131 align="char">
1132<para>This ioctl call returns information about the front-end. This call only requires
1133 read-only access to the device.</para>
1134</entry>
1135 </row></tbody></tgroup></informaltable>
1136<para>SYNOPSIS
1137</para>
1138
1139<informaltable><tgroup cols="1"><tbody><row><entry
1140 align="char">
1141<para> int ioctl(int fd, int request = <link linkend="FE_GET_INFO">FE_GET_INFO</link>, struct
1142 dvb_frontend_info &#x22C6;info);</para>
1143</entry>
1144 </row></tbody></tgroup></informaltable>
1145<para>PARAMETERS
1146</para>
1147
1148<informaltable><tgroup cols="2"><tbody><row><entry
1149 align="char">
1150<para>int fd</para>
1151</entry><entry
1152 align="char">
1153<para>File descriptor returned by a previous call to open().</para>
1154</entry>
1155 </row><row><entry
1156 align="char">
1157<para>int request</para>
1158</entry><entry
1159 align="char">
1160<para>Equals <link linkend="FE_GET_INFO">FE_GET_INFO</link> for this command.</para>
1161</entry>
1162 </row><row><entry
1163 align="char">
1164<para>struct
1165 dvb_frontend_info
1166 *info</para>
1167</entry><entry
1168 align="char">
1169<para>Points to the location where the front-end information is
1170 to be stored.</para>
1171</entry>
1172 </row></tbody></tgroup></informaltable>
1173<para>ERRORS
1174</para>
1175<informaltable><tgroup cols="2"><tbody><row><entry
1176 align="char">
1177<para>EBADF</para>
1178</entry><entry
1179 align="char">
1180<para>fd is not a valid open file descriptor.</para>
1181</entry>
1182 </row><row><entry
1183 align="char">
1184<para>EFAULT</para>
1185</entry><entry
1186 align="char">
1187<para>info points to invalid address.</para>
1188</entry>
1189</row></tbody></tgroup></informaltable>
1190</section>
1191
1192<section id="FE_DISEQC_RESET_OVERLOAD">
1193<title>FE_DISEQC_RESET_OVERLOAD</title>
1194<para>DESCRIPTION
1195</para>
1196<informaltable><tgroup cols="1"><tbody><row><entry
1197 align="char">
1198<para>If the bus has been automatically powered off due to power overload, this ioctl
1199 call restores the power to the bus. The call requires read/write access to the
1200 device. This call has no effect if the device is manually powered off. Not all
1201 DVB adapters support this ioctl.</para>
1202</entry>
1203 </row></tbody></tgroup></informaltable>
1204
1205<para>SYNOPSIS
1206</para>
1207<informaltable><tgroup cols="1"><tbody><row><entry
1208 align="char">
1209<para>int ioctl(int fd, int request =
1210 <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link>);</para>
1211</entry>
1212 </row></tbody></tgroup></informaltable>
1213<para>PARAMETERS
1214</para>
1215<informaltable><tgroup cols="2"><tbody><row><entry
1216 align="char">
1217<para>int fd</para>
1218</entry><entry
1219 align="char">
1220<para>File descriptor returned by a previous call to open().</para>
1221</entry>
1222 </row><row><entry
1223 align="char">
1224<para>int request</para>
1225</entry><entry
1226 align="char">
1227<para>Equals <link linkend="FE_DISEQC_RESET_OVERLOAD">FE_DISEQC_RESET_OVERLOAD</link> for this
1228 command.</para>
1229</entry>
1230 </row></tbody></tgroup></informaltable>
1231
1232<para>ERRORS
1233</para>
1234<informaltable><tgroup cols="2"><tbody><row><entry
1235 align="char">
1236<para>EBADF</para>
1237</entry><entry
1238 align="char">
1239<para>fd is not a valid file descriptor.</para>
1240</entry>
1241 </row><row><entry
1242 align="char">
1243<para>EPERM</para>
1244</entry><entry
1245 align="char">
1246<para>Permission denied (needs read/write access).</para>
1247</entry>
1248 </row><row><entry
1249 align="char">
1250<para>EINTERNAL</para>
1251</entry><entry
1252 align="char">
1253<para>Internal error in the device driver.</para>
1254</entry>
1255</row></tbody></tgroup></informaltable>
1256</section>
1257
1258<section id="FE_DISEQC_SEND_MASTER_CMD">
1259<title>FE_DISEQC_SEND_MASTER_CMD</title>
1260<para>DESCRIPTION
1261</para>
1262<informaltable><tgroup cols="1"><tbody><row><entry
1263 align="char">
1264<para>This ioctl call is used to send a a DiSEqC command.</para>
1265</entry>
1266 </row></tbody></tgroup></informaltable>
1267<para>SYNOPSIS
1268</para>
1269<informaltable><tgroup cols="1"><tbody><row><entry
1270 align="char">
1271<para>int ioctl(int fd, int request =
1272 <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link>, struct
1273 dvb_diseqc_master_cmd &#x22C6;cmd);</para>
1274</entry>
1275 </row></tbody></tgroup></informaltable>
1276
1277<para>PARAMETERS
1278</para>
1279<informaltable><tgroup cols="2"><tbody><row><entry
1280 align="char">
1281<para>int fd</para>
1282</entry><entry
1283 align="char">
1284<para>File descriptor returned by a previous call to open().</para>
1285</entry>
1286 </row><row><entry
1287 align="char">
1288<para>int request</para>
1289</entry><entry
1290 align="char">
1291<para>Equals <link linkend="FE_DISEQC_SEND_MASTER_CMD">FE_DISEQC_SEND_MASTER_CMD</link> for this
1292 command.</para>
1293</entry>
1294 </row><row><entry
1295 align="char">
1296<para>struct
1297 dvb_diseqc_master_cmd
1298 *cmd</para>
1299</entry><entry
1300 align="char">
1301<para>Pointer to the command to be transmitted.</para>
1302</entry>
1303 </row></tbody></tgroup></informaltable>
1304
1305<para>ERRORS
1306</para>
1307<informaltable><tgroup cols="2"><tbody><row><entry
1308 align="char">
1309<para>EBADF</para>
1310</entry><entry
1311 align="char">
1312<para>fd is not a valid file descriptor.</para>
1313</entry>
1314 </row><row><entry
1315 align="char">
1316<para>EFAULT</para>
1317</entry><entry
1318 align="char">
1319<para>Seq points to an invalid address.</para>
1320</entry>
1321 </row><row><entry
1322 align="char">
1323<para>EINVAL</para>
1324</entry><entry
1325 align="char">
1326<para>The data structure referred to by seq is invalid in some
1327 way.</para>
1328</entry>
1329 </row><row><entry
1330 align="char">
1331<para>EPERM</para>
1332</entry><entry
1333 align="char">
1334<para>Permission denied (needs read/write access).</para>
1335</entry>
1336 </row><row><entry
1337 align="char">
1338<para>EINTERNAL</para>
1339</entry><entry
1340 align="char">
1341<para>Internal error in the device driver.</para>
1342</entry>
1343</row></tbody></tgroup></informaltable>
1344</section>
1345
1346<section id="FE_DISEQC_RECV_SLAVE_REPLY">
1347<title>FE_DISEQC_RECV_SLAVE_REPLY</title>
1348<para>DESCRIPTION
1349</para>
1350<informaltable><tgroup cols="1"><tbody><row><entry
1351 align="char">
1352<para>This ioctl call is used to receive reply to a DiSEqC 2.0 command.</para>
1353</entry>
1354 </row></tbody></tgroup></informaltable>
1355
1356<para>SYNOPSIS
1357</para>
1358<informaltable><tgroup cols="1"><tbody><row><entry
1359 align="char">
1360<para>int ioctl(int fd, int request =
1361 <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link>, struct
1362 dvb_diseqc_slave_reply &#x22C6;reply);</para>
1363</entry>
1364 </row></tbody></tgroup></informaltable>
1365
1366<para>PARAMETERS
1367</para>
1368<informaltable><tgroup cols="2"><tbody><row><entry
1369 align="char">
1370<para>int fd</para>
1371</entry><entry
1372 align="char">
1373<para>File descriptor returned by a previous call to open().</para>
1374</entry>
1375 </row><row><entry
1376 align="char">
1377<para>int request</para>
1378</entry><entry
1379 align="char">
1380<para>Equals <link linkend="FE_DISEQC_RECV_SLAVE_REPLY">FE_DISEQC_RECV_SLAVE_REPLY</link> for this
1381 command.</para>
1382</entry>
1383 </row><row><entry
1384 align="char">
1385<para>struct
1386 dvb_diseqc_slave_reply
1387 *reply</para>
1388</entry><entry
1389 align="char">
1390<para>Pointer to the command to be received.</para>
1391</entry>
1392 </row></tbody></tgroup></informaltable>
1393<para>ERRORS
1394</para>
1395<informaltable><tgroup cols="2"><tbody><row><entry
1396 align="char">
1397<para>EBADF</para>
1398</entry><entry
1399 align="char">
1400<para>fd is not a valid file descriptor.</para>
1401</entry>
1402 </row><row><entry
1403 align="char">
1404<para>EFAULT</para>
1405</entry><entry
1406 align="char">
1407<para>Seq points to an invalid address.</para>
1408</entry>
1409 </row><row><entry
1410 align="char">
1411<para>EINVAL</para>
1412</entry><entry
1413 align="char">
1414<para>The data structure referred to by seq is invalid in some
1415 way.</para>
1416</entry>
1417 </row><row><entry
1418 align="char">
1419<para>EPERM</para>
1420</entry><entry
1421 align="char">
1422<para>Permission denied (needs read/write access).</para>
1423</entry>
1424 </row><row><entry
1425 align="char">
1426<para>EINTERNAL</para>
1427</entry><entry
1428 align="char">
1429<para>Internal error in the device driver.</para>
1430</entry>
1431 </row></tbody></tgroup></informaltable>
1432</section>
1433
1434<section id="FE_DISEQC_SEND_BURST">
1435<title>FE_DISEQC_SEND_BURST</title>
1436<para>DESCRIPTION
1437</para>
1438<informaltable><tgroup cols="1"><tbody><row><entry
1439 align="char">
1440<para>This ioctl call is used to send a 22KHz tone burst.</para>
1441</entry>
1442 </row></tbody></tgroup></informaltable>
1443
1444<para>SYNOPSIS
1445</para>
1446<informaltable><tgroup cols="1"><tbody><row><entry
1447 align="char">
1448<para>int ioctl(int fd, int request =
1449 <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link>, fe_sec_mini_cmd_t burst);</para>
1450</entry>
1451 </row></tbody></tgroup></informaltable>
1452
1453<para>PARAMETERS
1454</para>
1455<informaltable><tgroup cols="2"><tbody><row><entry
1456 align="char">
1457<para>int fd</para>
1458</entry><entry
1459 align="char">
1460<para>File descriptor returned by a previous call to open().</para>
1461</entry>
1462 </row><row><entry
1463 align="char">
1464<para>int request</para>
1465</entry><entry
1466 align="char">
1467<para>Equals <link linkend="FE_DISEQC_SEND_BURST">FE_DISEQC_SEND_BURST</link> for this command.</para>
1468</entry>
1469 </row><row><entry
1470 align="char">
1471<para>fe_sec_mini_cmd_t
1472 burst</para>
1473</entry><entry
1474 align="char">
1475<para>burst A or B.</para>
1476</entry>
1477 </row></tbody></tgroup></informaltable>
1478
1479<para>ERRORS
1480</para>
1481<informaltable><tgroup cols="2"><tbody><row><entry
1482 align="char">
1483<para>EBADF</para>
1484</entry><entry
1485 align="char">
1486<para>fd is not a valid file descriptor.</para>
1487</entry>
1488 </row><row><entry
1489 align="char">
1490<para>EFAULT</para>
1491</entry><entry
1492 align="char">
1493<para>Seq points to an invalid address.</para>
1494</entry>
1495 </row><row><entry
1496 align="char">
1497<para>EINVAL</para>
1498</entry><entry
1499 align="char">
1500<para>The data structure referred to by seq is invalid in some
1501 way.</para>
1502</entry>
1503 </row><row><entry
1504 align="char">
1505<para>EPERM</para>
1506</entry><entry
1507 align="char">
1508<para>Permission denied (needs read/write access).</para>
1509</entry>
1510 </row><row><entry
1511 align="char">
1512<para>EINTERNAL</para>
1513</entry><entry
1514 align="char">
1515<para>Internal error in the device driver.</para>
1516</entry>
1517</row></tbody></tgroup></informaltable>
1518</section>
1519
1520<section id="FE_SET_TONE">
1521<title>FE_SET_TONE</title>
1522<para>DESCRIPTION
1523</para>
1524<informaltable><tgroup cols="1"><tbody><row><entry
1525 align="char">
1526<para>This call is used to set the generation of the continuous 22kHz tone. This call
1527 requires read/write permissions.</para>
1528</entry>
1529 </row></tbody></tgroup></informaltable>
1530<para>SYNOPSIS
1531</para>
1532<informaltable><tgroup cols="1"><tbody><row><entry
1533 align="char">
1534<para>int ioctl(int fd, int request = <link linkend="FE_SET_TONE">FE_SET_TONE</link>,
1535 fe_sec_tone_mode_t tone);</para>
1536</entry>
1537 </row></tbody></tgroup></informaltable>
1538<para>PARAMETERS
1539</para>
1540<informaltable><tgroup cols="2"><tbody><row><entry
1541 align="char">
1542<para>int fd</para>
1543</entry><entry
1544 align="char">
1545<para>File descriptor returned by a previous call to open().</para>
1546</entry>
1547 </row><row><entry
1548 align="char">
1549<para>int request</para>
1550</entry><entry
1551 align="char">
1552<para>Equals <link linkend="FE_SET_TONE">FE_SET_TONE</link> for this command.</para>
1553</entry>
1554 </row><row><entry
1555 align="char">
1556<para>fe_sec_tone_mode_t
1557 tone</para>
1558</entry><entry
1559 align="char">
1560<para>The requested tone generation mode (on/off).</para>
1561</entry>
1562 </row></tbody></tgroup></informaltable>
1563<para>ERRORS
1564</para>
1565<informaltable><tgroup cols="2"><tbody><row><entry
1566 align="char">
1567<para>ENODEV</para>
1568</entry><entry
1569 align="char">
1570<para>Device driver not loaded/available.</para>
1571</entry>
1572 </row><row><entry
1573 align="char">
1574<para>EBUSY</para>
1575</entry><entry
1576 align="char">
1577<para>Device or resource busy.</para>
1578</entry>
1579 </row><row><entry
1580 align="char">
1581<para>EINVAL</para>
1582</entry><entry
1583 align="char">
1584<para>Invalid argument.</para>
1585</entry>
1586 </row><row><entry
1587 align="char">
1588<para>EPERM</para>
1589</entry><entry
1590 align="char">
1591<para>File not opened with read permissions.</para>
1592</entry>
1593 </row><row><entry
1594 align="char">
1595<para>EINTERNAL</para>
1596</entry><entry
1597 align="char">
1598<para>Internal error in the device driver.</para>
1599</entry>
1600</row></tbody></tgroup></informaltable>
1601</section>
1602
1603<section id="FE_SET_VOLTAGE">
1604<title>FE_SET_VOLTAGE</title>
1605<para>DESCRIPTION
1606</para>
1607<informaltable><tgroup cols="1"><tbody><row><entry
1608 align="char">
1609<para>This call is used to set the bus voltage. This call requires read/write
1610 permissions.</para>
1611</entry>
1612 </row></tbody></tgroup></informaltable>
1613<para>SYNOPSIS
1614</para>
1615<informaltable><tgroup cols="1"><tbody><row><entry
1616 align="char">
1617<para>int ioctl(int fd, int request = <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link>,
1618 fe_sec_voltage_t voltage);</para>
1619</entry>
1620 </row></tbody></tgroup></informaltable>
1621
1622<para>PARAMETERS
1623</para>
1624<informaltable><tgroup cols="2"><tbody><row><entry
1625 align="char">
1626<para>int fd</para>
1627</entry><entry
1628 align="char">
1629<para>File descriptor returned by a previous call to open().</para>
1630</entry>
1631 </row><row><entry
1632 align="char">
1633<para>int request</para>
1634</entry><entry
1635 align="char">
1636<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
1637</entry>
1638 </row><row><entry
1639 align="char">
1640<para>fe_sec_voltage_t
1641 voltage</para>
1642</entry><entry
1643 align="char">
1644<para>The requested bus voltage.</para>
1645</entry>
1646 </row></tbody></tgroup></informaltable>
1647
1648<para>ERRORS
1649</para>
1650<informaltable><tgroup cols="2"><tbody><row><entry
1651 align="char">
1652<para>ENODEV</para>
1653</entry><entry
1654 align="char">
1655<para>Device driver not loaded/available.</para>
1656</entry>
1657 </row><row><entry
1658 align="char">
1659<para>EBUSY</para>
1660</entry><entry
1661 align="char">
1662<para>Device or resource busy.</para>
1663</entry>
1664 </row><row><entry
1665 align="char">
1666<para>EINVAL</para>
1667</entry><entry
1668 align="char">
1669<para>Invalid argument.</para>
1670</entry>
1671 </row><row><entry
1672 align="char">
1673<para>EPERM</para>
1674</entry><entry
1675 align="char">
1676<para>File not opened with read permissions.</para>
1677</entry>
1678 </row><row><entry
1679 align="char">
1680<para>EINTERNAL</para>
1681</entry><entry
1682 align="char">
1683<para>Internal error in the device driver.</para>
1684</entry>
1685 </row></tbody></tgroup></informaltable>
1686</section>
1687
1688<section id="FE_ENABLE_HIGH_LNB_VOLTAGE">
1689<title>FE_ENABLE_HIGH_LNB_VOLTAGE</title>
1690<para>DESCRIPTION
1691</para>
1692<informaltable><tgroup cols="1"><tbody><row><entry
1693 align="char">
1694<para>If high != 0 enables slightly higher voltages instead of 13/18V (to compensate
1695 for long cables). This call requires read/write permissions. Not all DVB
1696 adapters support this ioctl.</para>
1697</entry>
1698 </row></tbody></tgroup></informaltable>
1699
1700<para>SYNOPSIS
1701</para>
1702<informaltable><tgroup cols="1"><tbody><row><entry
1703 align="char">
1704<para>int ioctl(int fd, int request =
1705 <link linkend="FE_ENABLE_HIGH_LNB_VOLTAGE">FE_ENABLE_HIGH_LNB_VOLTAGE</link>, int high);</para>
1706</entry>
1707 </row></tbody></tgroup></informaltable>
1708
1709<para>PARAMETERS
1710</para>
1711<informaltable><tgroup cols="2"><tbody><row><entry
1712 align="char">
1713<para>int fd</para>
1714</entry><entry
1715 align="char">
1716<para>File descriptor returned by a previous call to open().</para>
1717</entry>
1718 </row><row><entry
1719 align="char">
1720<para>int request</para>
1721</entry><entry
1722 align="char">
1723<para>Equals <link linkend="FE_SET_VOLTAGE">FE_SET_VOLTAGE</link> for this command.</para>
1724</entry>
1725 </row><row><entry
1726 align="char">
1727<para>int high</para>
1728</entry><entry
1729 align="char">
1730<para>The requested bus voltage.</para>
1731</entry>
1732 </row></tbody></tgroup></informaltable>
1733
1734<para>ERRORS
1735</para>
1736<informaltable><tgroup cols="2"><tbody><row><entry
1737 align="char">
1738<para>ENODEV</para>
1739</entry><entry
1740 align="char">
1741<para>Device driver not loaded/available.</para>
1742</entry>
1743 </row><row><entry
1744 align="char">
1745<para>EBUSY</para>
1746</entry><entry
1747 align="char">
1748<para>Device or resource busy.</para>
1749</entry>
1750 </row><row><entry
1751 align="char">
1752<para>EINVAL</para>
1753</entry><entry
1754 align="char">
1755<para>Invalid argument.</para>
1756</entry>
1757 </row><row><entry
1758 align="char">
1759<para>EPERM</para>
1760</entry><entry
1761 align="char">
1762<para>File not opened with read permissions.</para>
1763</entry>
1764 </row><row><entry
1765 align="char">
1766<para>EINTERNAL</para>
1767</entry><entry
1768 align="char">
1769<para>Internal error in the device driver.</para>
1770</entry>
1771 </row></tbody></tgroup></informaltable>
1772</section>
1773
1774<section id="FE_SET_FRONTEND_TUNE_MODE">
1775<title>FE_SET_FRONTEND_TUNE_MODE</title>
1776<para>DESCRIPTION</para>
1777<informaltable><tgroup cols="1"><tbody><row>
1778<entry align="char">
1779<para>Allow setting tuner mode flags to the frontend.</para>
1780</entry>
1781</row></tbody></tgroup></informaltable>
1782
1783<para>SYNOPSIS</para>
1784<informaltable><tgroup cols="1"><tbody><row>
1785<entry align="char">
1786<para>int ioctl(int fd, int request =
1787<link linkend="FE_SET_FRONTEND_TUNE_MODE">FE_SET_FRONTEND_TUNE_MODE</link>, unsigned int flags);</para>
1788</entry>
1789</row></tbody></tgroup></informaltable>
1790
1791<para>PARAMETERS</para>
1792<informaltable><tgroup cols="2"><tbody><row>
1793<entry align="char">
1794 <para>unsigned int flags</para>
1795</entry>
1796<entry align="char">
1797<para>
1798FE_TUNE_MODE_ONESHOT When set, this flag will disable any zigzagging or other "normal" tuning behaviour. Additionally, there will be no automatic monitoring of the lock status, and hence no frontend events will be generated. If a frontend device is closed, this flag will be automatically turned off when the device is reopened read-write.
1799</para>
1800</entry>
1801 </row></tbody></tgroup></informaltable>
1802
1803<para>ERRORS</para>
1804<informaltable><tgroup cols="2"><tbody><row>
1805<entry align="char"><para>EINVAL</para></entry>
1806<entry align="char"><para>Invalid argument.</para></entry>
1807 </row></tbody></tgroup></informaltable>
1808</section>
1809
1810<section id="FE_DISHNETWORK_SEND_LEGACY_CMD">
1811 <title>FE_DISHNETWORK_SEND_LEGACY_CMD</title>
1812<para>DESCRIPTION</para>
1813<informaltable><tgroup cols="1"><tbody><row>
1814<entry align="char">
1815<para>WARNING: This is a very obscure legacy command, used only at stv0299 driver. Should not be used on newer drivers.</para>
1816<para>It provides a non-standard method for selecting Diseqc voltage on the frontend, for Dish Network legacy switches.</para>
1817<para>As support for this ioctl were added in 2004, this means that such dishes were already legacy in 2004.</para>
1818</entry>
1819</row></tbody></tgroup></informaltable>
1820
1821<para>SYNOPSIS</para>
1822<informaltable><tgroup cols="1"><tbody><row>
1823<entry align="char">
1824<para>int ioctl(int fd, int request =
1825 <link linkend="FE_DISHNETWORK_SEND_LEGACY_CMD">FE_DISHNETWORK_SEND_LEGACY_CMD</link>, unsigned long cmd);</para>
1826</entry>
1827</row></tbody></tgroup></informaltable>
1828
1829<para>PARAMETERS</para>
1830<informaltable><tgroup cols="2"><tbody><row>
1831<entry align="char">
1832 <para>unsigned long cmd</para>
1833</entry>
1834<entry align="char">
1835<para>
1836sends the specified raw cmd to the dish via DISEqC.
1837</para>
1838</entry>
1839 </row></tbody></tgroup></informaltable>
1840
1841<para>ERRORS</para>
1842<informaltable><tgroup cols="1"><tbody><row>
1843<entry align="char">
1844 <para>There are no errors in use for this call</para>
1845</entry>
1846</row></tbody></tgroup></informaltable>
1847</section>
1848
1849</section>
1850
1851&sub-dvbproperty;
diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml
new file mode 100644
index 000000000000..0dc83f672ea2
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/intro.xml
@@ -0,0 +1,191 @@
1<title>Introduction</title>
2
3<section id="requisites">
4<title>What you need to know</title>
5
6<para>The reader of this document is required to have some knowledge in
7the area of digital video broadcasting (DVB) and should be familiar with
8part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e
9you should know what a program/transport stream (PS/TS) is and what is
10meant by a packetized elementary stream (PES) or an I-frame.</para>
11
12<para>Various DVB standards documents are available from
13<ulink url="http://www.dvb.org" /> and/or
14<ulink url="http://www.etsi.org" />.</para>
15
16<para>It is also necessary to know how to access unix/linux devices and
17how to use ioctl calls. This also includes the knowledge of C or C++.
18</para>
19</section>
20
21<section id="history">
22<title>History</title>
23
24<para>The first API for DVB cards we used at Convergence in late 1999
25was an extension of the Video4Linux API which was primarily developed
26for frame grabber cards. As such it was not really well suited to be
27used for DVB cards and their new features like recording MPEG streams
28and filtering several section and PES data streams at the same time.
29</para>
30
31<para>In early 2000, we were approached by Nokia with a proposal for a
32new standard Linux DVB API. As a commitment to the development of
33terminals based on open standards, Nokia and Convergence made it
34available to all Linux developers and published it on
35<ulink url="http://www.linuxtv.org/" /> in September 2000.
36Convergence is the maintainer of the Linux DVB API. Together with the
37LinuxTV community (i.e. you, the reader of this document), the Linux DVB
38API will be constantly reviewed and improved. With the Linux driver for
39the Siemens/Hauppauge DVB PCI card Convergence provides a first
40implementation of the Linux DVB API.</para>
41</section>
42
43<section id="overview">
44<title>Overview</title>
45
46<figure id="stb_components">
47<title>Components of a DVB card/STB</title>
48<mediaobject>
49<imageobject>
50<imagedata fileref="dvbstb.pdf" format="PS" />
51</imageobject>
52<imageobject>
53<imagedata fileref="dvbstb.png" format="PNG" />
54</imageobject>
55</mediaobject>
56</figure>
57
58<para>A DVB PCI card or DVB set-top-box (STB) usually consists of the
59following main hardware components: </para>
60
61<itemizedlist>
62 <listitem>
63
64<para>Frontend consisting of tuner and DVB demodulator</para>
65
66<para>Here the raw signal reaches the DVB hardware from a satellite dish
67or antenna or directly from cable. The frontend down-converts and
68demodulates this signal into an MPEG transport stream (TS). In case of a
69satellite frontend, this includes a facility for satellite equipment
70control (SEC), which allows control of LNB polarization, multi feed
71switches or dish rotors.</para>
72
73</listitem>
74 <listitem>
75
76<para>Conditional Access (CA) hardware like CI adapters and smartcard slots
77</para>
78
79<para>The complete TS is passed through the CA hardware. Programs to
80which the user has access (controlled by the smart card) are decoded in
81real time and re-inserted into the TS.</para>
82
83</listitem>
84 <listitem>
85 <para>Demultiplexer which filters the incoming DVB stream</para>
86
87<para>The demultiplexer splits the TS into its components like audio and
88video streams. Besides usually several of such audio and video streams
89it also contains data streams with information about the programs
90offered in this or other streams of the same provider.</para>
91
92</listitem>
93<listitem>
94
95<para>MPEG2 audio and video decoder</para>
96
97<para>The main targets of the demultiplexer are the MPEG2 audio and
98video decoders. After decoding they pass on the uncompressed audio and
99video to the computer screen or (through a PAL/NTSC encoder) to a TV
100set.</para>
101
102
103</listitem>
104</itemizedlist>
105
106<para><xref linkend="stb_components" /> shows a crude schematic of the control and data flow
107between those components.</para>
108
109<para>On a DVB PCI card not all of these have to be present since some
110functionality can be provided by the main CPU of the PC (e.g. MPEG
111picture and sound decoding) or is not needed (e.g. for data-only uses
112like &#8220;internet over satellite&#8221;). Also not every card or STB
113provides conditional access hardware.</para>
114
115</section>
116
117<section id="dvb_devices">
118<title>Linux DVB Devices</title>
119
120<para>The Linux DVB API lets you control these hardware components
121through currently six Unix-style character devices for video, audio,
122frontend, demux, CA and IP-over-DVB networking. The video and audio
123devices control the MPEG2 decoder hardware, the frontend device the
124tuner and the DVB demodulator. The demux device gives you control over
125the PES and section filters of the hardware. If the hardware does not
126support filtering these filters can be implemented in software. Finally,
127the CA device controls all the conditional access capabilities of the
128hardware. It can depend on the individual security requirements of the
129platform, if and how many of the CA functions are made available to the
130application through this device.</para>
131
132<para>All devices can be found in the <emphasis role="tt">/dev</emphasis>
133tree under <emphasis role="tt">/dev/dvb</emphasis>. The individual devices
134are called:</para>
135
136<itemizedlist>
137<listitem>
138
139<para><emphasis role="tt">/dev/dvb/adapterN/audioM</emphasis>,</para>
140</listitem>
141<listitem>
142<para><emphasis role="tt">/dev/dvb/adapterN/videoM</emphasis>,</para>
143</listitem>
144<listitem>
145<para><emphasis role="tt">/dev/dvb/adapterN/frontendM</emphasis>,</para>
146</listitem>
147 <listitem>
148
149<para><emphasis role="tt">/dev/dvb/adapterN/netM</emphasis>,</para>
150</listitem>
151 <listitem>
152
153<para><emphasis role="tt">/dev/dvb/adapterN/demuxM</emphasis>,</para>
154</listitem>
155 <listitem>
156
157<para><emphasis role="tt">/dev/dvb/adapterN/caM</emphasis>,</para></listitem></itemizedlist>
158
159<para>where N enumerates the DVB PCI cards in a system starting
160from&#x00A0;0, and M enumerates the devices of each type within each
161adapter, starting from&#x00A0;0, too. We will omit the &#8220;<emphasis
162role="tt">/dev/dvb/adapterN/</emphasis>&#8221; in the further dicussion
163of these devices. The naming scheme for the devices is the same wheter
164devfs is used or not.</para>
165
166<para>More details about the data structures and function calls of all
167the devices are described in the following chapters.</para>
168
169</section>
170
171<section id="include_files">
172<title>API include files</title>
173
174<para>For each of the DVB devices a corresponding include file exists.
175The DVB API include files should be included in application sources with
176a partial path like:</para>
177
178
179<programlisting>
180 #include &#x003C;linux/dvb/frontend.h&#x003E;
181</programlisting>
182
183<para>To enable applications to support different API version, an
184additional include file <emphasis
185role="tt">linux/dvb/version.h</emphasis> exists, which defines the
186constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document
187describes <emphasis role="tt">DVB_API_VERSION&#x00A0;3</emphasis>.
188</para>
189
190</section>
191
diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml
new file mode 100644
index 000000000000..6c67481eaa4b
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/kdapi.xml
@@ -0,0 +1,2309 @@
1<title>Kernel Demux API</title>
2<para>The kernel demux API defines a driver-internal interface for registering low-level,
3hardware specific driver to a hardware independent demux layer. It is only of interest for
4DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in
5<emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>.
6</para>
7<para>Maintainer note: This section must be reviewed. It is probably out of date.
8</para>
9
10<section id="kernel_demux_data_types">
11<title>Kernel Demux Data Types</title>
12
13
14<section id="dmx_success_t">
15<title>dmx_success_t</title>
16 <programlisting>
17 typedef enum {
18 DMX_OK = 0, /&#x22C6; Received Ok &#x22C6;/
19 DMX_LENGTH_ERROR, /&#x22C6; Incorrect length &#x22C6;/
20 DMX_OVERRUN_ERROR, /&#x22C6; Receiver ring buffer overrun &#x22C6;/
21 DMX_CRC_ERROR, /&#x22C6; Incorrect CRC &#x22C6;/
22 DMX_FRAME_ERROR, /&#x22C6; Frame alignment error &#x22C6;/
23 DMX_FIFO_ERROR, /&#x22C6; Receiver FIFO overrun &#x22C6;/
24 DMX_MISSED_ERROR /&#x22C6; Receiver missed packet &#x22C6;/
25 } dmx_success_t;
26</programlisting>
27
28</section>
29<section id="ts_filter_types">
30<title>TS filter types</title>
31 <programlisting>
32 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
33 /&#x22C6; TS packet reception &#x22C6;/
34 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
35
36 /&#x22C6; TS filter type for set_type() &#x22C6;/
37
38 #define TS_PACKET 1 /&#x22C6; send TS packets (188 bytes) to callback (default) &#x22C6;/
39 #define TS_PAYLOAD_ONLY 2 /&#x22C6; in case TS_PACKET is set, only send the TS
40 payload (&#x003C;=184 bytes per packet) to callback &#x22C6;/
41 #define TS_DECODER 4 /&#x22C6; send stream to built-in decoder (if present) &#x22C6;/
42</programlisting>
43
44</section>
45<section id="dmx_ts_pes_t">
46<title>dmx_ts_pes_t</title>
47<para>The structure
48</para>
49<programlisting>
50 typedef enum
51 {
52 DMX_TS_PES_AUDIO, /&#x22C6; also send packets to audio decoder (if it exists) &#x22C6;/
53 DMX_TS_PES_VIDEO, /&#x22C6; ... &#x22C6;/
54 DMX_TS_PES_TELETEXT,
55 DMX_TS_PES_SUBTITLE,
56 DMX_TS_PES_PCR,
57 DMX_TS_PES_OTHER,
58 } dmx_ts_pes_t;
59</programlisting>
60<para>describes the PES type for filters which write to a built-in decoder. The correspond (and
61should be kept identical) to the types in the demux device.
62</para>
63<programlisting>
64 struct dmx_ts_feed_s {
65 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
66 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
67 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
68 int (&#x22C6;set) (struct dmx_ts_feed_s&#x22C6; feed,
69 __u16 pid,
70 size_t callback_length,
71 size_t circular_buffer_size,
72 int descramble,
73 struct timespec timeout);
74 int (&#x22C6;start_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
75 int (&#x22C6;stop_filtering) (struct dmx_ts_feed_s&#x22C6; feed);
76 int (&#x22C6;set_type) (struct dmx_ts_feed_s&#x22C6; feed,
77 int type,
78 dmx_ts_pes_t pes_type);
79 };
80
81 typedef struct dmx_ts_feed_s dmx_ts_feed_t;
82</programlisting>
83 <programlisting>
84 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
85 /&#x22C6; PES packet reception (not supported yet) &#x22C6;/
86 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
87
88 typedef struct dmx_pes_filter_s {
89 struct dmx_pes_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
90 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
91 } dmx_pes_filter_t;
92</programlisting>
93 <programlisting>
94 typedef struct dmx_pes_feed_s {
95 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
96 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
97 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
98 int (&#x22C6;set) (struct dmx_pes_feed_s&#x22C6; feed,
99 __u16 pid,
100 size_t circular_buffer_size,
101 int descramble,
102 struct timespec timeout);
103 int (&#x22C6;start_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
104 int (&#x22C6;stop_filtering) (struct dmx_pes_feed_s&#x22C6; feed);
105 int (&#x22C6;allocate_filter) (struct dmx_pes_feed_s&#x22C6; feed,
106 dmx_pes_filter_t&#x22C6;&#x22C6; filter);
107 int (&#x22C6;release_filter) (struct dmx_pes_feed_s&#x22C6; feed,
108 dmx_pes_filter_t&#x22C6; filter);
109 } dmx_pes_feed_t;
110</programlisting>
111 <programlisting>
112 typedef struct {
113 __u8 filter_value [DMX_MAX_FILTER_SIZE];
114 __u8 filter_mask [DMX_MAX_FILTER_SIZE];
115 struct dmx_section_feed_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
116 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
117 } dmx_section_filter_t;
118</programlisting>
119 <programlisting>
120 struct dmx_section_feed_s {
121 int is_filtering; /&#x22C6; Set to non-zero when filtering in progress &#x22C6;/
122 struct dmx_demux_s&#x22C6; parent; /&#x22C6; Back-pointer &#x22C6;/
123 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
124 int (&#x22C6;set) (struct dmx_section_feed_s&#x22C6; feed,
125 __u16 pid,
126 size_t circular_buffer_size,
127 int descramble,
128 int check_crc);
129 int (&#x22C6;allocate_filter) (struct dmx_section_feed_s&#x22C6; feed,
130 dmx_section_filter_t&#x22C6;&#x22C6; filter);
131 int (&#x22C6;release_filter) (struct dmx_section_feed_s&#x22C6; feed,
132 dmx_section_filter_t&#x22C6; filter);
133 int (&#x22C6;start_filtering) (struct dmx_section_feed_s&#x22C6; feed);
134 int (&#x22C6;stop_filtering) (struct dmx_section_feed_s&#x22C6; feed);
135 };
136 typedef struct dmx_section_feed_s dmx_section_feed_t;
137
138 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
139 /&#x22C6; Callback functions &#x22C6;/
140 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
141
142 typedef int (&#x22C6;dmx_ts_cb) ( __u8 &#x22C6; buffer1,
143 size_t buffer1_length,
144 __u8 &#x22C6; buffer2,
145 size_t buffer2_length,
146 dmx_ts_feed_t&#x22C6; source,
147 dmx_success_t success);
148
149 typedef int (&#x22C6;dmx_section_cb) ( __u8 &#x22C6; buffer1,
150 size_t buffer1_len,
151 __u8 &#x22C6; buffer2,
152 size_t buffer2_len,
153 dmx_section_filter_t &#x22C6; source,
154 dmx_success_t success);
155
156 typedef int (&#x22C6;dmx_pes_cb) ( __u8 &#x22C6; buffer1,
157 size_t buffer1_len,
158 __u8 &#x22C6; buffer2,
159 size_t buffer2_len,
160 dmx_pes_filter_t&#x22C6; source,
161 dmx_success_t success);
162
163 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
164 /&#x22C6; DVB Front-End &#x22C6;/
165 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
166
167 typedef enum {
168 DMX_OTHER_FE = 0,
169 DMX_SATELLITE_FE,
170 DMX_CABLE_FE,
171 DMX_TERRESTRIAL_FE,
172 DMX_LVDS_FE,
173 DMX_ASI_FE, /&#x22C6; DVB-ASI interface &#x22C6;/
174 DMX_MEMORY_FE
175 } dmx_frontend_source_t;
176
177 typedef struct {
178 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
179 char&#x22C6; id; /&#x22C6; Unique front-end identifier &#x22C6;/
180 char&#x22C6; vendor; /&#x22C6; Name of the front-end vendor &#x22C6;/
181 char&#x22C6; model; /&#x22C6; Name of the front-end model &#x22C6;/
182 struct list_head connectivity_list; /&#x22C6; List of front-ends that can
183 be connected to a particular
184 demux &#x22C6;/
185 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
186 dmx_frontend_source_t source;
187 } dmx_frontend_t;
188
189 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
190 /&#x22C6; MPEG-2 TS Demux &#x22C6;/
191 /&#x22C6;--------------------------------------------------------------------------&#x22C6;/
192
193 /&#x22C6;
194 &#x22C6; Flags OR'ed in the capabilites field of struct dmx_demux_s.
195 &#x22C6;/
196
197 #define DMX_TS_FILTERING 1
198 #define DMX_PES_FILTERING 2
199 #define DMX_SECTION_FILTERING 4
200 #define DMX_MEMORY_BASED_FILTERING 8 /&#x22C6; write() available &#x22C6;/
201 #define DMX_CRC_CHECKING 16
202 #define DMX_TS_DESCRAMBLING 32
203 #define DMX_SECTION_PAYLOAD_DESCRAMBLING 64
204 #define DMX_MAC_ADDRESS_DESCRAMBLING 128
205</programlisting>
206
207</section>
208<section id="demux_demux_t">
209<title>demux_demux_t</title>
210 <programlisting>
211 /&#x22C6;
212 &#x22C6; DMX_FE_ENTRY(): Casts elements in the list of registered
213 &#x22C6; front-ends from the generic type struct list_head
214 &#x22C6; to the type &#x22C6; dmx_frontend_t
215 &#x22C6;.
216 &#x22C6;/
217
218 #define DMX_FE_ENTRY(list) list_entry(list, dmx_frontend_t, connectivity_list)
219
220 struct dmx_demux_s {
221 /&#x22C6; The following char&#x22C6; fields point to NULL terminated strings &#x22C6;/
222 char&#x22C6; id; /&#x22C6; Unique demux identifier &#x22C6;/
223 char&#x22C6; vendor; /&#x22C6; Name of the demux vendor &#x22C6;/
224 char&#x22C6; model; /&#x22C6; Name of the demux model &#x22C6;/
225 __u32 capabilities; /&#x22C6; Bitfield of capability flags &#x22C6;/
226 dmx_frontend_t&#x22C6; frontend; /&#x22C6; Front-end connected to the demux &#x22C6;/
227 struct list_head reg_list; /&#x22C6; List of registered demuxes &#x22C6;/
228 void&#x22C6; priv; /&#x22C6; Pointer to private data of the API client &#x22C6;/
229 int users; /&#x22C6; Number of users &#x22C6;/
230 int (&#x22C6;open) (struct dmx_demux_s&#x22C6; demux);
231 int (&#x22C6;close) (struct dmx_demux_s&#x22C6; demux);
232 int (&#x22C6;write) (struct dmx_demux_s&#x22C6; demux, const char&#x22C6; buf, size_t count);
233 int (&#x22C6;allocate_ts_feed) (struct dmx_demux_s&#x22C6; demux,
234 dmx_ts_feed_t&#x22C6;&#x22C6; feed,
235 dmx_ts_cb callback);
236 int (&#x22C6;release_ts_feed) (struct dmx_demux_s&#x22C6; demux,
237 dmx_ts_feed_t&#x22C6; feed);
238 int (&#x22C6;allocate_pes_feed) (struct dmx_demux_s&#x22C6; demux,
239 dmx_pes_feed_t&#x22C6;&#x22C6; feed,
240 dmx_pes_cb callback);
241 int (&#x22C6;release_pes_feed) (struct dmx_demux_s&#x22C6; demux,
242 dmx_pes_feed_t&#x22C6; feed);
243 int (&#x22C6;allocate_section_feed) (struct dmx_demux_s&#x22C6; demux,
244 dmx_section_feed_t&#x22C6;&#x22C6; feed,
245 dmx_section_cb callback);
246 int (&#x22C6;release_section_feed) (struct dmx_demux_s&#x22C6; demux,
247 dmx_section_feed_t&#x22C6; feed);
248 int (&#x22C6;descramble_mac_address) (struct dmx_demux_s&#x22C6; demux,
249 __u8&#x22C6; buffer1,
250 size_t buffer1_length,
251 __u8&#x22C6; buffer2,
252 size_t buffer2_length,
253 __u16 pid);
254 int (&#x22C6;descramble_section_payload) (struct dmx_demux_s&#x22C6; demux,
255 __u8&#x22C6; buffer1,
256 size_t buffer1_length,
257 __u8&#x22C6; buffer2, size_t buffer2_length,
258 __u16 pid);
259 int (&#x22C6;add_frontend) (struct dmx_demux_s&#x22C6; demux,
260 dmx_frontend_t&#x22C6; frontend);
261 int (&#x22C6;remove_frontend) (struct dmx_demux_s&#x22C6; demux,
262 dmx_frontend_t&#x22C6; frontend);
263 struct list_head&#x22C6; (&#x22C6;get_frontends) (struct dmx_demux_s&#x22C6; demux);
264 int (&#x22C6;connect_frontend) (struct dmx_demux_s&#x22C6; demux,
265 dmx_frontend_t&#x22C6; frontend);
266 int (&#x22C6;disconnect_frontend) (struct dmx_demux_s&#x22C6; demux);
267
268
269 /&#x22C6; added because js cannot keep track of these himself &#x22C6;/
270 int (&#x22C6;get_pes_pids) (struct dmx_demux_s&#x22C6; demux, __u16 &#x22C6;pids);
271 };
272 typedef struct dmx_demux_s dmx_demux_t;
273</programlisting>
274
275</section>
276<section id="demux_directory">
277<title>Demux directory</title>
278 <programlisting>
279 /&#x22C6;
280 &#x22C6; DMX_DIR_ENTRY(): Casts elements in the list of registered
281 &#x22C6; demuxes from the generic type struct list_head&#x22C6; to the type dmx_demux_t
282 &#x22C6;.
283 &#x22C6;/
284
285 #define DMX_DIR_ENTRY(list) list_entry(list, dmx_demux_t, reg_list)
286
287 int dmx_register_demux (dmx_demux_t&#x22C6; demux);
288 int dmx_unregister_demux (dmx_demux_t&#x22C6; demux);
289 struct list_head&#x22C6; dmx_get_demuxes (void);
290</programlisting>
291 </section></section>
292<section id="demux_directory_api">
293<title>Demux Directory API</title>
294<para>The demux directory is a Linux kernel-wide facility for registering and accessing the
295MPEG-2 TS demuxes in the system. Run-time registering and unregistering of demux drivers
296is possible using this API.
297</para>
298<para>All demux drivers in the directory implement the abstract interface dmx_demux_t.
299</para>
300
301<section
302role="subsection"><title>dmx_register_demux()</title>
303<para>DESCRIPTION
304</para>
305<informaltable><tgroup cols="1"><tbody><row><entry
306 align="char">
307<para>This function makes a demux driver interface available to the Linux kernel. It is
308 usually called by the init_module() function of the kernel module that contains
309 the demux driver. The caller of this function is responsible for allocating
310 dynamic or static memory for the demux structure and for initializing its fields
311 before calling this function. The memory allocated for the demux structure
312 must not be freed before calling dmx_unregister_demux(),</para>
313</entry>
314 </row></tbody></tgroup></informaltable>
315<para>SYNOPSIS
316</para>
317<informaltable><tgroup cols="1"><tbody><row><entry
318 align="char">
319<para>int dmx_register_demux ( dmx_demux_t &#x22C6;demux )</para>
320</entry>
321 </row></tbody></tgroup></informaltable>
322<para>PARAMETERS
323</para>
324<informaltable><tgroup cols="2"><tbody><row><entry
325 align="char">
326<para>dmx_demux_t*
327 demux</para>
328</entry><entry
329 align="char">
330<para>Pointer to the demux structure.</para>
331</entry>
332 </row></tbody></tgroup></informaltable>
333<para>RETURNS
334</para>
335<informaltable><tgroup cols="2"><tbody><row><entry
336 align="char">
337<para>0</para>
338</entry><entry
339 align="char">
340<para>The function was completed without errors.</para>
341</entry>
342 </row><row><entry
343 align="char">
344<para>-EEXIST</para>
345</entry><entry
346 align="char">
347<para>A demux with the same value of the id field already stored
348 in the directory.</para>
349</entry>
350 </row><row><entry
351 align="char">
352<para>-ENOSPC</para>
353</entry><entry
354 align="char">
355<para>No space left in the directory.</para>
356</entry>
357 </row></tbody></tgroup></informaltable>
358
359</section><section
360role="subsection"><title>dmx_unregister_demux()</title>
361<para>DESCRIPTION
362</para>
363<informaltable><tgroup cols="1"><tbody><row><entry
364 align="char">
365<para>This function is called to indicate that the given demux interface is no
366 longer available. The caller of this function is responsible for freeing the
367 memory of the demux structure, if it was dynamically allocated before calling
368 dmx_register_demux(). The cleanup_module() function of the kernel module
369 that contains the demux driver should call this function. Note that this function
370 fails if the demux is currently in use, i.e., release_demux() has not been called
371 for the interface.</para>
372</entry>
373 </row></tbody></tgroup></informaltable>
374<para>SYNOPSIS
375</para>
376<informaltable><tgroup cols="1"><tbody><row><entry
377 align="char">
378<para>int dmx_unregister_demux ( dmx_demux_t &#x22C6;demux )</para>
379</entry>
380 </row></tbody></tgroup></informaltable>
381<para>PARAMETERS
382</para>
383<informaltable><tgroup cols="2"><tbody><row><entry
384 align="char">
385<para>dmx_demux_t*
386 demux</para>
387</entry><entry
388 align="char">
389<para>Pointer to the demux structure which is to be
390 unregistered.</para>
391</entry>
392 </row></tbody></tgroup></informaltable>
393<para>RETURNS
394</para>
395<informaltable><tgroup cols="2"><tbody><row><entry
396 align="char">
397<para>0</para>
398</entry><entry
399 align="char">
400<para>The function was completed without errors.</para>
401</entry>
402 </row><row><entry
403 align="char">
404<para>ENODEV</para>
405</entry><entry
406 align="char">
407<para>The specified demux is not registered in the demux
408 directory.</para>
409</entry>
410 </row><row><entry
411 align="char">
412<para>EBUSY</para>
413</entry><entry
414 align="char">
415<para>The specified demux is currently in use.</para>
416</entry>
417 </row></tbody></tgroup></informaltable>
418
419</section><section
420role="subsection"><title>dmx_get_demuxes()</title>
421<para>DESCRIPTION
422</para>
423<informaltable><tgroup cols="1"><tbody><row><entry
424 align="char">
425<para>Provides the caller with the list of registered demux interfaces, using the
426 standard list structure defined in the include file linux/list.h. The include file
427 demux.h defines the macro DMX_DIR_ENTRY() for converting an element of
428 the generic type struct list_head* to the type dmx_demux_t*. The caller must
429 not free the memory of any of the elements obtained via this function call.</para>
430</entry>
431 </row></tbody></tgroup></informaltable>
432<para>SYNOPSIS
433</para>
434<informaltable><tgroup cols="1"><tbody><row><entry
435 align="char">
436<para>struct list_head &#x22C6;dmx_get_demuxes ()</para>
437</entry>
438 </row></tbody></tgroup></informaltable>
439<para>PARAMETERS
440</para>
441<informaltable><tgroup cols="2"><tbody><row><entry
442 align="char">
443<para>none</para>
444</entry>
445 </row></tbody></tgroup></informaltable>
446<para>RETURNS
447</para>
448<informaltable><tgroup cols="2"><tbody><row><entry
449 align="char">
450<para>struct list_head *</para>
451</entry><entry
452 align="char">
453<para>A list of demux interfaces, or NULL in the case of an
454 empty list.</para>
455</entry>
456 </row></tbody></tgroup></informaltable>
457 </section></section>
458<section id="demux_api">
459<title>Demux API</title>
460<para>The demux API should be implemented for each demux in the system. It is used to select
461the TS source of a demux and to manage the demux resources. When the demux
462client allocates a resource via the demux API, it receives a pointer to the API of that
463resource.
464</para>
465<para>Each demux receives its TS input from a DVB front-end or from memory, as set via the
466demux API. In a system with more than one front-end, the API can be used to select one of
467the DVB front-ends as a TS source for a demux, unless this is fixed in the HW platform. The
468demux API only controls front-ends regarding their connections with demuxes; the APIs
469used to set the other front-end parameters, such as tuning, are not defined in this
470document.
471</para>
472<para>The functions that implement the abstract interface demux should be defined static or
473module private and registered to the Demux Directory for external access. It is not necessary
474to implement every function in the demux_t struct, however (for example, a demux interface
475might support Section filtering, but not TS or PES filtering). The API client is expected to
476check the value of any function pointer before calling the function: the value of NULL means
477&#8220;function not available&#8221;.
478</para>
479<para>Whenever the functions of the demux API modify shared data, the possibilities of lost
480update and race condition problems should be addressed, e.g. by protecting parts of code with
481mutexes. This is especially important on multi-processor hosts.
482</para>
483<para>Note that functions called from a bottom half context must not sleep, at least in the 2.2.x
484kernels. Even a simple memory allocation can result in a kernel thread being put to sleep if
485swapping is needed. For example, the Linux kernel calls the functions of a network device
486interface from a bottom half context. Thus, if a demux API function is called from network
487device code, the function must not sleep.
488</para>
489
490
491<section id="kdapi_fopen">
492<title>open()</title>
493<para>DESCRIPTION
494</para>
495<informaltable><tgroup cols="1"><tbody><row><entry
496 align="char">
497<para>This function reserves the demux for use by the caller and, if necessary,
498 initializes the demux. When the demux is no longer needed, the function close()
499 should be called. It should be possible for multiple clients to access the demux
500 at the same time. Thus, the function implementation should increment the
501 demux usage count when open() is called and decrement it when close() is
502 called.</para>
503</entry>
504 </row></tbody></tgroup></informaltable>
505<para>SYNOPSIS
506</para>
507<informaltable><tgroup cols="1"><tbody><row><entry
508 align="char">
509<para>int open ( demux_t&#x22C6; demux );</para>
510</entry>
511 </row></tbody></tgroup></informaltable>
512<para>PARAMETERS
513</para>
514<informaltable><tgroup cols="2"><tbody><row><entry
515 align="char">
516<para>demux_t* demux</para>
517</entry><entry
518 align="char">
519<para>Pointer to the demux API and instance data.</para>
520</entry>
521 </row></tbody></tgroup></informaltable>
522<para>RETURNS
523</para>
524<informaltable><tgroup cols="2"><tbody><row><entry
525 align="char">
526<para>0</para>
527</entry><entry
528 align="char">
529<para>The function was completed without errors.</para>
530</entry>
531 </row><row><entry
532 align="char">
533<para>-EUSERS</para>
534</entry><entry
535 align="char">
536<para>Maximum usage count reached.</para>
537</entry>
538 </row><row><entry
539 align="char">
540<para>-EINVAL</para>
541</entry><entry
542 align="char">
543<para>Bad parameter.</para>
544</entry>
545 </row></tbody></tgroup></informaltable>
546
547</section>
548<section id="kdapi_fclose">
549<title>close()</title>
550<para>DESCRIPTION
551</para>
552<informaltable><tgroup cols="1"><tbody><row><entry
553 align="char">
554<para>This function reserves the demux for use by the caller and, if necessary,
555 initializes the demux. When the demux is no longer needed, the function close()
556 should be called. It should be possible for multiple clients to access the demux
557 at the same time. Thus, the function implementation should increment the
558 demux usage count when open() is called and decrement it when close() is
559 called.</para>
560</entry>
561 </row></tbody></tgroup></informaltable>
562<para>SYNOPSIS
563</para>
564<informaltable><tgroup cols="1"><tbody><row><entry
565 align="char">
566<para>int close(demux_t&#x22C6; demux);</para>
567</entry>
568 </row></tbody></tgroup></informaltable>
569<para>PARAMETERS
570</para>
571<informaltable><tgroup cols="2"><tbody><row><entry
572 align="char">
573<para>demux_t* demux</para>
574</entry><entry
575 align="char">
576<para>Pointer to the demux API and instance data.</para>
577</entry>
578 </row></tbody></tgroup></informaltable>
579<para>RETURNS
580</para>
581<informaltable><tgroup cols="2"><tbody><row><entry
582 align="char">
583<para>0</para>
584</entry><entry
585 align="char">
586<para>The function was completed without errors.</para>
587</entry>
588 </row><row><entry
589 align="char">
590<para>-ENODEV</para>
591</entry><entry
592 align="char">
593<para>The demux was not in use.</para>
594</entry>
595 </row><row><entry
596 align="char">
597<para>-EINVAL</para>
598</entry><entry
599 align="char">
600<para>Bad parameter.</para>
601</entry>
602 </row></tbody></tgroup></informaltable>
603
604</section>
605<section id="kdapi_fwrite">
606<title>write()</title>
607<para>DESCRIPTION
608</para>
609<informaltable><tgroup cols="1"><tbody><row><entry
610 align="char">
611<para>This function provides the demux driver with a memory buffer containing TS
612 packets. Instead of receiving TS packets from the DVB front-end, the demux
613 driver software will read packets from memory. Any clients of this demux
614 with active TS, PES or Section filters will receive filtered data via the Demux
615 callback API (see 0). The function returns when all the data in the buffer has
616 been consumed by the demux. Demux hardware typically cannot read TS from
617 memory. If this is the case, memory-based filtering has to be implemented
618 entirely in software.</para>
619</entry>
620 </row></tbody></tgroup></informaltable>
621<para>SYNOPSIS
622</para>
623<informaltable><tgroup cols="1"><tbody><row><entry
624 align="char">
625<para>int write(demux_t&#x22C6; demux, const char&#x22C6; buf, size_t
626 count);</para>
627</entry>
628 </row></tbody></tgroup></informaltable>
629<para>PARAMETERS
630</para>
631<informaltable><tgroup cols="2"><tbody><row><entry
632 align="char">
633<para>demux_t* demux</para>
634</entry><entry
635 align="char">
636<para>Pointer to the demux API and instance data.</para>
637</entry>
638 </row><row><entry
639 align="char">
640<para>const char* buf</para>
641</entry><entry
642 align="char">
643<para>Pointer to the TS data in kernel-space memory.</para>
644</entry>
645 </row><row><entry
646 align="char">
647<para>size_t length</para>
648</entry><entry
649 align="char">
650<para>Length of the TS data.</para>
651</entry>
652 </row></tbody></tgroup></informaltable>
653<para>RETURNS
654</para>
655<informaltable><tgroup cols="2"><tbody><row><entry
656 align="char">
657<para>0</para>
658</entry><entry
659 align="char">
660<para>The function was completed without errors.</para>
661</entry>
662 </row><row><entry
663 align="char">
664<para>-ENOSYS</para>
665</entry><entry
666 align="char">
667<para>The command is not implemented.</para>
668</entry>
669 </row><row><entry
670 align="char">
671<para>-EINVAL</para>
672</entry><entry
673 align="char">
674<para>Bad parameter.</para>
675</entry>
676 </row></tbody></tgroup></informaltable>
677
678</section><section
679role="subsection"><title>allocate_ts_feed()</title>
680<para>DESCRIPTION
681</para>
682<informaltable><tgroup cols="1"><tbody><row><entry
683 align="char">
684<para>Allocates a new TS feed, which is used to filter the TS packets carrying a
685 certain PID. The TS feed normally corresponds to a hardware PID filter on the
686 demux chip.</para>
687</entry>
688 </row></tbody></tgroup></informaltable>
689<para>SYNOPSIS
690</para>
691<informaltable><tgroup cols="1"><tbody><row><entry
692 align="char">
693<para>int allocate_ts_feed(dmx_demux_t&#x22C6; demux,
694 dmx_ts_feed_t&#x22C6;&#x22C6; feed, dmx_ts_cb callback);</para>
695</entry>
696 </row></tbody></tgroup></informaltable>
697<para>PARAMETERS
698</para>
699<informaltable><tgroup cols="2"><tbody><row><entry
700 align="char">
701<para>demux_t* demux</para>
702</entry><entry
703 align="char">
704<para>Pointer to the demux API and instance data.</para>
705</entry>
706 </row><row><entry
707 align="char">
708<para>dmx_ts_feed_t**
709 feed</para>
710</entry><entry
711 align="char">
712<para>Pointer to the TS feed API and instance data.</para>
713</entry>
714 </row><row><entry
715 align="char">
716<para>dmx_ts_cb callback</para>
717</entry><entry
718 align="char">
719<para>Pointer to the callback function for passing received TS
720 packet</para>
721</entry>
722 </row></tbody></tgroup></informaltable>
723<para>RETURNS
724</para>
725<informaltable><tgroup cols="2"><tbody><row><entry
726 align="char">
727<para>0</para>
728</entry><entry
729 align="char">
730<para>The function was completed without errors.</para>
731</entry>
732 </row><row><entry
733 align="char">
734<para>-EBUSY</para>
735</entry><entry
736 align="char">
737<para>No more TS feeds available.</para>
738</entry>
739 </row><row><entry
740 align="char">
741<para>-ENOSYS</para>
742</entry><entry
743 align="char">
744<para>The command is not implemented.</para>
745</entry>
746 </row><row><entry
747 align="char">
748<para>-EINVAL</para>
749</entry><entry
750 align="char">
751<para>Bad parameter.</para>
752</entry>
753 </row></tbody></tgroup></informaltable>
754
755</section><section
756role="subsection"><title>release_ts_feed()</title>
757<para>DESCRIPTION
758</para>
759<informaltable><tgroup cols="1"><tbody><row><entry
760 align="char">
761<para>Releases the resources allocated with allocate_ts_feed(). Any filtering in
762 progress on the TS feed should be stopped before calling this function.</para>
763</entry>
764 </row></tbody></tgroup></informaltable>
765<para>SYNOPSIS
766</para>
767<informaltable><tgroup cols="1"><tbody><row><entry
768 align="char">
769<para>int release_ts_feed(dmx_demux_t&#x22C6; demux,
770 dmx_ts_feed_t&#x22C6; feed);</para>
771</entry>
772 </row></tbody></tgroup></informaltable>
773<para>PARAMETERS
774</para>
775<informaltable><tgroup cols="2"><tbody><row><entry
776 align="char">
777<para>demux_t* demux</para>
778</entry><entry
779 align="char">
780<para>Pointer to the demux API and instance data.</para>
781</entry>
782 </row><row><entry
783 align="char">
784<para>dmx_ts_feed_t* feed</para>
785</entry><entry
786 align="char">
787<para>Pointer to the TS feed API and instance data.</para>
788</entry>
789 </row></tbody></tgroup></informaltable>
790<para>RETURNS
791</para>
792<informaltable><tgroup cols="2"><tbody><row><entry
793 align="char">
794<para>0</para>
795</entry><entry
796 align="char">
797<para>The function was completed without errors.</para>
798</entry>
799 </row><row><entry
800 align="char">
801<para>-EINVAL</para>
802</entry><entry
803 align="char">
804<para>Bad parameter.</para>
805</entry>
806 </row></tbody></tgroup></informaltable>
807
808</section><section
809role="subsection"><title>allocate_section_feed()</title>
810<para>DESCRIPTION
811</para>
812<informaltable><tgroup cols="1"><tbody><row><entry
813 align="char">
814<para>Allocates a new section feed, i.e. a demux resource for filtering and receiving
815 sections. On platforms with hardware support for section filtering, a section
816 feed is directly mapped to the demux HW. On other platforms, TS packets are
817 first PID filtered in hardware and a hardware section filter then emulated in
818 software. The caller obtains an API pointer of type dmx_section_feed_t as an
819 out parameter. Using this API the caller can set filtering parameters and start
820 receiving sections.</para>
821</entry>
822 </row></tbody></tgroup></informaltable>
823<para>SYNOPSIS
824</para>
825<informaltable><tgroup cols="1"><tbody><row><entry
826 align="char">
827<para>int allocate_section_feed(dmx_demux_t&#x22C6; demux,
828 dmx_section_feed_t &#x22C6;&#x22C6;feed, dmx_section_cb callback);</para>
829</entry>
830 </row></tbody></tgroup></informaltable>
831<para>PARAMETERS
832</para>
833<informaltable><tgroup cols="2"><tbody><row><entry
834 align="char">
835<para>demux_t *demux</para>
836</entry><entry
837 align="char">
838<para>Pointer to the demux API and instance data.</para>
839</entry>
840 </row><row><entry
841 align="char">
842<para>dmx_section_feed_t
843 **feed</para>
844</entry><entry
845 align="char">
846<para>Pointer to the section feed API and instance data.</para>
847</entry>
848 </row><row><entry
849 align="char">
850<para>dmx_section_cb
851 callback</para>
852</entry><entry
853 align="char">
854<para>Pointer to the callback function for passing received
855 sections.</para>
856</entry>
857 </row></tbody></tgroup></informaltable>
858<para>RETURNS
859</para>
860<informaltable><tgroup cols="2"><tbody><row><entry
861 align="char">
862<para>0</para>
863</entry><entry
864 align="char">
865<para>The function was completed without errors.</para>
866</entry>
867 </row><row><entry
868 align="char">
869<para>-EBUSY</para>
870</entry><entry
871 align="char">
872<para>No more section feeds available.</para>
873</entry>
874 </row><row><entry
875 align="char">
876<para>-ENOSYS</para>
877</entry><entry
878 align="char">
879<para>The command is not implemented.</para>
880</entry>
881 </row><row><entry
882 align="char">
883<para>-EINVAL</para>
884</entry><entry
885 align="char">
886<para>Bad parameter.</para>
887</entry>
888 </row></tbody></tgroup></informaltable>
889
890</section><section
891role="subsection"><title>release_section_feed()</title>
892<para>DESCRIPTION
893</para>
894<informaltable><tgroup cols="1"><tbody><row><entry
895 align="char">
896<para>Releases the resources allocated with allocate_section_feed(), including
897 allocated filters. Any filtering in progress on the section feed should be stopped
898 before calling this function.</para>
899</entry>
900 </row></tbody></tgroup></informaltable>
901<para>SYNOPSIS
902</para>
903<informaltable><tgroup cols="1"><tbody><row><entry
904 align="char">
905<para>int release_section_feed(dmx_demux_t&#x22C6; demux,
906 dmx_section_feed_t &#x22C6;feed);</para>
907</entry>
908 </row></tbody></tgroup></informaltable>
909<para>PARAMETERS
910</para>
911<informaltable><tgroup cols="2"><tbody><row><entry
912 align="char">
913<para>demux_t *demux</para>
914</entry><entry
915 align="char">
916<para>Pointer to the demux API and instance data.</para>
917</entry>
918 </row><row><entry
919 align="char">
920<para>dmx_section_feed_t
921 *feed</para>
922</entry><entry
923 align="char">
924<para>Pointer to the section feed API and instance data.</para>
925</entry>
926 </row></tbody></tgroup></informaltable>
927<para>RETURNS
928</para>
929<informaltable><tgroup cols="2"><tbody><row><entry
930 align="char">
931<para>0</para>
932</entry><entry
933 align="char">
934<para>The function was completed without errors.</para>
935</entry>
936 </row><row><entry
937 align="char">
938<para>-EINVAL</para>
939</entry><entry
940 align="char">
941<para>Bad parameter.</para>
942</entry>
943 </row></tbody></tgroup></informaltable>
944
945</section><section
946role="subsection"><title>descramble_mac_address()</title>
947<para>DESCRIPTION
948</para>
949<informaltable><tgroup cols="1"><tbody><row><entry
950 align="char">
951<para>This function runs a descrambling algorithm on the destination MAC
952 address field of a DVB Datagram Section, replacing the original address
953 with its un-encrypted version. Otherwise, the description on the function
954 descramble_section_payload() applies also to this function.</para>
955</entry>
956 </row></tbody></tgroup></informaltable>
957<para>SYNOPSIS
958</para>
959<informaltable><tgroup cols="1"><tbody><row><entry
960 align="char">
961<para>int descramble_mac_address(dmx_demux_t&#x22C6; demux, __u8
962 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
963 size_t buffer2_length, __u16 pid);</para>
964</entry>
965 </row></tbody></tgroup></informaltable>
966<para>PARAMETERS
967</para>
968<informaltable><tgroup cols="2"><tbody><row><entry
969 align="char">
970<para>dmx_demux_t
971 *demux</para>
972</entry><entry
973 align="char">
974<para>Pointer to the demux API and instance data.</para>
975</entry>
976 </row><row><entry
977 align="char">
978<para>__u8 *buffer1</para>
979</entry><entry
980 align="char">
981<para>Pointer to the first byte of the section.</para>
982</entry>
983 </row><row><entry
984 align="char">
985<para>size_t buffer1_length</para>
986</entry><entry
987 align="char">
988<para>Length of the section data, including headers and CRC,
989 in buffer1.</para>
990</entry>
991 </row><row><entry
992 align="char">
993<para>__u8* buffer2</para>
994</entry><entry
995 align="char">
996<para>Pointer to the tail of the section data, or NULL. The
997 pointer has a non-NULL value if the section wraps past
998 the end of a circular buffer.</para>
999</entry>
1000 </row><row><entry
1001 align="char">
1002<para>size_t buffer2_length</para>
1003</entry><entry
1004 align="char">
1005<para>Length of the section data, including headers and CRC,
1006 in buffer2.</para>
1007</entry>
1008 </row><row><entry
1009 align="char">
1010<para>__u16 pid</para>
1011</entry><entry
1012 align="char">
1013<para>The PID on which the section was received. Useful
1014 for obtaining the descrambling key, e.g. from a DVB
1015 Common Access facility.</para>
1016</entry>
1017 </row></tbody></tgroup></informaltable>
1018<para>RETURNS
1019</para>
1020<informaltable><tgroup cols="2"><tbody><row><entry
1021 align="char">
1022<para>0</para>
1023</entry><entry
1024 align="char">
1025<para>The function was completed without errors.</para>
1026</entry>
1027 </row><row><entry
1028 align="char">
1029<para>-ENOSYS</para>
1030</entry><entry
1031 align="char">
1032<para>No descrambling facility available.</para>
1033</entry>
1034 </row><row><entry
1035 align="char">
1036<para>-EINVAL</para>
1037</entry><entry
1038 align="char">
1039<para>Bad parameter.</para>
1040</entry>
1041 </row></tbody></tgroup></informaltable>
1042
1043</section><section
1044role="subsection"><title>descramble_section_payload()</title>
1045<para>DESCRIPTION
1046</para>
1047<informaltable><tgroup cols="1"><tbody><row><entry
1048 align="char">
1049<para>This function runs a descrambling algorithm on the payload of a DVB
1050 Datagram Section, replacing the original payload with its un-encrypted
1051 version. The function will be called from the demux API implementation;
1052 the API client need not call this function directly. Section-level scrambling
1053 algorithms are currently standardized only for DVB-RCC (return channel
1054 over 2-directional cable TV network) systems. For all other DVB networks,
1055 encryption schemes are likely to be proprietary to each data broadcaster. Thus,
1056 it is expected that this function pointer will have the value of NULL (i.e.,
1057 function not available) in most demux API implementations. Nevertheless, it
1058 should be possible to use the function pointer as a hook for dynamically adding
1059 a &#8220;plug-in&#8221; descrambling facility to a demux driver.</para>
1060</entry>
1061 </row><row><entry
1062 align="char">
1063<para>While this function is not needed with hardware-based section descrambling,
1064 the descramble_section_payload function pointer can be used to override the
1065 default hardware-based descrambling algorithm: if the function pointer has a
1066 non-NULL value, the corresponding function should be used instead of any
1067 descrambling hardware.</para>
1068</entry>
1069 </row></tbody></tgroup></informaltable>
1070<para>SYNOPSIS
1071</para>
1072<informaltable><tgroup cols="1"><tbody><row><entry
1073 align="char">
1074<para>int descramble_section_payload(dmx_demux_t&#x22C6; demux,
1075 __u8 &#x22C6;buffer1, size_t buffer1_length, __u8 &#x22C6;buffer2,
1076 size_t buffer2_length, __u16 pid);</para>
1077</entry>
1078 </row></tbody></tgroup></informaltable>
1079<para>PARAMETERS
1080</para>
1081<informaltable><tgroup cols="2"><tbody><row><entry
1082 align="char">
1083<para>dmx_demux_t
1084 *demux</para>
1085</entry><entry
1086 align="char">
1087<para>Pointer to the demux API and instance data.</para>
1088</entry>
1089 </row><row><entry
1090 align="char">
1091<para>__u8 *buffer1</para>
1092</entry><entry
1093 align="char">
1094<para>Pointer to the first byte of the section.</para>
1095</entry>
1096 </row><row><entry
1097 align="char">
1098<para>size_t buffer1_length</para>
1099</entry><entry
1100 align="char">
1101<para>Length of the section data, including headers and CRC,
1102 in buffer1.</para>
1103</entry>
1104 </row><row><entry
1105 align="char">
1106<para>__u8 *buffer2</para>
1107</entry><entry
1108 align="char">
1109<para>Pointer to the tail of the section data, or NULL. The
1110 pointer has a non-NULL value if the section wraps past
1111 the end of a circular buffer.</para>
1112</entry>
1113 </row><row><entry
1114 align="char">
1115<para>size_t buffer2_length</para>
1116</entry><entry
1117 align="char">
1118<para>Length of the section data, including headers and CRC,
1119 in buffer2.</para>
1120</entry>
1121 </row><row><entry
1122 align="char">
1123<para>__u16 pid</para>
1124</entry><entry
1125 align="char">
1126<para>The PID on which the section was received. Useful
1127 for obtaining the descrambling key, e.g. from a DVB
1128 Common Access facility.</para>
1129</entry>
1130 </row></tbody></tgroup></informaltable>
1131<para>RETURNS
1132</para>
1133<informaltable><tgroup cols="2"><tbody><row><entry
1134 align="char">
1135<para>0</para>
1136</entry><entry
1137 align="char">
1138<para>The function was completed without errors.</para>
1139</entry>
1140 </row><row><entry
1141 align="char">
1142<para>-ENOSYS</para>
1143</entry><entry
1144 align="char">
1145<para>No descrambling facility available.</para>
1146</entry>
1147 </row><row><entry
1148 align="char">
1149<para>-EINVAL</para>
1150</entry><entry
1151 align="char">
1152<para>Bad parameter.</para>
1153</entry>
1154 </row></tbody></tgroup></informaltable>
1155
1156</section><section
1157role="subsection"><title>add_frontend()</title>
1158<para>DESCRIPTION
1159</para>
1160<informaltable><tgroup cols="1"><tbody><row><entry
1161 align="char">
1162<para>Registers a connectivity between a demux and a front-end, i.e., indicates that
1163 the demux can be connected via a call to connect_frontend() to use the given
1164 front-end as a TS source. The client of this function has to allocate dynamic or
1165 static memory for the frontend structure and initialize its fields before calling
1166 this function. This function is normally called during the driver initialization.
1167 The caller must not free the memory of the frontend struct before successfully
1168 calling remove_frontend().</para>
1169</entry>
1170 </row></tbody></tgroup></informaltable>
1171<para>SYNOPSIS
1172</para>
1173<informaltable><tgroup cols="1"><tbody><row><entry
1174 align="char">
1175<para>int add_frontend(dmx_demux_t &#x22C6;demux, dmx_frontend_t
1176 &#x22C6;frontend);</para>
1177</entry>
1178 </row></tbody></tgroup></informaltable>
1179<para>PARAMETERS
1180</para>
1181<informaltable><tgroup cols="2"><tbody><row><entry
1182 align="char">
1183<para>dmx_demux_t*
1184 demux</para>
1185</entry><entry
1186 align="char">
1187<para>Pointer to the demux API and instance data.</para>
1188</entry>
1189 </row><row><entry
1190 align="char">
1191<para>dmx_frontend_t*
1192 frontend</para>
1193</entry><entry
1194 align="char">
1195<para>Pointer to the front-end instance data.</para>
1196</entry>
1197 </row></tbody></tgroup></informaltable>
1198<para>RETURNS
1199</para>
1200<informaltable><tgroup cols="2"><tbody><row><entry
1201 align="char">
1202<para>0</para>
1203</entry><entry
1204 align="char">
1205<para>The function was completed without errors.</para>
1206</entry>
1207 </row><row><entry
1208 align="char">
1209<para>-EEXIST</para>
1210</entry><entry
1211 align="char">
1212<para>A front-end with the same value of the id field already
1213 registered.</para>
1214</entry>
1215 </row><row><entry
1216 align="char">
1217<para>-EINUSE</para>
1218</entry><entry
1219 align="char">
1220<para>The demux is in use.</para>
1221</entry>
1222 </row><row><entry
1223 align="char">
1224<para>-ENOMEM</para>
1225</entry><entry
1226 align="char">
1227<para>No more front-ends can be added.</para>
1228</entry>
1229 </row><row><entry
1230 align="char">
1231<para>-EINVAL</para>
1232</entry><entry
1233 align="char">
1234<para>Bad parameter.</para>
1235</entry>
1236 </row></tbody></tgroup></informaltable>
1237
1238</section><section
1239role="subsection"><title>remove_frontend()</title>
1240<para>DESCRIPTION
1241</para>
1242<informaltable><tgroup cols="1"><tbody><row><entry
1243 align="char">
1244<para>Indicates that the given front-end, registered by a call to add_frontend(), can
1245 no longer be connected as a TS source by this demux. The function should be
1246 called when a front-end driver or a demux driver is removed from the system.
1247 If the front-end is in use, the function fails with the return value of -EBUSY.
1248 After successfully calling this function, the caller can free the memory of
1249 the frontend struct if it was dynamically allocated before the add_frontend()
1250 operation.</para>
1251</entry>
1252 </row></tbody></tgroup></informaltable>
1253<para>SYNOPSIS
1254</para>
1255<informaltable><tgroup cols="1"><tbody><row><entry
1256 align="char">
1257<para>int remove_frontend(dmx_demux_t&#x22C6; demux,
1258 dmx_frontend_t&#x22C6; frontend);</para>
1259</entry>
1260 </row></tbody></tgroup></informaltable>
1261<para>PARAMETERS
1262</para>
1263<informaltable><tgroup cols="2"><tbody><row><entry
1264 align="char">
1265<para>dmx_demux_t*
1266 demux</para>
1267</entry><entry
1268 align="char">
1269<para>Pointer to the demux API and instance data.</para>
1270</entry>
1271 </row><row><entry
1272 align="char">
1273<para>dmx_frontend_t*
1274 frontend</para>
1275</entry><entry
1276 align="char">
1277<para>Pointer to the front-end instance data.</para>
1278</entry>
1279 </row></tbody></tgroup></informaltable>
1280<para>RETURNS
1281</para>
1282<informaltable><tgroup cols="2"><tbody><row><entry
1283 align="char">
1284<para>0</para>
1285</entry><entry
1286 align="char">
1287<para>The function was completed without errors.</para>
1288</entry>
1289 </row><row><entry
1290 align="char">
1291<para>-EINVAL</para>
1292</entry><entry
1293 align="char">
1294<para>Bad parameter.</para>
1295</entry>
1296 </row><row><entry
1297 align="char">
1298<para>-EBUSY</para>
1299</entry><entry
1300 align="char">
1301<para>The front-end is in use, i.e. a call to connect_frontend()
1302 has not been followed by a call to disconnect_frontend().</para>
1303</entry>
1304 </row></tbody></tgroup></informaltable>
1305
1306</section><section
1307role="subsection"><title>get_frontends()</title>
1308<para>DESCRIPTION
1309</para>
1310<informaltable><tgroup cols="1"><tbody><row><entry
1311 align="char">
1312<para>Provides the APIs of the front-ends that have been registered for this demux.
1313 Any of the front-ends obtained with this call can be used as a parameter for
1314 connect_frontend().</para>
1315</entry>
1316 </row><row><entry
1317 align="char">
1318<para>The include file demux.h contains the macro DMX_FE_ENTRY() for
1319 converting an element of the generic type struct list_head* to the type
1320 dmx_frontend_t*. The caller must not free the memory of any of the elements
1321 obtained via this function call.</para>
1322</entry>
1323 </row></tbody></tgroup></informaltable>
1324<para>SYNOPSIS
1325</para>
1326<informaltable><tgroup cols="1"><tbody><row><entry
1327 align="char">
1328<para>struct list_head&#x22C6; get_frontends(dmx_demux_t&#x22C6; demux);</para>
1329</entry>
1330 </row></tbody></tgroup></informaltable>
1331<para>PARAMETERS
1332</para>
1333<informaltable><tgroup cols="2"><tbody><row><entry
1334 align="char">
1335<para>dmx_demux_t*
1336 demux</para>
1337</entry><entry
1338 align="char">
1339<para>Pointer to the demux API and instance data.</para>
1340</entry>
1341 </row></tbody></tgroup></informaltable>
1342<para>RETURNS
1343</para>
1344<informaltable><tgroup cols="2"><tbody><row><entry
1345 align="char">
1346<para>dmx_demux_t*</para>
1347</entry><entry
1348 align="char">
1349<para>A list of front-end interfaces, or NULL in the case of an
1350 empty list.</para>
1351</entry>
1352 </row></tbody></tgroup></informaltable>
1353
1354</section><section
1355role="subsection"><title>connect_frontend()</title>
1356<para>DESCRIPTION
1357</para>
1358<informaltable><tgroup cols="1"><tbody><row><entry
1359 align="char">
1360<para>Connects the TS output of the front-end to the input of the demux. A demux
1361 can only be connected to a front-end registered to the demux with the function
1362 add_frontend().</para>
1363</entry>
1364 </row><row><entry
1365 align="char">
1366<para>It may or may not be possible to connect multiple demuxes to the same
1367 front-end, depending on the capabilities of the HW platform. When not used,
1368 the front-end should be released by calling disconnect_frontend().</para>
1369</entry>
1370 </row></tbody></tgroup></informaltable>
1371<para>SYNOPSIS
1372</para>
1373<informaltable><tgroup cols="1"><tbody><row><entry
1374 align="char">
1375<para>int connect_frontend(dmx_demux_t&#x22C6; demux,
1376 dmx_frontend_t&#x22C6; frontend);</para>
1377</entry>
1378 </row></tbody></tgroup></informaltable>
1379<para>PARAMETERS
1380</para>
1381<informaltable><tgroup cols="2"><tbody><row><entry
1382 align="char">
1383<para>dmx_demux_t*
1384 demux</para>
1385</entry><entry
1386 align="char">
1387<para>Pointer to the demux API and instance data.</para>
1388</entry>
1389 </row><row><entry
1390 align="char">
1391<para>dmx_frontend_t*
1392 frontend</para>
1393</entry><entry
1394 align="char">
1395<para>Pointer to the front-end instance data.</para>
1396</entry>
1397 </row></tbody></tgroup></informaltable>
1398<para>RETURNS
1399</para>
1400<informaltable><tgroup cols="2"><tbody><row><entry
1401 align="char">
1402<para>0</para>
1403</entry><entry
1404 align="char">
1405<para>The function was completed without errors.</para>
1406</entry>
1407 </row><row><entry
1408 align="char">
1409<para>-EINVAL</para>
1410</entry><entry
1411 align="char">
1412<para>Bad parameter.</para>
1413</entry>
1414 </row><row><entry
1415 align="char">
1416<para>-EBUSY</para>
1417</entry><entry
1418 align="char">
1419<para>The front-end is in use.</para>
1420</entry>
1421 </row></tbody></tgroup></informaltable>
1422
1423</section><section
1424role="subsection"><title>disconnect_frontend()</title>
1425<para>DESCRIPTION
1426</para>
1427<informaltable><tgroup cols="1"><tbody><row><entry
1428 align="char">
1429<para>Disconnects the demux and a front-end previously connected by a
1430 connect_frontend() call.</para>
1431</entry>
1432 </row></tbody></tgroup></informaltable>
1433<para>SYNOPSIS
1434</para>
1435<informaltable><tgroup cols="1"><tbody><row><entry
1436 align="char">
1437<para>int disconnect_frontend(dmx_demux_t&#x22C6; demux);</para>
1438</entry>
1439 </row></tbody></tgroup></informaltable>
1440<para>PARAMETERS
1441</para>
1442<informaltable><tgroup cols="2"><tbody><row><entry
1443 align="char">
1444<para>dmx_demux_t*
1445 demux</para>
1446</entry><entry
1447 align="char">
1448<para>Pointer to the demux API and instance data.</para>
1449</entry>
1450 </row></tbody></tgroup></informaltable>
1451<para>RETURNS
1452</para>
1453<informaltable><tgroup cols="2"><tbody><row><entry
1454 align="char">
1455<para>0</para>
1456</entry><entry
1457 align="char">
1458<para>The function was completed without errors.</para>
1459</entry>
1460 </row><row><entry
1461 align="char">
1462<para>-EINVAL</para>
1463</entry><entry
1464 align="char">
1465<para>Bad parameter.</para>
1466</entry>
1467 </row></tbody></tgroup></informaltable>
1468 </section></section>
1469<section id="demux_callback_api">
1470<title>Demux Callback API</title>
1471<para>This kernel-space API comprises the callback functions that deliver filtered data to the
1472demux client. Unlike the other APIs, these API functions are provided by the client and called
1473from the demux code.
1474</para>
1475<para>The function pointers of this abstract interface are not packed into a structure as in the
1476other demux APIs, because the callback functions are registered and used independent
1477of each other. As an example, it is possible for the API client to provide several
1478callback functions for receiving TS packets and no callbacks for PES packets or
1479sections.
1480</para>
1481<para>The functions that implement the callback API need not be re-entrant: when a demux
1482driver calls one of these functions, the driver is not allowed to call the function again before
1483the original call returns. If a callback is triggered by a hardware interrupt, it is recommended
1484to use the Linux &#8220;bottom half&#8221; mechanism or start a tasklet instead of making the callback
1485function call directly from a hardware interrupt.
1486</para>
1487
1488<section
1489role="subsection"><title>dmx_ts_cb()</title>
1490<para>DESCRIPTION
1491</para>
1492<informaltable><tgroup cols="1"><tbody><row><entry
1493 align="char">
1494<para>This function, provided by the client of the demux API, is called from the
1495 demux code. The function is only called when filtering on this TS feed has
1496 been enabled using the start_filtering() function.</para>
1497</entry>
1498 </row><row><entry
1499 align="char">
1500<para>Any TS packets that match the filter settings are copied to a circular buffer. The
1501 filtered TS packets are delivered to the client using this callback function. The
1502 size of the circular buffer is controlled by the circular_buffer_size parameter
1503 of the set() function in the TS Feed API. It is expected that the buffer1 and
1504 buffer2 callback parameters point to addresses within the circular buffer, but
1505 other implementations are also possible. Note that the called party should not
1506 try to free the memory the buffer1 and buffer2 parameters point to.</para>
1507</entry>
1508 </row><row><entry
1509 align="char">
1510<para>When this function is called, the buffer1 parameter typically points to the
1511 start of the first undelivered TS packet within a circular buffer. The buffer2
1512 buffer parameter is normally NULL, except when the received TS packets have
1513 crossed the last address of the circular buffer and &#8221;wrapped&#8221; to the beginning
1514 of the buffer. In the latter case the buffer1 parameter would contain an address
1515 within the circular buffer, while the buffer2 parameter would contain the first
1516 address of the circular buffer.</para>
1517</entry>
1518 </row><row><entry
1519 align="char">
1520<para>The number of bytes delivered with this function (i.e. buffer1_length +
1521 buffer2_length) is usually equal to the value of callback_length parameter
1522 given in the set() function, with one exception: if a timeout occurs before
1523 receiving callback_length bytes of TS data, any undelivered packets are
1524 immediately delivered to the client by calling this function. The timeout
1525 duration is controlled by the set() function in the TS Feed API.</para>
1526</entry>
1527 </row><row><entry
1528 align="char">
1529<para>If a TS packet is received with errors that could not be fixed by the TS-level
1530 forward error correction (FEC), the Transport_error_indicator flag of the TS
1531 packet header should be set. The TS packet should not be discarded, as
1532 the error can possibly be corrected by a higher layer protocol. If the called
1533 party is slow in processing the callback, it is possible that the circular buffer
1534 eventually fills up. If this happens, the demux driver should discard any TS
1535 packets received while the buffer is full. The error should be indicated to the
1536 client on the next callback by setting the success parameter to the value of
1537 DMX_OVERRUN_ERROR.</para>
1538</entry>
1539 </row><row><entry
1540 align="char">
1541<para>The type of data returned to the callback can be selected by the new
1542 function int (*set_type) (struct dmx_ts_feed_s* feed, int type, dmx_ts_pes_t
1543 pes_type) which is part of the dmx_ts_feed_s struct (also cf. to the
1544 include file ost/demux.h) The type parameter decides if the raw TS packet
1545 (TS_PACKET) or just the payload (TS_PACKET&#8212;TS_PAYLOAD_ONLY)
1546 should be returned. If additionally the TS_DECODER bit is set the stream
1547 will also be sent to the hardware MPEG decoder. In this case, the second
1548 flag decides as what kind of data the stream should be interpreted. The
1549 possible choices are one of DMX_TS_PES_AUDIO, DMX_TS_PES_VIDEO,
1550 DMX_TS_PES_TELETEXT, DMX_TS_PES_SUBTITLE,
1551 DMX_TS_PES_PCR, or DMX_TS_PES_OTHER.</para>
1552</entry>
1553 </row></tbody></tgroup></informaltable>
1554<para>SYNOPSIS
1555</para>
1556<informaltable><tgroup cols="1"><tbody><row><entry
1557 align="char">
1558<para>int dmx_ts_cb(__u8&#x22C6; buffer1, size_t buffer1_length,
1559 __u8&#x22C6; buffer2, size_t buffer2_length, dmx_ts_feed_t&#x22C6;
1560 source, dmx_success_t success);</para>
1561</entry>
1562 </row></tbody></tgroup></informaltable>
1563<para>PARAMETERS
1564</para>
1565<informaltable><tgroup cols="2"><tbody><row><entry
1566 align="char">
1567<para>__u8* buffer1</para>
1568</entry><entry
1569 align="char">
1570<para>Pointer to the start of the filtered TS packets.</para>
1571</entry>
1572 </row><row><entry
1573 align="char">
1574<para>size_t buffer1_length</para>
1575</entry><entry
1576 align="char">
1577<para>Length of the TS data in buffer1.</para>
1578</entry>
1579 </row><row><entry
1580 align="char">
1581<para>__u8* buffer2</para>
1582</entry><entry
1583 align="char">
1584<para>Pointer to the tail of the filtered TS packets, or NULL.</para>
1585</entry>
1586 </row><row><entry
1587 align="char">
1588<para>size_t buffer2_length</para>
1589</entry><entry
1590 align="char">
1591<para>Length of the TS data in buffer2.</para>
1592</entry>
1593 </row><row><entry
1594 align="char">
1595<para>dmx_ts_feed_t*
1596 source</para>
1597</entry><entry
1598 align="char">
1599<para>Indicates which TS feed is the source of the callback.</para>
1600</entry>
1601 </row><row><entry
1602 align="char">
1603<para>dmx_success_t
1604 success</para>
1605</entry><entry
1606 align="char">
1607<para>Indicates if there was an error in TS reception.</para>
1608</entry>
1609 </row></tbody></tgroup></informaltable>
1610<para>RETURNS
1611</para>
1612<informaltable><tgroup cols="2"><tbody><row><entry
1613 align="char">
1614<para>0</para>
1615</entry><entry
1616 align="char">
1617<para>Continue filtering.</para>
1618</entry>
1619 </row><row><entry
1620 align="char">
1621<para>-1</para>
1622</entry><entry
1623 align="char">
1624<para>Stop filtering - has the same effect as a call to
1625 stop_filtering() on the TS Feed API.</para>
1626</entry>
1627 </row></tbody></tgroup></informaltable>
1628
1629</section><section
1630role="subsection"><title>dmx_section_cb()</title>
1631<para>DESCRIPTION
1632</para>
1633<informaltable><tgroup cols="1"><tbody><row><entry
1634 align="char">
1635<para>This function, provided by the client of the demux API, is called from the
1636 demux code. The function is only called when filtering of sections has been
1637 enabled using the function start_filtering() of the section feed API. When the
1638 demux driver has received a complete section that matches at least one section
1639 filter, the client is notified via this callback function. Normally this function is
1640 called for each received section; however, it is also possible to deliver multiple
1641 sections with one callback, for example when the system load is high. If an
1642 error occurs while receiving a section, this function should be called with
1643 the corresponding error type set in the success field, whether or not there is
1644 data to deliver. The Section Feed implementation should maintain a circular
1645 buffer for received sections. However, this is not necessary if the Section Feed
1646 API is implemented as a client of the TS Feed API, because the TS Feed
1647 implementation then buffers the received data. The size of the circular buffer
1648 can be configured using the set() function in the Section Feed API. If there
1649 is no room in the circular buffer when a new section is received, the section
1650 must be discarded. If this happens, the value of the success parameter should
1651 be DMX_OVERRUN_ERROR on the next callback.</para>
1652</entry>
1653 </row></tbody></tgroup></informaltable>
1654<para>SYNOPSIS
1655</para>
1656<informaltable><tgroup cols="1"><tbody><row><entry
1657 align="char">
1658<para>int dmx_section_cb(__u8&#x22C6; buffer1, size_t
1659 buffer1_length, __u8&#x22C6; buffer2, size_t
1660 buffer2_length, dmx_section_filter_t&#x22C6; source,
1661 dmx_success_t success);</para>
1662</entry>
1663 </row></tbody></tgroup></informaltable>
1664<para>PARAMETERS
1665</para>
1666<informaltable><tgroup cols="2"><tbody><row><entry
1667 align="char">
1668<para>__u8* buffer1</para>
1669</entry><entry
1670 align="char">
1671<para>Pointer to the start of the filtered section, e.g. within the
1672 circular buffer of the demux driver.</para>
1673</entry>
1674 </row><row><entry
1675 align="char">
1676<para>size_t buffer1_length</para>
1677</entry><entry
1678 align="char">
1679<para>Length of the filtered section data in buffer1, including
1680 headers and CRC.</para>
1681</entry>
1682 </row><row><entry
1683 align="char">
1684<para>__u8* buffer2</para>
1685</entry><entry
1686 align="char">
1687<para>Pointer to the tail of the filtered section data, or NULL.
1688 Useful to handle the wrapping of a circular buffer.</para>
1689</entry>
1690 </row><row><entry
1691 align="char">
1692<para>size_t buffer2_length</para>
1693</entry><entry
1694 align="char">
1695<para>Length of the filtered section data in buffer2, including
1696 headers and CRC.</para>
1697</entry>
1698 </row><row><entry
1699 align="char">
1700<para>dmx_section_filter_t*
1701 filter</para>
1702</entry><entry
1703 align="char">
1704<para>Indicates the filter that triggered the callback.</para>
1705</entry>
1706 </row><row><entry
1707 align="char">
1708<para>dmx_success_t
1709 success</para>
1710</entry><entry
1711 align="char">
1712<para>Indicates if there was an error in section reception.</para>
1713</entry>
1714 </row></tbody></tgroup></informaltable>
1715<para>RETURNS
1716</para>
1717<informaltable><tgroup cols="2"><tbody><row><entry
1718 align="char">
1719<para>0</para>
1720</entry><entry
1721 align="char">
1722<para>Continue filtering.</para>
1723</entry>
1724 </row><row><entry
1725 align="char">
1726<para>-1</para>
1727</entry><entry
1728 align="char">
1729<para>Stop filtering - has the same effect as a call to
1730 stop_filtering() on the Section Feed API.</para>
1731</entry>
1732 </row></tbody></tgroup></informaltable>
1733 </section></section>
1734<section id="ts_feed_api">
1735<title>TS Feed API</title>
1736<para>A TS feed is typically mapped to a hardware PID filter on the demux chip.
1737Using this API, the client can set the filtering properties to start/stop filtering TS
1738packets on a particular TS feed. The API is defined as an abstract interface of the type
1739dmx_ts_feed_t.
1740</para>
1741<para>The functions that implement the interface should be defined static or module private. The
1742client can get the handle of a TS feed API by calling the function allocate_ts_feed() in the
1743demux API.
1744</para>
1745
1746<section
1747role="subsection"><title>set()</title>
1748<para>DESCRIPTION
1749</para>
1750<informaltable><tgroup cols="1"><tbody><row><entry
1751 align="char">
1752<para>This function sets the parameters of a TS feed. Any filtering in progress on the
1753 TS feed must be stopped before calling this function.</para>
1754</entry>
1755 </row></tbody></tgroup></informaltable>
1756<para>SYNOPSIS
1757</para>
1758<informaltable><tgroup cols="1"><tbody><row><entry
1759 align="char">
1760<para>int set ( dmx_ts_feed_t&#x22C6; feed, __u16 pid, size_t
1761 callback_length, size_t circular_buffer_size, int
1762 descramble, struct timespec timeout);</para>
1763</entry>
1764 </row></tbody></tgroup></informaltable>
1765<para>PARAMETERS
1766</para>
1767<informaltable><tgroup cols="2"><tbody><row><entry
1768 align="char">
1769<para>dmx_ts_feed_t* feed</para>
1770</entry><entry
1771 align="char">
1772<para>Pointer to the TS feed API and instance data.</para>
1773</entry>
1774 </row><row><entry
1775 align="char">
1776<para>__u16 pid</para>
1777</entry><entry
1778 align="char">
1779<para>PID value to filter. Only the TS packets carrying the
1780 specified PID will be passed to the API client.</para>
1781</entry>
1782 </row><row><entry
1783 align="char">
1784<para>size_t
1785 callback_length</para>
1786</entry><entry
1787 align="char">
1788<para>Number of bytes to deliver with each call to the
1789 dmx_ts_cb() callback function. The value of this
1790 parameter should be a multiple of 188.</para>
1791</entry>
1792 </row><row><entry
1793 align="char">
1794<para>size_t
1795 circular_buffer_size</para>
1796</entry><entry
1797 align="char">
1798<para>Size of the circular buffer for the filtered TS packets.</para>
1799</entry>
1800 </row><row><entry
1801 align="char">
1802<para>int descramble</para>
1803</entry><entry
1804 align="char">
1805<para>If non-zero, descramble the filtered TS packets.</para>
1806</entry>
1807 </row><row><entry
1808 align="char">
1809<para>struct timespec
1810 timeout</para>
1811</entry><entry
1812 align="char">
1813<para>Maximum time to wait before delivering received TS
1814 packets to the client.</para>
1815</entry>
1816 </row></tbody></tgroup></informaltable>
1817<para>RETURNS
1818</para>
1819<informaltable><tgroup cols="2"><tbody><row><entry
1820 align="char">
1821<para>0</para>
1822</entry><entry
1823 align="char">
1824<para>The function was completed without errors.</para>
1825</entry>
1826 </row><row><entry
1827 align="char">
1828<para>-ENOMEM</para>
1829</entry><entry
1830 align="char">
1831<para>Not enough memory for the requested buffer size.</para>
1832</entry>
1833 </row><row><entry
1834 align="char">
1835<para>-ENOSYS</para>
1836</entry><entry
1837 align="char">
1838<para>No descrambling facility available for TS.</para>
1839</entry>
1840 </row><row><entry
1841 align="char">
1842<para>-EINVAL</para>
1843</entry><entry
1844 align="char">
1845<para>Bad parameter.</para>
1846</entry>
1847 </row></tbody></tgroup></informaltable>
1848
1849</section><section
1850role="subsection"><title>start_filtering()</title>
1851<para>DESCRIPTION
1852</para>
1853<informaltable><tgroup cols="1"><tbody><row><entry
1854 align="char">
1855<para>Starts filtering TS packets on this TS feed, according to its settings. The PID
1856 value to filter can be set by the API client. All matching TS packets are
1857 delivered asynchronously to the client, using the callback function registered
1858 with allocate_ts_feed().</para>
1859</entry>
1860 </row></tbody></tgroup></informaltable>
1861<para>SYNOPSIS
1862</para>
1863<informaltable><tgroup cols="1"><tbody><row><entry
1864 align="char">
1865<para>int start_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
1866</entry>
1867 </row></tbody></tgroup></informaltable>
1868<para>PARAMETERS
1869</para>
1870<informaltable><tgroup cols="2"><tbody><row><entry
1871 align="char">
1872<para>dmx_ts_feed_t* feed</para>
1873</entry><entry
1874 align="char">
1875<para>Pointer to the TS feed API and instance data.</para>
1876</entry>
1877 </row></tbody></tgroup></informaltable>
1878<para>RETURNS
1879</para>
1880<informaltable><tgroup cols="2"><tbody><row><entry
1881 align="char">
1882<para>0</para>
1883</entry><entry
1884 align="char">
1885<para>The function was completed without errors.</para>
1886</entry>
1887 </row><row><entry
1888 align="char">
1889<para>-EINVAL</para>
1890</entry><entry
1891 align="char">
1892<para>Bad parameter.</para>
1893</entry>
1894 </row></tbody></tgroup></informaltable>
1895
1896</section><section
1897role="subsection"><title>stop_filtering()</title>
1898<para>DESCRIPTION
1899</para>
1900<informaltable><tgroup cols="1"><tbody><row><entry
1901 align="char">
1902<para>Stops filtering TS packets on this TS feed.</para>
1903</entry>
1904 </row></tbody></tgroup></informaltable>
1905<para>SYNOPSIS
1906</para>
1907<informaltable><tgroup cols="1"><tbody><row><entry
1908 align="char">
1909<para>int stop_filtering(dmx_ts_feed_t&#x22C6; feed);</para>
1910</entry>
1911 </row></tbody></tgroup></informaltable>
1912<para>PARAMETERS
1913</para>
1914<informaltable><tgroup cols="2"><tbody><row><entry
1915 align="char">
1916<para>dmx_ts_feed_t* feed</para>
1917</entry><entry
1918 align="char">
1919<para>Pointer to the TS feed API and instance data.</para>
1920</entry>
1921 </row></tbody></tgroup></informaltable>
1922<para>RETURNS
1923</para>
1924<informaltable><tgroup cols="2"><tbody><row><entry
1925 align="char">
1926<para>0</para>
1927</entry><entry
1928 align="char">
1929<para>The function was completed without errors.</para>
1930</entry>
1931 </row><row><entry
1932 align="char">
1933<para>-EINVAL</para>
1934</entry><entry
1935 align="char">
1936<para>Bad parameter.</para>
1937</entry>
1938 </row></tbody></tgroup></informaltable>
1939 </section></section>
1940<section id="section_feed_api">
1941<title>Section Feed API</title>
1942<para>A section feed is a resource consisting of a PID filter and a set of section filters. Using this
1943API, the client can set the properties of a section feed and to start/stop filtering. The API is
1944defined as an abstract interface of the type dmx_section_feed_t. The functions that implement
1945the interface should be defined static or module private. The client can get the handle of
1946a section feed API by calling the function allocate_section_feed() in the demux
1947API.
1948</para>
1949<para>On demux platforms that provide section filtering in hardware, the Section Feed API
1950implementation provides a software wrapper for the demux hardware. Other platforms may
1951support only PID filtering in hardware, requiring that TS packets are converted to sections in
1952software. In the latter case the Section Feed API implementation can be a client of the TS
1953Feed API.
1954</para>
1955
1956</section>
1957<section id="kdapi_set">
1958<title>set()</title>
1959<para>DESCRIPTION
1960</para>
1961<informaltable><tgroup cols="1"><tbody><row><entry
1962 align="char">
1963<para>This function sets the parameters of a section feed. Any filtering in progress on
1964 the section feed must be stopped before calling this function. If descrambling
1965 is enabled, the payload_scrambling_control and address_scrambling_control
1966 fields of received DVB datagram sections should be observed. If either one is
1967 non-zero, the section should be descrambled either in hardware or using the
1968 functions descramble_mac_address() and descramble_section_payload() of the
1969 demux API. Note that according to the MPEG-2 Systems specification, only
1970 the payloads of private sections can be scrambled while the rest of the section
1971 data must be sent in the clear.</para>
1972</entry>
1973 </row></tbody></tgroup></informaltable>
1974<para>SYNOPSIS
1975</para>
1976<informaltable><tgroup cols="1"><tbody><row><entry
1977 align="char">
1978<para>int set(dmx_section_feed_t&#x22C6; feed, __u16 pid, size_t
1979 circular_buffer_size, int descramble, int
1980 check_crc);</para>
1981</entry>
1982 </row></tbody></tgroup></informaltable>
1983<para>PARAMETERS
1984</para>
1985<informaltable><tgroup cols="2"><tbody><row><entry
1986 align="char">
1987<para>dmx_section_feed_t*
1988 feed</para>
1989</entry><entry
1990 align="char">
1991<para>Pointer to the section feed API and instance data.</para>
1992</entry>
1993 </row><row><entry
1994 align="char">
1995<para>__u16 pid</para>
1996</entry><entry
1997 align="char">
1998<para>PID value to filter; only the TS packets carrying the
1999 specified PID will be accepted.</para>
2000</entry>
2001 </row><row><entry
2002 align="char">
2003<para>size_t
2004 circular_buffer_size</para>
2005</entry><entry
2006 align="char">
2007<para>Size of the circular buffer for filtered sections.</para>
2008</entry>
2009 </row><row><entry
2010 align="char">
2011<para>int descramble</para>
2012</entry><entry
2013 align="char">
2014<para>If non-zero, descramble any sections that are scrambled.</para>
2015</entry>
2016 </row><row><entry
2017 align="char">
2018<para>int check_crc</para>
2019</entry><entry
2020 align="char">
2021<para>If non-zero, check the CRC values of filtered sections.</para>
2022</entry>
2023 </row></tbody></tgroup></informaltable>
2024<para>RETURNS
2025</para>
2026<informaltable><tgroup cols="2"><tbody><row><entry
2027 align="char">
2028<para>0</para>
2029</entry><entry
2030 align="char">
2031<para>The function was completed without errors.</para>
2032</entry>
2033 </row><row><entry
2034 align="char">
2035<para>-ENOMEM</para>
2036</entry><entry
2037 align="char">
2038<para>Not enough memory for the requested buffer size.</para>
2039</entry>
2040 </row><row><entry
2041 align="char">
2042<para>-ENOSYS</para>
2043</entry><entry
2044 align="char">
2045<para>No descrambling facility available for sections.</para>
2046</entry>
2047 </row><row><entry
2048 align="char">
2049<para>-EINVAL</para>
2050</entry><entry
2051 align="char">
2052<para>Bad parameters.</para>
2053</entry>
2054 </row></tbody></tgroup></informaltable>
2055
2056</section><section
2057role="subsection"><title>allocate_filter()</title>
2058<para>DESCRIPTION
2059</para>
2060<informaltable><tgroup cols="1"><tbody><row><entry
2061 align="char">
2062<para>This function is used to allocate a section filter on the demux. It should only be
2063 called when no filtering is in progress on this section feed. If a filter cannot be
2064 allocated, the function fails with -ENOSPC. See in section ?? for the format of
2065 the section filter.</para>
2066</entry>
2067 </row><row><entry
2068 align="char">
2069<para>The bitfields filter_mask and filter_value should only be modified when no
2070 filtering is in progress on this section feed. filter_mask controls which bits of
2071 filter_value are compared with the section headers/payload. On a binary value
2072 of 1 in filter_mask, the corresponding bits are compared. The filter only accepts
2073 sections that are equal to filter_value in all the tested bit positions. Any changes
2074 to the values of filter_mask and filter_value are guaranteed to take effect only
2075 when the start_filtering() function is called next time. The parent pointer in
2076 the struct is initialized by the API implementation to the value of the feed
2077 parameter. The priv pointer is not used by the API implementation, and can
2078 thus be freely utilized by the caller of this function. Any data pointed to by the
2079 priv pointer is available to the recipient of the dmx_section_cb() function call.</para>
2080</entry>
2081 </row><row><entry
2082 align="char">
2083<para>While the maximum section filter length (DMX_MAX_FILTER_SIZE) is
2084 currently set at 16 bytes, hardware filters of that size are not available on all
2085 platforms. Therefore, section filtering will often take place first in hardware,
2086 followed by filtering in software for the header bytes that were not covered
2087 by a hardware filter. The filter_mask field can be checked to determine how
2088 many bytes of the section filter are actually used, and if the hardware filter will
2089 suffice. Additionally, software-only section filters can optionally be allocated
2090 to clients when all hardware section filters are in use. Note that on most demux
2091 hardware it is not possible to filter on the section_length field of the section
2092 header &#8211; thus this field is ignored, even though it is included in filter_value and
2093 filter_mask fields.</para>
2094</entry>
2095 </row></tbody></tgroup></informaltable>
2096<para>SYNOPSIS
2097</para>
2098<informaltable><tgroup cols="1"><tbody><row><entry
2099 align="char">
2100<para>int allocate_filter(dmx_section_feed_t&#x22C6; feed,
2101 dmx_section_filter_t&#x22C6;&#x22C6; filter);</para>
2102</entry>
2103 </row></tbody></tgroup></informaltable>
2104<para>PARAMETERS
2105</para>
2106<informaltable><tgroup cols="2"><tbody><row><entry
2107 align="char">
2108<para>dmx_section_feed_t*
2109 feed</para>
2110</entry><entry
2111 align="char">
2112<para>Pointer to the section feed API and instance data.</para>
2113</entry>
2114 </row><row><entry
2115 align="char">
2116<para>dmx_section_filter_t**
2117 filter</para>
2118</entry><entry
2119 align="char">
2120<para>Pointer to the allocated filter.</para>
2121</entry>
2122 </row></tbody></tgroup></informaltable>
2123<para>RETURNS
2124</para>
2125<informaltable><tgroup cols="2"><tbody><row><entry
2126 align="char">
2127<para>0</para>
2128</entry><entry
2129 align="char">
2130<para>The function was completed without errors.</para>
2131</entry>
2132 </row><row><entry
2133 align="char">
2134<para>-ENOSPC</para>
2135</entry><entry
2136 align="char">
2137<para>No filters of given type and length available.</para>
2138</entry>
2139 </row><row><entry
2140 align="char">
2141<para>-EINVAL</para>
2142</entry><entry
2143 align="char">
2144<para>Bad parameters.</para>
2145</entry>
2146 </row></tbody></tgroup></informaltable>
2147
2148</section><section
2149role="subsection"><title>release_filter()</title>
2150<para>DESCRIPTION
2151</para>
2152<informaltable><tgroup cols="1"><tbody><row><entry
2153 align="char">
2154<para>This function releases all the resources of a previously allocated section filter.
2155 The function should not be called while filtering is in progress on this section
2156 feed. After calling this function, the caller should not try to dereference the
2157 filter pointer.</para>
2158</entry>
2159 </row></tbody></tgroup></informaltable>
2160<para>SYNOPSIS
2161</para>
2162<informaltable><tgroup cols="1"><tbody><row><entry
2163 align="char">
2164<para>int release_filter ( dmx_section_feed_t&#x22C6; feed,
2165 dmx_section_filter_t&#x22C6; filter);</para>
2166</entry>
2167 </row></tbody></tgroup></informaltable>
2168<para>PARAMETERS
2169</para>
2170<informaltable><tgroup cols="2"><tbody><row><entry
2171 align="char">
2172<para>dmx_section_feed_t*
2173 feed</para>
2174</entry><entry
2175 align="char">
2176<para>Pointer to the section feed API and instance data.</para>
2177</entry>
2178 </row><row><entry
2179 align="char">
2180<para>dmx_section_filter_t*
2181 filter</para>
2182</entry><entry
2183 align="char">
2184<para>I/O Pointer to the instance data of a section filter.</para>
2185</entry>
2186 </row></tbody></tgroup></informaltable>
2187<para>RETURNS
2188</para>
2189<informaltable><tgroup cols="2"><tbody><row><entry
2190 align="char">
2191<para>0</para>
2192</entry><entry
2193 align="char">
2194<para>The function was completed without errors.</para>
2195</entry>
2196 </row><row><entry
2197 align="char">
2198<para>-ENODEV</para>
2199</entry><entry
2200 align="char">
2201<para>No such filter allocated.</para>
2202</entry>
2203 </row><row><entry
2204 align="char">
2205<para>-EINVAL</para>
2206</entry><entry
2207 align="char">
2208<para>Bad parameter.</para>
2209</entry>
2210 </row></tbody></tgroup></informaltable>
2211
2212</section><section
2213role="subsection"><title>start_filtering()</title>
2214<para>DESCRIPTION
2215</para>
2216<informaltable><tgroup cols="1"><tbody><row><entry
2217 align="char">
2218<para>Starts filtering sections on this section feed, according to its settings. Sections
2219 are first filtered based on their PID and then matched with the section
2220 filters allocated for this feed. If the section matches the PID filter and
2221 at least one section filter, it is delivered to the API client. The section
2222 is delivered asynchronously using the callback function registered with
2223 allocate_section_feed().</para>
2224</entry>
2225 </row></tbody></tgroup></informaltable>
2226<para>SYNOPSIS
2227</para>
2228<informaltable><tgroup cols="1"><tbody><row><entry
2229 align="char">
2230<para>int start_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
2231</entry>
2232 </row></tbody></tgroup></informaltable>
2233<para>PARAMETERS
2234</para>
2235<informaltable><tgroup cols="2"><tbody><row><entry
2236 align="char">
2237<para>dmx_section_feed_t*
2238 feed</para>
2239</entry><entry
2240 align="char">
2241<para>Pointer to the section feed API and instance data.</para>
2242</entry>
2243 </row></tbody></tgroup></informaltable>
2244<para>RETURNS
2245</para>
2246<informaltable><tgroup cols="2"><tbody><row><entry
2247 align="char">
2248<para>0</para>
2249</entry><entry
2250 align="char">
2251<para>The function was completed without errors.</para>
2252</entry>
2253 </row><row><entry
2254 align="char">
2255<para>-EINVAL</para>
2256</entry><entry
2257 align="char">
2258<para>Bad parameter.</para>
2259</entry>
2260 </row></tbody></tgroup></informaltable>
2261
2262</section><section
2263role="subsection"><title>stop_filtering()</title>
2264<para>DESCRIPTION
2265</para>
2266<informaltable><tgroup cols="1"><tbody><row><entry
2267 align="char">
2268<para>Stops filtering sections on this section feed. Note that any changes to the
2269 filtering parameters (filter_value, filter_mask, etc.) should only be made when
2270 filtering is stopped.</para>
2271</entry>
2272 </row></tbody></tgroup></informaltable>
2273<para>SYNOPSIS
2274</para>
2275<informaltable><tgroup cols="1"><tbody><row><entry
2276 align="char">
2277<para>int stop_filtering ( dmx_section_feed_t&#x22C6; feed );</para>
2278</entry>
2279 </row></tbody></tgroup></informaltable>
2280<para>PARAMETERS
2281</para>
2282<informaltable><tgroup cols="2"><tbody><row><entry
2283 align="char">
2284<para>dmx_section_feed_t*
2285 feed</para>
2286</entry><entry
2287 align="char">
2288<para>Pointer to the section feed API and instance data.</para>
2289</entry>
2290 </row></tbody></tgroup></informaltable>
2291<para>RETURNS
2292</para>
2293<informaltable><tgroup cols="2"><tbody><row><entry
2294 align="char">
2295<para>0</para>
2296</entry><entry
2297 align="char">
2298<para>The function was completed without errors.</para>
2299</entry>
2300 </row><row><entry
2301 align="char">
2302<para>-EINVAL</para>
2303</entry><entry
2304 align="char">
2305<para>Bad parameter.</para>
2306</entry>
2307 </row></tbody></tgroup></informaltable>
2308
2309</section>
diff --git a/Documentation/DocBook/media/dvb/net.xml b/Documentation/DocBook/media/dvb/net.xml
new file mode 100644
index 000000000000..94e388d94c0d
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/net.xml
@@ -0,0 +1,12 @@
1<title>DVB Network API</title>
2<para>The DVB net device enables feeding of MPE (multi protocol encapsulation) packets
3received via DVB into the Linux network protocol stack, e.g. for internet via satellite
4applications. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/net0</emphasis>. Data types and
5and ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/net.h</emphasis> in your
6application.
7</para>
8<section id="dvb_net_types">
9<title>DVB Net Data Types</title>
10<para>To be written&#x2026;
11</para>
12</section>
diff --git a/Documentation/DocBook/media/dvb/video.xml b/Documentation/DocBook/media/dvb/video.xml
new file mode 100644
index 000000000000..7bb287e67c8e
--- /dev/null
+++ b/Documentation/DocBook/media/dvb/video.xml
@@ -0,0 +1,1971 @@
1<title>DVB Video Device</title>
2<para>The DVB video device controls the MPEG2 video decoder of the DVB hardware. It
3can be accessed through <emphasis role="tt">/dev/dvb/adapter0/video0</emphasis>. Data types and and
4ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your
5application.
6</para>
7<para>Note that the DVB video device only controls decoding of the MPEG video stream, not
8its presentation on the TV or computer screen. On PCs this is typically handled by an
9associated video4linux device, e.g. <emphasis role="tt">/dev/video</emphasis>, which allows scaling and defining output
10windows.
11</para>
12<para>Some DVB cards don&#8217;t have their own MPEG decoder, which results in the omission of
13the audio and video device as well as the video4linux device.
14</para>
15<para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only
16supported on some MPEG decoders made for DVD playback.
17</para>
18<section id="video_types">
19<title>Video Data Types</title>
20
21<section id="video_format_t">
22<title>video_format_t</title>
23<para>The <emphasis role="tt">video_format_t</emphasis> data type defined by
24</para>
25<programlisting>
26 typedef enum {
27 VIDEO_FORMAT_4_3,
28 VIDEO_FORMAT_16_9
29 } video_format_t;
30</programlisting>
31<para>is used in the VIDEO_SET_FORMAT function (??) to tell the driver which aspect ratio
32the output hardware (e.g. TV) has. It is also used in the data structures video_status
33(??) returned by VIDEO_GET_STATUS (??) and video_event (??) returned by
34VIDEO_GET_EVENT (??) which report about the display format of the current video
35stream.
36</para>
37</section>
38
39<section id="video_display_format_t">
40<title>video_display_format_t</title>
41<para>In case the display format of the video stream and of the display hardware differ the
42application has to specify how to handle the cropping of the picture. This can be done using
43the VIDEO_SET_DISPLAY_FORMAT call (??) which accepts
44</para>
45<programlisting>
46 typedef enum {
47 VIDEO_PAN_SCAN,
48 VIDEO_LETTER_BOX,
49 VIDEO_CENTER_CUT_OUT
50 } video_display_format_t;
51</programlisting>
52<para>as argument.
53</para>
54</section>
55
56<section id="video_stream_source">
57<title>video stream source</title>
58<para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take
59the following values, depending on whether we are replaying from an internal (demuxer) or
60external (user write) source.
61</para>
62<programlisting>
63 typedef enum {
64 VIDEO_SOURCE_DEMUX,
65 VIDEO_SOURCE_MEMORY
66 } video_stream_source_t;
67</programlisting>
68<para>VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the frontend or the
69DVR device) as the source of the video stream. If VIDEO_SOURCE_MEMORY
70is selected the stream comes from the application through the <emphasis role="tt">write()</emphasis> system
71call.
72</para>
73</section>
74
75<section id="video_play_state">
76<title>video play state</title>
77<para>The following values can be returned by the VIDEO_GET_STATUS call representing the
78state of video playback.
79</para>
80<programlisting>
81 typedef enum {
82 VIDEO_STOPPED,
83 VIDEO_PLAYING,
84 VIDEO_FREEZED
85 } video_play_state_t;
86</programlisting>
87</section>
88
89<section id="video_event">
90<title>struct video_event</title>
91<para>The following is the structure of a video event as it is returned by the VIDEO_GET_EVENT
92call.
93</para>
94<programlisting>
95 struct video_event {
96 int32_t type;
97 time_t timestamp;
98 union {
99 video_format_t video_format;
100 } u;
101 };
102</programlisting>
103</section>
104
105<section id="video_status">
106<title>struct video_status</title>
107<para>The VIDEO_GET_STATUS call returns the following structure informing about various
108states of the playback operation.
109</para>
110<programlisting>
111 struct video_status {
112 boolean video_blank;
113 video_play_state_t play_state;
114 video_stream_source_t stream_source;
115 video_format_t video_format;
116 video_displayformat_t display_format;
117 };
118</programlisting>
119<para>If video_blank is set video will be blanked out if the channel is changed or if playback is
120stopped. Otherwise, the last picture will be displayed. play_state indicates if the video is
121currently frozen, stopped, or being played back. The stream_source corresponds to the seleted
122source for the video stream. It can come either from the demultiplexer or from memory.
123The video_format indicates the aspect ratio (one of 4:3 or 16:9) of the currently
124played video stream. Finally, display_format corresponds to the selected cropping
125mode in case the source video format is not the same as the format of the output
126device.
127</para>
128</section>
129
130<section id="video_still_picture">
131<title>struct video_still_picture</title>
132<para>An I-frame displayed via the VIDEO_STILLPICTURE call is passed on within the
133following structure.
134</para>
135<programlisting>
136 /&#x22C6; pointer to and size of a single iframe in memory &#x22C6;/
137 struct video_still_picture {
138 char &#x22C6;iFrame;
139 int32_t size;
140 };
141</programlisting>
142</section>
143
144<section id="video_caps">
145<title>video capabilities</title>
146<para>A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the following
147bits set according to the hardwares capabilities.
148</para>
149<programlisting>
150 /&#x22C6; bit definitions for capabilities: &#x22C6;/
151 /&#x22C6; can the hardware decode MPEG1 and/or MPEG2? &#x22C6;/
152 #define VIDEO_CAP_MPEG1 1
153 #define VIDEO_CAP_MPEG2 2
154 /&#x22C6; can you send a system and/or program stream to video device?
155 (you still have to open the video and the audio device but only
156 send the stream to the video device) &#x22C6;/
157 #define VIDEO_CAP_SYS 4
158 #define VIDEO_CAP_PROG 8
159 /&#x22C6; can the driver also handle SPU, NAVI and CSS encoded data?
160 (CSS API is not present yet) &#x22C6;/
161 #define VIDEO_CAP_SPU 16
162 #define VIDEO_CAP_NAVI 32
163 #define VIDEO_CAP_CSS 64
164</programlisting>
165</section>
166
167<section id="video_system">
168<title>video system</title>
169<para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The
170following system types can be set:
171</para>
172<programlisting>
173 typedef enum {
174 VIDEO_SYSTEM_PAL,
175 VIDEO_SYSTEM_NTSC,
176 VIDEO_SYSTEM_PALN,
177 VIDEO_SYSTEM_PALNc,
178 VIDEO_SYSTEM_PALM,
179 VIDEO_SYSTEM_NTSC60,
180 VIDEO_SYSTEM_PAL60,
181 VIDEO_SYSTEM_PALM60
182 } video_system_t;
183</programlisting>
184</section>
185
186<section id="video_highlight">
187<title>struct video_highlight</title>
188<para>Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight information. The
189call expects the following format for that information:
190</para>
191<programlisting>
192 typedef
193 struct video_highlight {
194 boolean active; /&#x22C6; 1=show highlight, 0=hide highlight &#x22C6;/
195 uint8_t contrast1; /&#x22C6; 7- 4 Pattern pixel contrast &#x22C6;/
196 /&#x22C6; 3- 0 Background pixel contrast &#x22C6;/
197 uint8_t contrast2; /&#x22C6; 7- 4 Emphasis pixel-2 contrast &#x22C6;/
198 /&#x22C6; 3- 0 Emphasis pixel-1 contrast &#x22C6;/
199 uint8_t color1; /&#x22C6; 7- 4 Pattern pixel color &#x22C6;/
200 /&#x22C6; 3- 0 Background pixel color &#x22C6;/
201 uint8_t color2; /&#x22C6; 7- 4 Emphasis pixel-2 color &#x22C6;/
202 /&#x22C6; 3- 0 Emphasis pixel-1 color &#x22C6;/
203 uint32_t ypos; /&#x22C6; 23-22 auto action mode &#x22C6;/
204 /&#x22C6; 21-12 start y &#x22C6;/
205 /&#x22C6; 9- 0 end y &#x22C6;/
206 uint32_t xpos; /&#x22C6; 23-22 button color number &#x22C6;/
207 /&#x22C6; 21-12 start x &#x22C6;/
208 /&#x22C6; 9- 0 end x &#x22C6;/
209 } video_highlight_t;
210</programlisting>
211
212</section>
213<section id="video_spu">
214<title>video SPU</title>
215<para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the
216following format:
217</para>
218<programlisting>
219 typedef
220 struct video_spu {
221 boolean active;
222 int stream_id;
223 } video_spu_t;
224</programlisting>
225
226</section>
227<section id="video_spu_palette">
228<title>video SPU palette</title>
229<para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE:
230</para>
231<programlisting>
232 typedef
233 struct video_spu_palette{
234 int length;
235 uint8_t &#x22C6;palette;
236 } video_spu_palette_t;
237</programlisting>
238
239</section>
240<section id="video_navi_pack">
241<title>video NAVI pack</title>
242<para>In order to get the navigational data the following structure has to be passed to the ioctl
243VIDEO_GET_NAVI:
244</para>
245<programlisting>
246 typedef
247 struct video_navi_pack{
248 int length; /&#x22C6; 0 ... 1024 &#x22C6;/
249 uint8_t data[1024];
250 } video_navi_pack_t;
251</programlisting>
252</section>
253
254
255<section id="video_attributes">
256<title>video attributes</title>
257<para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES:
258</para>
259<programlisting>
260 typedef uint16_t video_attributes_t;
261 /&#x22C6; bits: descr. &#x22C6;/
262 /&#x22C6; 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) &#x22C6;/
263 /&#x22C6; 13-12 TV system (0=525/60, 1=625/50) &#x22C6;/
264 /&#x22C6; 11-10 Aspect ratio (0=4:3, 3=16:9) &#x22C6;/
265 /&#x22C6; 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca &#x22C6;/
266 /&#x22C6; 7 line 21-1 data present in GOP (1=yes, 0=no) &#x22C6;/
267 /&#x22C6; 6 line 21-2 data present in GOP (1=yes, 0=no) &#x22C6;/
268 /&#x22C6; 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 &#x22C6;/
269 /&#x22C6; 2 source letterboxed (1=yes, 0=no) &#x22C6;/
270 /&#x22C6; 0 film/camera mode (0=camera, 1=film (625/50 only)) &#x22C6;/
271</programlisting>
272</section></section>
273
274
275<section id="video_function_calls">
276<title>Video Function Calls</title>
277
278
279<section id="video_fopen">
280<title>open()</title>
281<para>DESCRIPTION
282</para>
283<informaltable><tgroup cols="1"><tbody><row><entry
284 align="char">
285<para>This system call opens a named video device (e.g. /dev/dvb/adapter0/video0)
286 for subsequent use.</para>
287<para>When an open() call has succeeded, the device will be ready for use.
288 The significance of blocking or non-blocking mode is described in the
289 documentation for functions where there is a difference. It does not affect the
290 semantics of the open() call itself. A device opened in blocking mode can later
291 be put into non-blocking mode (and vice versa) using the F_SETFL command
292 of the fcntl system call. This is a standard system call, documented in the Linux
293 manual page for fcntl. Only one user can open the Video Device in O_RDWR
294 mode. All other attempts to open the device in this mode will fail, and an
295 error-code will be returned. If the Video Device is opened in O_RDONLY
296 mode, the only ioctl call that can be used is VIDEO_GET_STATUS. All other
297 call will return an error code.</para>
298</entry>
299 </row></tbody></tgroup></informaltable>
300
301<para>SYNOPSIS
302</para>
303<informaltable><tgroup cols="1"><tbody><row><entry
304 align="char">
305<para>int open(const char &#x22C6;deviceName, int flags);</para>
306</entry>
307 </row></tbody></tgroup></informaltable>
308<para>PARAMETERS
309</para>
310<informaltable><tgroup cols="2"><tbody><row><entry
311 align="char">
312<para>const char
313 *deviceName</para>
314</entry><entry
315 align="char">
316<para>Name of specific video device.</para>
317</entry>
318 </row><row><entry
319 align="char">
320<para>int flags</para>
321</entry><entry
322 align="char">
323<para>A bit-wise OR of the following flags:</para>
324</entry>
325 </row><row><entry
326 align="char">
327</entry><entry
328 align="char">
329<para>O_RDONLY read-only access</para>
330</entry>
331 </row><row><entry
332 align="char">
333</entry><entry
334 align="char">
335<para>O_RDWR read/write access</para>
336</entry>
337 </row><row><entry
338 align="char">
339</entry><entry
340 align="char">
341<para>O_NONBLOCK open in non-blocking mode</para>
342</entry>
343 </row><row><entry
344 align="char">
345</entry><entry
346 align="char">
347<para>(blocking mode is the default)</para>
348</entry>
349 </row></tbody></tgroup></informaltable>
350<para>ERRORS
351</para>
352<informaltable><tgroup cols="2"><tbody><row><entry
353 align="char">
354<para>ENODEV</para>
355</entry><entry
356 align="char">
357<para>Device driver not loaded/available.</para>
358</entry>
359 </row><row><entry
360 align="char">
361<para>EINTERNAL</para>
362</entry><entry
363 align="char">
364<para>Internal error.</para>
365</entry>
366 </row><row><entry
367 align="char">
368<para>EBUSY</para>
369</entry><entry
370 align="char">
371<para>Device or resource busy.</para>
372</entry>
373 </row><row><entry
374 align="char">
375<para>EINVAL</para>
376</entry><entry
377 align="char">
378<para>Invalid argument.</para>
379</entry>
380 </row></tbody></tgroup></informaltable>
381
382</section>
383<section id="video_fclose">
384<title>close()</title>
385<para>DESCRIPTION
386</para>
387<informaltable><tgroup cols="1"><tbody><row><entry
388 align="char">
389<para>This system call closes a previously opened video device.</para>
390</entry>
391 </row></tbody></tgroup></informaltable>
392<para>SYNOPSIS
393</para>
394<informaltable><tgroup cols="1"><tbody><row><entry
395 align="char">
396<para>int close(int fd);</para>
397</entry>
398 </row></tbody></tgroup></informaltable>
399<para>PARAMETERS
400</para>
401<informaltable><tgroup cols="2"><tbody><row><entry
402 align="char">
403<para>int fd</para>
404</entry><entry
405 align="char">
406<para>File descriptor returned by a previous call to open().</para>
407</entry>
408 </row></tbody></tgroup></informaltable>
409<para>ERRORS
410</para>
411<informaltable><tgroup cols="2"><tbody><row><entry
412 align="char">
413<para>EBADF</para>
414</entry><entry
415 align="char">
416<para>fd is not a valid open file descriptor.</para>
417</entry>
418 </row></tbody></tgroup></informaltable>
419
420</section>
421<section id="video_fwrite">
422<title>write()</title>
423<para>DESCRIPTION
424</para>
425<informaltable><tgroup cols="1"><tbody><row><entry
426 align="char">
427<para>This system call can only be used if VIDEO_SOURCE_MEMORY is selected
428 in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in
429 PES format, unless the capability allows other formats. If O_NONBLOCK is
430 not specified the function will block until buffer space is available. The amount
431 of data to be transferred is implied by count.</para>
432</entry>
433 </row></tbody></tgroup></informaltable>
434<para>SYNOPSIS
435</para>
436<informaltable><tgroup cols="1"><tbody><row><entry
437 align="char">
438<para>size_t write(int fd, const void &#x22C6;buf, size_t count);</para>
439</entry>
440 </row></tbody></tgroup></informaltable>
441<para>PARAMETERS
442</para>
443<informaltable><tgroup cols="2"><tbody><row><entry
444 align="char">
445<para>int fd</para>
446</entry><entry
447 align="char">
448<para>File descriptor returned by a previous call to open().</para>
449</entry>
450 </row><row><entry
451 align="char">
452<para>void *buf</para>
453</entry><entry
454 align="char">
455<para>Pointer to the buffer containing the PES data.</para>
456</entry>
457 </row><row><entry
458 align="char">
459<para>size_t count</para>
460</entry><entry
461 align="char">
462<para>Size of buf.</para>
463</entry>
464 </row></tbody></tgroup></informaltable>
465<para>ERRORS
466</para>
467<informaltable><tgroup cols="2"><tbody><row><entry
468 align="char">
469<para>EPERM</para>
470</entry><entry
471 align="char">
472<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
473</entry>
474 </row><row><entry
475 align="char">
476<para>ENOMEM</para>
477</entry><entry
478 align="char">
479<para>Attempted to write more data than the internal buffer can
480 hold.</para>
481</entry>
482 </row><row><entry
483 align="char">
484<para>EBADF</para>
485</entry><entry
486 align="char">
487<para>fd is not a valid open file descriptor.</para>
488</entry>
489 </row></tbody></tgroup></informaltable>
490
491</section><section
492role="subsection"><title>VIDEO_STOP</title>
493<para>DESCRIPTION
494</para>
495<informaltable><tgroup cols="1"><tbody><row><entry
496 align="char">
497<para>This ioctl call asks the Video Device to stop playing the current stream.
498 Depending on the input parameter, the screen can be blanked out or displaying
499 the last decoded frame.</para>
500</entry>
501 </row></tbody></tgroup></informaltable>
502<para>SYNOPSIS
503</para>
504<informaltable><tgroup cols="1"><tbody><row><entry
505 align="char">
506<para>int ioctl(fd, int request = VIDEO_STOP, boolean
507 mode);</para>
508</entry>
509 </row></tbody></tgroup></informaltable>
510<para>PARAMETERS
511</para>
512<informaltable><tgroup cols="2"><tbody><row><entry
513 align="char">
514<para>int fd</para>
515</entry><entry
516 align="char">
517<para>File descriptor returned by a previous call to open().</para>
518</entry>
519 </row><row><entry
520 align="char">
521<para>int request</para>
522</entry><entry
523 align="char">
524<para>Equals VIDEO_STOP for this command.</para>
525</entry>
526 </row><row><entry
527 align="char">
528<para>Boolean mode</para>
529</entry><entry
530 align="char">
531<para>Indicates how the screen shall be handled.</para>
532</entry>
533 </row><row><entry
534 align="char">
535</entry><entry
536 align="char">
537<para>TRUE: Blank screen when stop.</para>
538</entry>
539 </row><row><entry
540 align="char">
541</entry><entry
542 align="char">
543<para>FALSE: Show last decoded frame.</para>
544</entry>
545 </row></tbody></tgroup></informaltable>
546<para>ERRORS
547</para>
548<informaltable><tgroup cols="2"><tbody><row><entry
549 align="char">
550<para>EBADF</para>
551</entry><entry
552 align="char">
553<para>fd is not a valid open file descriptor</para>
554</entry>
555 </row><row><entry
556 align="char">
557<para>EINTERNAL</para>
558</entry><entry
559 align="char">
560<para>Internal error, possibly in the communication with the
561 DVB subsystem.</para>
562</entry>
563 </row></tbody></tgroup></informaltable>
564
565</section><section
566role="subsection"><title>VIDEO_PLAY</title>
567<para>DESCRIPTION
568</para>
569<informaltable><tgroup cols="1"><tbody><row><entry
570 align="char">
571<para>This ioctl call asks the Video Device to start playing a video stream from the
572 selected source.</para>
573</entry>
574 </row></tbody></tgroup></informaltable>
575<para>SYNOPSIS
576</para>
577<informaltable><tgroup cols="1"><tbody><row><entry
578 align="char">
579<para>int ioctl(fd, int request = VIDEO_PLAY);</para>
580</entry>
581 </row></tbody></tgroup></informaltable>
582<para>PARAMETERS
583</para>
584<informaltable><tgroup cols="2"><tbody><row><entry
585 align="char">
586<para>int fd</para>
587</entry><entry
588 align="char">
589<para>File descriptor returned by a previous call to open().</para>
590</entry>
591 </row><row><entry
592 align="char">
593<para>int request</para>
594</entry><entry
595 align="char">
596<para>Equals VIDEO_PLAY for this command.</para>
597</entry>
598 </row></tbody></tgroup></informaltable>
599<para>ERRORS
600</para>
601<informaltable><tgroup cols="2"><tbody><row><entry
602 align="char">
603<para>EBADF</para>
604</entry><entry
605 align="char">
606<para>fd is not a valid open file descriptor</para>
607</entry>
608 </row><row><entry
609 align="char">
610<para>EINTERNAL</para>
611</entry><entry
612 align="char">
613<para>Internal error, possibly in the communication with the
614 DVB subsystem.</para>
615</entry>
616 </row></tbody></tgroup></informaltable>
617
618</section><section
619role="subsection"><title>VIDEO_FREEZE</title>
620<para>DESCRIPTION
621</para>
622<informaltable><tgroup cols="1"><tbody><row><entry
623 align="char">
624<para>This ioctl call suspends the live video stream being played. Decoding
625 and playing are frozen. It is then possible to restart the decoding
626 and playing process of the video stream using the VIDEO_CONTINUE
627 command. If VIDEO_SOURCE_MEMORY is selected in the ioctl call
628 VIDEO_SELECT_SOURCE, the DVB subsystem will not decode any more
629 data until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed.</para>
630</entry>
631 </row></tbody></tgroup></informaltable>
632<para>SYNOPSIS
633</para>
634<informaltable><tgroup cols="1"><tbody><row><entry
635 align="char">
636<para>int ioctl(fd, int request = VIDEO_FREEZE);</para>
637</entry>
638 </row></tbody></tgroup></informaltable>
639<para>PARAMETERS
640</para>
641<informaltable><tgroup cols="2"><tbody><row><entry
642 align="char">
643<para>int fd</para>
644</entry><entry
645 align="char">
646<para>File descriptor returned by a previous call to open().</para>
647</entry>
648 </row><row><entry
649 align="char">
650<para>int request</para>
651</entry><entry
652 align="char">
653<para>Equals VIDEO_FREEZE for this command.</para>
654</entry>
655 </row></tbody></tgroup></informaltable>
656<para>ERRORS
657</para>
658<informaltable><tgroup cols="2"><tbody><row><entry
659 align="char">
660<para>EBADF</para>
661</entry><entry
662 align="char">
663<para>fd is not a valid open file descriptor</para>
664</entry>
665 </row><row><entry
666 align="char">
667<para>EINTERNAL</para>
668</entry><entry
669 align="char">
670<para>Internal error, possibly in the communication with the
671 DVB subsystem.</para>
672</entry>
673 </row></tbody></tgroup></informaltable>
674
675</section><section
676role="subsection"><title>VIDEO_CONTINUE</title>
677<para>DESCRIPTION
678</para>
679<informaltable><tgroup cols="1"><tbody><row><entry
680 align="char">
681<para>This ioctl call restarts decoding and playing processes of the video stream
682 which was played before a call to VIDEO_FREEZE was made.</para>
683</entry>
684 </row></tbody></tgroup></informaltable>
685<para>SYNOPSIS
686</para>
687<informaltable><tgroup cols="1"><tbody><row><entry
688 align="char">
689<para>int ioctl(fd, int request = VIDEO_CONTINUE);</para>
690</entry>
691 </row></tbody></tgroup></informaltable>
692<para>PARAMETERS
693</para>
694<informaltable><tgroup cols="2"><tbody><row><entry
695 align="char">
696<para>int fd</para>
697</entry><entry
698 align="char">
699<para>File descriptor returned by a previous call to open().</para>
700</entry>
701 </row><row><entry
702 align="char">
703<para>int request</para>
704</entry><entry
705 align="char">
706<para>Equals VIDEO_CONTINUE for this command.</para>
707</entry>
708 </row></tbody></tgroup></informaltable>
709<para>ERRORS
710</para>
711<informaltable><tgroup cols="2"><tbody><row><entry
712 align="char">
713<para>EBADF</para>
714</entry><entry
715 align="char">
716<para>fd is not a valid open file descriptor</para>
717</entry>
718 </row><row><entry
719 align="char">
720<para>EINTERNAL</para>
721</entry><entry
722 align="char">
723<para>Internal error, possibly in the communication with the
724 DVB subsystem.</para>
725</entry>
726 </row></tbody></tgroup></informaltable>
727
728</section><section
729role="subsection"><title>VIDEO_SELECT_SOURCE</title>
730<para>DESCRIPTION
731</para>
732<informaltable><tgroup cols="1"><tbody><row><entry
733 align="char">
734<para>This ioctl call informs the video device which source shall be used for the input
735 data. The possible sources are demux or memory. If memory is selected, the
736 data is fed to the video device through the write command.</para>
737</entry>
738 </row></tbody></tgroup></informaltable>
739<para>SYNOPSIS
740</para>
741<informaltable><tgroup cols="1"><tbody><row><entry
742 align="char">
743<para>int ioctl(fd, int request = VIDEO_SELECT_SOURCE,
744 video_stream_source_t source);</para>
745</entry>
746 </row></tbody></tgroup></informaltable>
747<para>PARAMETERS
748</para>
749<informaltable><tgroup cols="2"><tbody><row><entry
750 align="char">
751<para>int fd</para>
752</entry><entry
753 align="char">
754<para>File descriptor returned by a previous call to open().</para>
755</entry>
756 </row><row><entry
757 align="char">
758<para>int request</para>
759</entry><entry
760 align="char">
761<para>Equals VIDEO_SELECT_SOURCE for this command.</para>
762</entry>
763 </row><row><entry
764 align="char">
765<para>video_stream_source_t
766 source</para>
767</entry><entry
768 align="char">
769<para>Indicates which source shall be used for the Video stream.</para>
770</entry>
771 </row></tbody></tgroup></informaltable>
772<para>ERRORS
773</para>
774<informaltable><tgroup cols="2"><tbody><row><entry
775 align="char">
776<para>EBADF</para>
777</entry><entry
778 align="char">
779<para>fd is not a valid open file descriptor</para>
780</entry>
781 </row><row><entry
782 align="char">
783<para>EINTERNAL</para>
784</entry><entry
785 align="char">
786<para>Internal error, possibly in the communication with the
787 DVB subsystem.</para>
788</entry>
789 </row></tbody></tgroup></informaltable>
790
791</section><section
792role="subsection"><title>VIDEO_SET_BLANK</title>
793<para>DESCRIPTION
794</para>
795<informaltable><tgroup cols="1"><tbody><row><entry
796 align="char">
797<para>This ioctl call asks the Video Device to blank out the picture.</para>
798</entry>
799 </row></tbody></tgroup></informaltable>
800<para>SYNOPSIS
801</para>
802<informaltable><tgroup cols="1"><tbody><row><entry
803 align="char">
804<para>int ioctl(fd, int request = VIDEO_SET_BLANK, boolean
805 mode);</para>
806</entry>
807 </row></tbody></tgroup></informaltable>
808<para>PARAMETERS
809</para>
810<informaltable><tgroup cols="2"><tbody><row><entry
811 align="char">
812<para>int fd</para>
813</entry><entry
814 align="char">
815<para>File descriptor returned by a previous call to open().</para>
816</entry>
817 </row><row><entry
818 align="char">
819<para>int request</para>
820</entry><entry
821 align="char">
822<para>Equals VIDEO_SET_BLANK for this command.</para>
823</entry>
824 </row><row><entry
825 align="char">
826<para>boolean mode</para>
827</entry><entry
828 align="char">
829<para>TRUE: Blank screen when stop.</para>
830</entry>
831 </row><row><entry
832 align="char">
833</entry><entry
834 align="char">
835<para>FALSE: Show last decoded frame.</para>
836</entry>
837 </row></tbody></tgroup></informaltable>
838<para>ERRORS
839</para>
840<informaltable><tgroup cols="2"><tbody><row><entry
841 align="char">
842<para>EBADF</para>
843</entry><entry
844 align="char">
845<para>fd is not a valid open file descriptor</para>
846</entry>
847 </row><row><entry
848 align="char">
849<para>EINTERNAL</para>
850</entry><entry
851 align="char">
852<para>Internal error, possibly in the communication with the
853 DVB subsystem.</para>
854</entry>
855 </row><row><entry
856 align="char">
857<para>EINVAL</para>
858</entry><entry
859 align="char">
860<para>Illegal input parameter</para>
861</entry>
862 </row></tbody></tgroup></informaltable>
863
864</section><section
865role="subsection"><title>VIDEO_GET_STATUS</title>
866<para>DESCRIPTION
867</para>
868<informaltable><tgroup cols="1"><tbody><row><entry
869 align="char">
870<para>This ioctl call asks the Video Device to return the current status of the device.</para>
871</entry>
872 </row></tbody></tgroup></informaltable>
873<para>SYNOPSIS
874</para>
875<informaltable><tgroup cols="1"><tbody><row><entry
876 align="char">
877<para> int ioctl(fd, int request = VIDEO_GET_STATUS, struct
878 video_status &#x22C6;status);</para>
879</entry>
880 </row></tbody></tgroup></informaltable>
881<para>PARAMETERS
882</para>
883<informaltable><tgroup cols="2"><tbody><row><entry
884 align="char">
885<para>int fd</para>
886</entry><entry
887 align="char">
888<para>File descriptor returned by a previous call to open().</para>
889</entry>
890 </row><row><entry
891 align="char">
892<para>int request</para>
893</entry><entry
894 align="char">
895<para>Equals VIDEO_GET_STATUS for this command.</para>
896</entry>
897 </row><row><entry
898 align="char">
899<para>struct video_status
900 *status</para>
901</entry><entry
902 align="char">
903<para>Returns the current status of the Video Device.</para>
904</entry>
905 </row></tbody></tgroup></informaltable>
906<para>ERRORS
907</para>
908<informaltable><tgroup cols="2"><tbody><row><entry
909 align="char">
910<para>EBADF</para>
911</entry><entry
912 align="char">
913<para>fd is not a valid open file descriptor</para>
914</entry>
915 </row><row><entry
916 align="char">
917<para>EINTERNAL</para>
918</entry><entry
919 align="char">
920<para>Internal error, possibly in the communication with the
921 DVB subsystem.</para>
922</entry>
923 </row><row><entry
924 align="char">
925<para>EFAULT</para>
926</entry><entry
927 align="char">
928<para>status points to invalid address</para>
929</entry>
930 </row></tbody></tgroup></informaltable>
931
932</section><section
933role="subsection"><title>VIDEO_GET_EVENT</title>
934<para>DESCRIPTION
935</para>
936<informaltable><tgroup cols="1"><tbody><row><entry
937 align="char">
938<para>This ioctl call returns an event of type video_event if available. If an event is
939 not available, the behavior depends on whether the device is in blocking or
940 non-blocking mode. In the latter case, the call fails immediately with errno
941 set to EWOULDBLOCK. In the former case, the call blocks until an event
942 becomes available. The standard Linux poll() and/or select() system calls can
943 be used with the device file descriptor to watch for new events. For select(),
944 the file descriptor should be included in the exceptfds argument, and for
945 poll(), POLLPRI should be specified as the wake-up condition. Read-only
946 permissions are sufficient for this ioctl call.</para>
947</entry>
948 </row></tbody></tgroup></informaltable>
949<para>SYNOPSIS
950</para>
951<informaltable><tgroup cols="1"><tbody><row><entry
952 align="char">
953<para> int ioctl(fd, int request = VIDEO_GET_EVENT, struct
954 video_event &#x22C6;ev);</para>
955</entry>
956 </row></tbody></tgroup></informaltable>
957<para>PARAMETERS
958</para>
959<informaltable><tgroup cols="2"><tbody><row><entry
960 align="char">
961<para>int fd</para>
962</entry><entry
963 align="char">
964<para>File descriptor returned by a previous call to open().</para>
965</entry>
966 </row><row><entry
967 align="char">
968<para>int request</para>
969</entry><entry
970 align="char">
971<para>Equals VIDEO_GET_EVENT for this command.</para>
972</entry>
973 </row><row><entry
974 align="char">
975<para>struct video_event
976 *ev</para>
977</entry><entry
978 align="char">
979<para>Points to the location where the event, if any, is to be
980 stored.</para>
981</entry>
982 </row></tbody></tgroup></informaltable>
983<para>ERRORS
984</para>
985<informaltable><tgroup cols="2"><tbody><row><entry
986 align="char">
987<para>EBADF</para>
988</entry><entry
989 align="char">
990<para>fd is not a valid open file descriptor</para>
991</entry>
992 </row><row><entry
993 align="char">
994<para>EFAULT</para>
995</entry><entry
996 align="char">
997<para>ev points to invalid address</para>
998</entry>
999 </row><row><entry
1000 align="char">
1001<para>EWOULDBLOCK</para>
1002</entry><entry
1003 align="char">
1004<para>There is no event pending, and the device is in
1005 non-blocking mode.</para>
1006</entry>
1007 </row><row><entry
1008 align="char">
1009<para>EOVERFLOW</para>
1010</entry><entry
1011 align="char">
1012</entry>
1013 </row><row><entry
1014 align="char">
1015</entry><entry
1016 align="char">
1017<para>Overflow in event queue - one or more events were lost.</para>
1018</entry>
1019 </row></tbody></tgroup></informaltable>
1020
1021</section><section
1022role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title>
1023<para>DESCRIPTION
1024</para>
1025<informaltable><tgroup cols="1"><tbody><row><entry
1026 align="char">
1027<para>This ioctl call asks the Video Device to select the video format to be applied
1028 by the MPEG chip on the video.</para>
1029</entry>
1030 </row></tbody></tgroup></informaltable>
1031<para>SYNOPSIS
1032</para>
1033<informaltable><tgroup cols="1"><tbody><row><entry
1034 align="char">
1035<para> int ioctl(fd, int request =
1036 VIDEO_SET_DISPLAY_FORMAT, video_display_format_t
1037 format);</para>
1038</entry>
1039 </row></tbody></tgroup></informaltable>
1040<para>PARAMETERS
1041</para>
1042<informaltable><tgroup cols="2"><tbody><row><entry
1043 align="char">
1044<para>int fd</para>
1045</entry><entry
1046 align="char">
1047<para>File descriptor returned by a previous call to open().</para>
1048</entry>
1049 </row><row><entry
1050 align="char">
1051<para>int request</para>
1052</entry><entry
1053 align="char">
1054<para>Equals VIDEO_SET_DISPLAY_FORMAT for this
1055 command.</para>
1056</entry>
1057 </row><row><entry
1058 align="char">
1059<para>video_display_format_t
1060 format</para>
1061</entry><entry
1062 align="char">
1063<para>Selects the video format to be used.</para>
1064</entry>
1065 </row></tbody></tgroup></informaltable>
1066<para>ERRORS
1067</para>
1068<informaltable><tgroup cols="2"><tbody><row><entry
1069 align="char">
1070<para>EBADF</para>
1071</entry><entry
1072 align="char">
1073<para>fd is not a valid open file descriptor</para>
1074</entry>
1075 </row><row><entry
1076 align="char">
1077<para>EINTERNAL</para>
1078</entry><entry
1079 align="char">
1080<para>Internal error.</para>
1081</entry>
1082 </row><row><entry
1083 align="char">
1084<para>EINVAL</para>
1085</entry><entry
1086 align="char">
1087<para>Illegal parameter format.</para>
1088</entry>
1089 </row></tbody></tgroup></informaltable>
1090
1091</section><section
1092role="subsection"><title>VIDEO_STILLPICTURE</title>
1093<para>DESCRIPTION
1094</para>
1095<informaltable><tgroup cols="1"><tbody><row><entry
1096 align="char">
1097<para>This ioctl call asks the Video Device to display a still picture (I-frame). The
1098 input data shall contain an I-frame. If the pointer is NULL, then the current
1099 displayed still picture is blanked.</para>
1100</entry>
1101 </row></tbody></tgroup></informaltable>
1102<para>SYNOPSIS
1103</para>
1104<informaltable><tgroup cols="1"><tbody><row><entry
1105 align="char">
1106<para>int ioctl(fd, int request = VIDEO_STILLPICTURE,
1107 struct video_still_picture &#x22C6;sp);</para>
1108</entry>
1109 </row></tbody></tgroup></informaltable>
1110<para>PARAMETERS
1111</para>
1112<informaltable><tgroup cols="2"><tbody><row><entry
1113 align="char">
1114<para>int fd</para>
1115</entry><entry
1116 align="char">
1117<para>File descriptor returned by a previous call to open().</para>
1118</entry>
1119 </row><row><entry
1120 align="char">
1121<para>int request</para>
1122</entry><entry
1123 align="char">
1124<para>Equals VIDEO_STILLPICTURE for this command.</para>
1125</entry>
1126 </row><row><entry
1127 align="char">
1128<para>struct
1129 video_still_picture
1130 *sp</para>
1131</entry><entry
1132 align="char">
1133<para>Pointer to a location where an I-frame and size is stored.</para>
1134</entry>
1135 </row></tbody></tgroup></informaltable>
1136<para>ERRORS
1137</para>
1138<informaltable><tgroup cols="2"><tbody><row><entry
1139 align="char">
1140<para>EBADF</para>
1141</entry><entry
1142 align="char">
1143<para>fd is not a valid open file descriptor</para>
1144</entry>
1145 </row><row><entry
1146 align="char">
1147<para>EINTERNAL</para>
1148</entry><entry
1149 align="char">
1150<para>Internal error.</para>
1151</entry>
1152 </row><row><entry
1153 align="char">
1154<para>EFAULT</para>
1155</entry><entry
1156 align="char">
1157<para>sp points to an invalid iframe.</para>
1158</entry>
1159 </row></tbody></tgroup></informaltable>
1160
1161</section><section
1162role="subsection"><title>VIDEO_FAST_FORWARD</title>
1163<para>DESCRIPTION
1164</para>
1165<informaltable><tgroup cols="1"><tbody><row><entry
1166 align="char">
1167<para>This ioctl call asks the Video Device to skip decoding of N number of I-frames.
1168 This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
1169</entry>
1170 </row></tbody></tgroup></informaltable>
1171<para>SYNOPSIS
1172</para>
1173<informaltable><tgroup cols="1"><tbody><row><entry
1174 align="char">
1175<para>int ioctl(fd, int request = VIDEO_FAST_FORWARD, int
1176 nFrames);</para>
1177</entry>
1178 </row></tbody></tgroup></informaltable>
1179<para>PARAMETERS
1180</para>
1181<informaltable><tgroup cols="2"><tbody><row><entry
1182 align="char">
1183<para>int fd</para>
1184</entry><entry
1185 align="char">
1186<para>File descriptor returned by a previous call to open().</para>
1187</entry>
1188 </row><row><entry
1189 align="char">
1190<para>int request</para>
1191</entry><entry
1192 align="char">
1193<para>Equals VIDEO_FAST_FORWARD for this command.</para>
1194</entry>
1195 </row><row><entry
1196 align="char">
1197<para>int nFrames</para>
1198</entry><entry
1199 align="char">
1200<para>The number of frames to skip.</para>
1201</entry>
1202 </row></tbody></tgroup></informaltable>
1203<para>ERRORS
1204</para>
1205<informaltable><tgroup cols="2"><tbody><row><entry
1206 align="char">
1207<para>EBADF</para>
1208</entry><entry
1209 align="char">
1210<para>fd is not a valid open file descriptor</para>
1211</entry>
1212 </row><row><entry
1213 align="char">
1214<para>EINTERNAL</para>
1215</entry><entry
1216 align="char">
1217<para>Internal error.</para>
1218</entry>
1219 </row><row><entry
1220 align="char">
1221<para>EPERM</para>
1222</entry><entry
1223 align="char">
1224<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
1225</entry>
1226 </row><row><entry
1227 align="char">
1228<para>EINVAL</para>
1229</entry><entry
1230 align="char">
1231<para>Illegal parameter format.</para>
1232</entry>
1233 </row></tbody></tgroup></informaltable>
1234
1235</section><section
1236role="subsection"><title>VIDEO_SLOWMOTION</title>
1237<para>DESCRIPTION
1238</para>
1239<informaltable><tgroup cols="1"><tbody><row><entry
1240 align="char">
1241<para>This ioctl call asks the video device to repeat decoding frames N number of
1242 times. This call can only be used if VIDEO_SOURCE_MEMORY is selected.</para>
1243</entry>
1244 </row></tbody></tgroup></informaltable>
1245<para>SYNOPSIS
1246</para>
1247<informaltable><tgroup cols="1"><tbody><row><entry
1248 align="char">
1249<para>int ioctl(fd, int request = VIDEO_SLOWMOTION, int
1250 nFrames);</para>
1251</entry>
1252 </row></tbody></tgroup></informaltable>
1253<para>PARAMETERS
1254</para>
1255<informaltable><tgroup cols="2"><tbody><row><entry
1256 align="char">
1257<para>int fd</para>
1258</entry><entry
1259 align="char">
1260<para>File descriptor returned by a previous call to open().</para>
1261</entry>
1262 </row><row><entry
1263 align="char">
1264<para>int request</para>
1265</entry><entry
1266 align="char">
1267<para>Equals VIDEO_SLOWMOTION for this command.</para>
1268</entry>
1269 </row><row><entry
1270 align="char">
1271<para>int nFrames</para>
1272</entry><entry
1273 align="char">
1274<para>The number of times to repeat each frame.</para>
1275</entry>
1276 </row></tbody></tgroup></informaltable>
1277<para>ERRORS
1278</para>
1279<informaltable><tgroup cols="2"><tbody><row><entry
1280 align="char">
1281<para>EBADF</para>
1282</entry><entry
1283 align="char">
1284<para>fd is not a valid open file descriptor</para>
1285</entry>
1286 </row><row><entry
1287 align="char">
1288<para>EINTERNAL</para>
1289</entry><entry
1290 align="char">
1291<para>Internal error.</para>
1292</entry>
1293 </row><row><entry
1294 align="char">
1295<para>EPERM</para>
1296</entry><entry
1297 align="char">
1298<para>Mode VIDEO_SOURCE_MEMORY not selected.</para>
1299</entry>
1300 </row><row><entry
1301 align="char">
1302<para>EINVAL</para>
1303</entry><entry
1304 align="char">
1305<para>Illegal parameter format.</para>
1306</entry>
1307 </row></tbody></tgroup></informaltable>
1308
1309</section><section
1310role="subsection"><title>VIDEO_GET_CAPABILITIES</title>
1311<para>DESCRIPTION
1312</para>
1313<informaltable><tgroup cols="1"><tbody><row><entry
1314 align="char">
1315<para>This ioctl call asks the video device about its decoding capabilities. On success
1316 it returns and integer which has bits set according to the defines in section ??.</para>
1317</entry>
1318 </row></tbody></tgroup></informaltable>
1319<para>SYNOPSIS
1320</para>
1321<informaltable><tgroup cols="1"><tbody><row><entry
1322 align="char">
1323<para>int ioctl(fd, int request = VIDEO_GET_CAPABILITIES,
1324 unsigned int &#x22C6;cap);</para>
1325</entry>
1326 </row></tbody></tgroup></informaltable>
1327<para>PARAMETERS
1328</para>
1329<informaltable><tgroup cols="2"><tbody><row><entry
1330 align="char">
1331<para>int fd</para>
1332</entry><entry
1333 align="char">
1334<para>File descriptor returned by a previous call to open().</para>
1335</entry>
1336 </row><row><entry
1337 align="char">
1338<para>int request</para>
1339</entry><entry
1340 align="char">
1341<para>Equals VIDEO_GET_CAPABILITIES for this
1342 command.</para>
1343</entry>
1344 </row><row><entry
1345 align="char">
1346<para>unsigned int *cap</para>
1347</entry><entry
1348 align="char">
1349<para>Pointer to a location where to store the capability
1350 information.</para>
1351</entry>
1352 </row></tbody></tgroup></informaltable>
1353<para>ERRORS
1354</para>
1355<informaltable><tgroup cols="2"><tbody><row><entry
1356 align="char">
1357<para>EBADF</para>
1358</entry><entry
1359 align="char">
1360<para>fd is not a valid open file descriptor</para>
1361</entry>
1362 </row><row><entry
1363 align="char">
1364<para>EFAULT</para>
1365</entry><entry
1366 align="char">
1367<para>cap points to an invalid iframe.</para>
1368</entry>
1369 </row></tbody></tgroup></informaltable>
1370
1371</section><section
1372role="subsection"><title>VIDEO_SET_ID</title>
1373<para>DESCRIPTION
1374</para>
1375<informaltable><tgroup cols="1"><tbody><row><entry
1376 align="char">
1377<para>This ioctl selects which sub-stream is to be decoded if a program or system
1378 stream is sent to the video device.</para>
1379</entry>
1380 </row></tbody></tgroup></informaltable>
1381<para>SYNOPSIS
1382</para>
1383<informaltable><tgroup cols="1"><tbody><row><entry
1384 align="char">
1385<para>int ioctl(int fd, int request = VIDEO_SET_ID, int
1386 id);</para>
1387</entry>
1388 </row></tbody></tgroup></informaltable>
1389<para>PARAMETERS
1390</para>
1391<informaltable><tgroup cols="2"><tbody><row><entry
1392 align="char">
1393<para>int fd</para>
1394</entry><entry
1395 align="char">
1396<para>File descriptor returned by a previous call to open().</para>
1397</entry>
1398 </row><row><entry
1399 align="char">
1400<para>int request</para>
1401</entry><entry
1402 align="char">
1403<para>Equals VIDEO_SET_ID for this command.</para>
1404</entry>
1405 </row><row><entry
1406 align="char">
1407<para>int id</para>
1408</entry><entry
1409 align="char">
1410<para>video sub-stream id</para>
1411</entry>
1412 </row></tbody></tgroup></informaltable>
1413<para>ERRORS
1414</para>
1415<informaltable><tgroup cols="2"><tbody><row><entry
1416 align="char">
1417<para>EBADF</para>
1418</entry><entry
1419 align="char">
1420<para>fd is not a valid open file descriptor.</para>
1421</entry>
1422 </row><row><entry
1423 align="char">
1424<para>EINTERNAL</para>
1425</entry><entry
1426 align="char">
1427<para>Internal error.</para>
1428</entry>
1429 </row><row><entry
1430 align="char">
1431<para>EINVAL</para>
1432</entry><entry
1433 align="char">
1434<para>Invalid sub-stream id.</para>
1435</entry>
1436 </row></tbody></tgroup></informaltable>
1437
1438</section><section
1439role="subsection"><title>VIDEO_CLEAR_BUFFER</title>
1440<para>DESCRIPTION
1441</para>
1442<informaltable><tgroup cols="1"><tbody><row><entry
1443 align="char">
1444<para>This ioctl call clears all video buffers in the driver and in the decoder hardware.</para>
1445</entry>
1446 </row></tbody></tgroup></informaltable>
1447<para>SYNOPSIS
1448</para>
1449<informaltable><tgroup cols="1"><tbody><row><entry
1450 align="char">
1451<para>int ioctl(fd, int request = VIDEO_CLEAR_BUFFER);</para>
1452</entry>
1453 </row></tbody></tgroup></informaltable>
1454<para>PARAMETERS
1455</para>
1456<informaltable><tgroup cols="2"><tbody><row><entry
1457 align="char">
1458<para>int fd</para>
1459</entry><entry
1460 align="char">
1461<para>File descriptor returned by a previous call to open().</para>
1462</entry>
1463 </row><row><entry
1464 align="char">
1465<para>int request</para>
1466</entry><entry
1467 align="char">
1468<para>Equals VIDEO_CLEAR_BUFFER for this command.</para>
1469</entry>
1470 </row></tbody></tgroup></informaltable>
1471<para>ERRORS
1472</para>
1473<informaltable><tgroup cols="2"><tbody><row><entry
1474 align="char">
1475<para>EBADF</para>
1476</entry><entry
1477 align="char">
1478<para>fd is not a valid open file descriptor</para>
1479</entry>
1480 </row></tbody></tgroup></informaltable>
1481
1482</section><section
1483role="subsection"><title>VIDEO_SET_STREAMTYPE</title>
1484<para>DESCRIPTION
1485</para>
1486<informaltable><tgroup cols="1"><tbody><row><entry
1487 align="char">
1488<para>This ioctl tells the driver which kind of stream to expect being written to it. If
1489 this call is not used the default of video PES is used. Some drivers might not
1490 support this call and always expect PES.</para>
1491</entry>
1492 </row></tbody></tgroup></informaltable>
1493<para>SYNOPSIS
1494</para>
1495<informaltable><tgroup cols="1"><tbody><row><entry
1496 align="char">
1497<para>int ioctl(fd, int request = VIDEO_SET_STREAMTYPE,
1498 int type);</para>
1499</entry>
1500 </row></tbody></tgroup></informaltable>
1501<para>PARAMETERS
1502</para>
1503<informaltable><tgroup cols="2"><tbody><row><entry
1504 align="char">
1505<para>int fd</para>
1506</entry><entry
1507 align="char">
1508<para>File descriptor returned by a previous call to open().</para>
1509</entry>
1510 </row><row><entry
1511 align="char">
1512<para>int request</para>
1513</entry><entry
1514 align="char">
1515<para>Equals VIDEO_SET_STREAMTYPE for this command.</para>
1516</entry>
1517 </row><row><entry
1518 align="char">
1519<para>int type</para>
1520</entry><entry
1521 align="char">
1522<para>stream type</para>
1523</entry>
1524 </row></tbody></tgroup></informaltable>
1525<para>ERRORS
1526</para>
1527<informaltable><tgroup cols="2"><tbody><row><entry
1528 align="char">
1529<para>EBADF</para>
1530</entry><entry
1531 align="char">
1532<para>fd is not a valid open file descriptor</para>
1533</entry>
1534 </row><row><entry
1535 align="char">
1536<para>EINVAL</para>
1537</entry><entry
1538 align="char">
1539<para>type is not a valid or supported stream type.</para>
1540</entry>
1541 </row></tbody></tgroup></informaltable>
1542
1543</section><section
1544role="subsection"><title>VIDEO_SET_FORMAT</title>
1545<para>DESCRIPTION
1546</para>
1547<informaltable><tgroup cols="1"><tbody><row><entry
1548 align="char">
1549<para>This ioctl sets the screen format (aspect ratio) of the connected output device
1550 (TV) so that the output of the decoder can be adjusted accordingly.</para>
1551</entry>
1552 </row></tbody></tgroup></informaltable>
1553<para>SYNOPSIS
1554</para>
1555<informaltable><tgroup cols="1"><tbody><row><entry
1556 align="char">
1557<para> int ioctl(fd, int request = VIDEO_SET_FORMAT,
1558 video_format_t format);</para>
1559</entry>
1560 </row></tbody></tgroup></informaltable>
1561<para>PARAMETERS
1562</para>
1563<informaltable><tgroup cols="2"><tbody><row><entry
1564 align="char">
1565<para>int fd</para>
1566</entry><entry
1567 align="char">
1568<para>File descriptor returned by a previous call to open().</para>
1569</entry>
1570 </row><row><entry
1571 align="char">
1572<para>int request</para>
1573</entry><entry
1574 align="char">
1575<para>Equals VIDEO_SET_FORMAT for this command.</para>
1576</entry>
1577 </row><row><entry
1578 align="char">
1579<para>video_format_t
1580 format</para>
1581</entry><entry
1582 align="char">
1583<para>video format of TV as defined in section ??.</para>
1584</entry>
1585 </row></tbody></tgroup></informaltable>
1586<para>ERRORS
1587</para>
1588<informaltable><tgroup cols="2"><tbody><row><entry
1589 align="char">
1590<para>EBADF</para>
1591</entry><entry
1592 align="char">
1593<para>fd is not a valid open file descriptor</para>
1594</entry>
1595 </row><row><entry
1596 align="char">
1597<para>EINVAL</para>
1598</entry><entry
1599 align="char">
1600<para>format is not a valid video format.</para>
1601</entry>
1602 </row></tbody></tgroup></informaltable>
1603
1604</section><section
1605role="subsection"><title>VIDEO_SET_SYSTEM</title>
1606<para>DESCRIPTION
1607</para>
1608<informaltable><tgroup cols="1"><tbody><row><entry
1609 align="char">
1610<para>This ioctl sets the television output format. The format (see section ??) may
1611 vary from the color format of the displayed MPEG stream. If the hardware is
1612 not able to display the requested format the call will return an error.</para>
1613</entry>
1614 </row></tbody></tgroup></informaltable>
1615<para>SYNOPSIS
1616</para>
1617<informaltable><tgroup cols="1"><tbody><row><entry
1618 align="char">
1619<para> int ioctl(fd, int request = VIDEO_SET_SYSTEM ,
1620 video_system_t system);</para>
1621</entry>
1622 </row></tbody></tgroup></informaltable>
1623<para>PARAMETERS
1624</para>
1625<informaltable><tgroup cols="2"><tbody><row><entry
1626 align="char">
1627<para>int fd</para>
1628</entry><entry
1629 align="char">
1630<para>File descriptor returned by a previous call to open().</para>
1631</entry>
1632 </row><row><entry
1633 align="char">
1634<para>int request</para>
1635</entry><entry
1636 align="char">
1637<para>Equals VIDEO_SET_FORMAT for this command.</para>
1638</entry>
1639 </row><row><entry
1640 align="char">
1641<para>video_system_t
1642 system</para>
1643</entry><entry
1644 align="char">
1645<para>video system of TV output.</para>
1646</entry>
1647 </row></tbody></tgroup></informaltable>
1648<para>ERRORS
1649</para>
1650<informaltable><tgroup cols="2"><tbody><row><entry
1651 align="char">
1652<para>EBADF</para>
1653</entry><entry
1654 align="char">
1655<para>fd is not a valid open file descriptor</para>
1656</entry>
1657 </row><row><entry
1658 align="char">
1659<para>EINVAL</para>
1660</entry><entry
1661 align="char">
1662<para>system is not a valid or supported video system.</para>
1663</entry>
1664 </row></tbody></tgroup></informaltable>
1665
1666</section><section
1667role="subsection"><title>VIDEO_SET_HIGHLIGHT</title>
1668<para>DESCRIPTION
1669</para>
1670<informaltable><tgroup cols="1"><tbody><row><entry
1671 align="char">
1672<para>This ioctl sets the SPU highlight information for the menu access of a DVD.</para>
1673</entry>
1674 </row></tbody></tgroup></informaltable>
1675<para>SYNOPSIS
1676</para>
1677<informaltable><tgroup cols="1"><tbody><row><entry
1678 align="char">
1679<para> int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT
1680 ,video_highlight_t &#x22C6;vhilite)</para>
1681</entry>
1682 </row></tbody></tgroup></informaltable>
1683<para>PARAMETERS
1684</para>
1685<informaltable><tgroup cols="2"><tbody><row><entry
1686 align="char">
1687<para>int fd</para>
1688</entry><entry
1689 align="char">
1690<para>File descriptor returned by a previous call to open().</para>
1691</entry>
1692 </row><row><entry
1693 align="char">
1694<para>int request</para>
1695</entry><entry
1696 align="char">
1697<para>Equals VIDEO_SET_HIGHLIGHT for this command.</para>
1698</entry>
1699 </row><row><entry
1700 align="char">
1701<para>video_highlight_t
1702 *vhilite</para>
1703</entry><entry
1704 align="char">
1705<para>SPU Highlight information according to section ??.</para>
1706</entry>
1707 </row></tbody></tgroup></informaltable>
1708<para>ERRORS
1709</para>
1710<informaltable><tgroup cols="2"><tbody><row><entry
1711 align="char">
1712<para>EBADF</para>
1713</entry><entry
1714 align="char">
1715<para>fd is not a valid open file descriptor.</para>
1716</entry>
1717 </row><row><entry
1718 align="char">
1719<para>EINVAL</para>
1720</entry><entry
1721 align="char">
1722<para>input is not a valid highlight setting.</para>
1723</entry>
1724 </row></tbody></tgroup></informaltable>
1725
1726</section><section
1727role="subsection"><title>VIDEO_SET_SPU</title>
1728<para>DESCRIPTION
1729</para>
1730<informaltable><tgroup cols="1"><tbody><row><entry
1731 align="char">
1732<para>This ioctl activates or deactivates SPU decoding in a DVD input stream. It can
1733 only be used, if the driver is able to handle a DVD stream.</para>
1734</entry>
1735 </row></tbody></tgroup></informaltable>
1736<para>SYNOPSIS
1737</para>
1738<informaltable><tgroup cols="1"><tbody><row><entry
1739 align="char">
1740<para> int ioctl(fd, int request = VIDEO_SET_SPU ,
1741 video_spu_t &#x22C6;spu)</para>
1742</entry>
1743 </row></tbody></tgroup></informaltable>
1744<para>PARAMETERS
1745</para>
1746<informaltable><tgroup cols="2"><tbody><row><entry
1747 align="char">
1748<para>int fd</para>
1749</entry><entry
1750 align="char">
1751<para>File descriptor returned by a previous call to open().</para>
1752</entry>
1753 </row><row><entry
1754 align="char">
1755<para>int request</para>
1756</entry><entry
1757 align="char">
1758<para>Equals VIDEO_SET_SPU for this command.</para>
1759</entry>
1760 </row><row><entry
1761 align="char">
1762<para>video_spu_t *spu</para>
1763</entry><entry
1764 align="char">
1765<para>SPU decoding (de)activation and subid setting according
1766 to section ??.</para>
1767</entry>
1768 </row></tbody></tgroup></informaltable>
1769<para>ERRORS
1770</para>
1771<informaltable><tgroup cols="2"><tbody><row><entry
1772 align="char">
1773<para>EBADF</para>
1774</entry><entry
1775 align="char">
1776<para>fd is not a valid open file descriptor</para>
1777</entry>
1778 </row><row><entry
1779 align="char">
1780<para>EINVAL</para>
1781</entry><entry
1782 align="char">
1783<para>input is not a valid spu setting or driver cannot handle
1784 SPU.</para>
1785</entry>
1786 </row></tbody></tgroup></informaltable>
1787
1788</section><section
1789role="subsection"><title>VIDEO_SET_SPU_PALETTE</title>
1790<para>DESCRIPTION
1791</para>
1792<informaltable><tgroup cols="1"><tbody><row><entry
1793 align="char">
1794<para>This ioctl sets the SPU color palette.</para>
1795</entry>
1796 </row></tbody></tgroup></informaltable>
1797<para>SYNOPSIS
1798</para>
1799<informaltable><tgroup cols="1"><tbody><row><entry
1800 align="char">
1801<para> int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE
1802 ,video_spu_palette_t &#x22C6;palette )</para>
1803</entry>
1804 </row></tbody></tgroup></informaltable>
1805<para>PARAMETERS
1806</para>
1807<informaltable><tgroup cols="2"><tbody><row><entry
1808 align="char">
1809<para>int fd</para>
1810</entry><entry
1811 align="char">
1812<para>File descriptor returned by a previous call to open().</para>
1813</entry>
1814 </row><row><entry
1815 align="char">
1816<para>int request</para>
1817</entry><entry
1818 align="char">
1819<para>Equals VIDEO_SET_SPU_PALETTE for this command.</para>
1820</entry>
1821 </row><row><entry
1822 align="char">
1823<para>video_spu_palette_t
1824 *palette</para>
1825</entry><entry
1826 align="char">
1827<para>SPU palette according to section ??.</para>
1828</entry>
1829 </row></tbody></tgroup></informaltable>
1830<para>ERRORS
1831</para>
1832<informaltable><tgroup cols="2"><tbody><row><entry
1833 align="char">
1834<para>EBADF</para>
1835</entry><entry
1836 align="char">
1837<para>fd is not a valid open file descriptor</para>
1838</entry>
1839 </row><row><entry
1840 align="char">
1841<para>EINVAL</para>
1842</entry><entry
1843 align="char">
1844<para>input is not a valid palette or driver doesn&#8217;t handle SPU.</para>
1845</entry>
1846 </row></tbody></tgroup></informaltable>
1847
1848</section><section
1849role="subsection"><title>VIDEO_GET_NAVI</title>
1850<para>DESCRIPTION
1851</para>
1852<informaltable><tgroup cols="1"><tbody><row><entry
1853 align="char">
1854<para>This ioctl returns navigational information from the DVD stream. This is
1855 especially needed if an encoded stream has to be decoded by the hardware.</para>
1856</entry>
1857 </row></tbody></tgroup></informaltable>
1858<para>SYNOPSIS
1859</para>
1860<informaltable><tgroup cols="1"><tbody><row><entry
1861 align="char">
1862<para> int ioctl(fd, int request = VIDEO_GET_NAVI ,
1863 video_navi_pack_t &#x22C6;navipack)</para>
1864</entry>
1865 </row></tbody></tgroup></informaltable>
1866<para>PARAMETERS
1867</para>
1868<informaltable><tgroup cols="2"><tbody><row><entry
1869 align="char">
1870<para>int fd</para>
1871</entry><entry
1872 align="char">
1873<para>File descriptor returned by a previous call to open().</para>
1874</entry>
1875 </row><row><entry
1876 align="char">
1877<para>int request</para>
1878</entry><entry
1879 align="char">
1880<para>Equals VIDEO_GET_NAVI for this command.</para>
1881</entry>
1882 </row><row><entry
1883 align="char">
1884<para>video_navi_pack_t
1885 *navipack</para>
1886</entry><entry
1887 align="char">
1888<para>PCI or DSI pack (private stream 2) according to section
1889 ??.</para>
1890</entry>
1891 </row></tbody></tgroup></informaltable>
1892<para>ERRORS
1893</para>
1894<informaltable><tgroup cols="2"><tbody><row><entry
1895 align="char">
1896<para>EBADF</para>
1897</entry><entry
1898 align="char">
1899<para>fd is not a valid open file descriptor</para>
1900</entry>
1901 </row><row><entry
1902 align="char">
1903<para>EFAULT</para>
1904</entry><entry
1905 align="char">
1906<para>driver is not able to return navigational information</para>
1907</entry>
1908 </row></tbody></tgroup></informaltable>
1909
1910</section><section
1911role="subsection"><title>VIDEO_SET_ATTRIBUTES</title>
1912<para>DESCRIPTION
1913</para>
1914<informaltable><tgroup cols="1"><tbody><row><entry
1915 align="char">
1916<para>This ioctl is intended for DVD playback and allows you to set certain
1917 information about the stream. Some hardware may not need this information,
1918 but the call also tells the hardware to prepare for DVD playback.</para>
1919</entry>
1920 </row></tbody></tgroup></informaltable>
1921<para>SYNOPSIS
1922</para>
1923<informaltable><tgroup cols="1"><tbody><row><entry
1924 align="char">
1925<para> int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE
1926 ,video_attributes_t vattr)</para>
1927</entry>
1928 </row></tbody></tgroup></informaltable>
1929<para>PARAMETERS
1930</para>
1931<informaltable><tgroup cols="2"><tbody><row><entry
1932 align="char">
1933<para>int fd</para>
1934</entry><entry
1935 align="char">
1936<para>File descriptor returned by a previous call to open().</para>
1937</entry>
1938 </row><row><entry
1939 align="char">
1940<para>int request</para>
1941</entry><entry
1942 align="char">
1943<para>Equals VIDEO_SET_ATTRIBUTE for this command.</para>
1944</entry>
1945 </row><row><entry
1946 align="char">
1947<para>video_attributes_t
1948 vattr</para>
1949</entry><entry
1950 align="char">
1951<para>video attributes according to section ??.</para>
1952</entry>
1953 </row></tbody></tgroup></informaltable>
1954<para>ERRORS
1955</para>
1956<informaltable><tgroup cols="2"><tbody><row><entry
1957 align="char">
1958<para>EBADF</para>
1959</entry><entry
1960 align="char">
1961<para>fd is not a valid open file descriptor</para>
1962</entry>
1963 </row><row><entry
1964 align="char">
1965<para>EINVAL</para>
1966</entry><entry
1967 align="char">
1968<para>input is not a valid attribute setting.</para>
1969</entry>
1970 </row></tbody></tgroup></informaltable>
1971 </section></section>
diff --git a/Documentation/DocBook/media/v4l/.gitignore b/Documentation/DocBook/media/v4l/.gitignore
new file mode 100644
index 000000000000..d7ec32eafac9
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/.gitignore
@@ -0,0 +1 @@
!*.xml
diff --git a/Documentation/DocBook/media/v4l/bayer.pdf b/Documentation/DocBook/media/v4l/bayer.pdf
new file mode 100644
index 000000000000..905e60e6cd42
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/bayer.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/bayer.png b/Documentation/DocBook/media/v4l/bayer.png
new file mode 100644
index 000000000000..9b15fb22e817
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/bayer.png
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml
new file mode 100644
index 000000000000..afc8a0dd2601
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/biblio.xml
@@ -0,0 +1,188 @@
1 <bibliography>
2 <title>References</title>
3
4 <biblioentry id="eia608">
5 <abbrev>EIA&nbsp;608-B</abbrev>
6 <authorgroup>
7 <corpauthor>Electronic Industries Alliance (<ulink
8url="http://www.eia.org">http://www.eia.org</ulink>)</corpauthor>
9 </authorgroup>
10 <title>EIA 608-B "Recommended Practice for Line 21 Data
11Service"</title>
12 </biblioentry>
13
14 <biblioentry id="en300294">
15 <abbrev>EN&nbsp;300&nbsp;294</abbrev>
16 <authorgroup>
17 <corpauthor>European Telecommunication Standards Institute
18(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
19 </authorgroup>
20 <title>EN 300 294 "625-line television Wide Screen Signalling
21(WSS)"</title>
22 </biblioentry>
23
24 <biblioentry id="ets300231">
25 <abbrev>ETS&nbsp;300&nbsp;231</abbrev>
26 <authorgroup>
27 <corpauthor>European Telecommunication Standards Institute
28(<ulink
29url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
30 </authorgroup>
31 <title>ETS 300 231 "Specification of the domestic video
32Programme Delivery Control system (PDC)"</title>
33 </biblioentry>
34
35 <biblioentry id="ets300706">
36 <abbrev>ETS&nbsp;300&nbsp;706</abbrev>
37 <authorgroup>
38 <corpauthor>European Telecommunication Standards Institute
39(<ulink url="http://www.etsi.org">http://www.etsi.org</ulink>)</corpauthor>
40 </authorgroup>
41 <title>ETS 300 706 "Enhanced Teletext specification"</title>
42 </biblioentry>
43
44 <biblioentry id="mpeg2part1">
45 <abbrev>ISO&nbsp;13818-1</abbrev>
46 <authorgroup>
47 <corpauthor>International Telecommunication Union (<ulink
48url="http://www.itu.ch">http://www.itu.ch</ulink>), International
49Organisation for Standardisation (<ulink
50url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
51 </authorgroup>
52 <title>ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information
53technology &mdash; Generic coding of moving pictures and associated
54audio information: Systems"</title>
55 </biblioentry>
56
57 <biblioentry id="mpeg2part2">
58 <abbrev>ISO&nbsp;13818-2</abbrev>
59 <authorgroup>
60 <corpauthor>International Telecommunication Union (<ulink
61url="http://www.itu.ch">http://www.itu.ch</ulink>), International
62Organisation for Standardisation (<ulink
63url="http://www.iso.ch">http://www.iso.ch</ulink>)</corpauthor>
64 </authorgroup>
65 <title>ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information
66technology &mdash; Generic coding of moving pictures and associated
67audio information: Video"</title>
68 </biblioentry>
69
70 <biblioentry id="itu470">
71 <abbrev>ITU&nbsp;BT.470</abbrev>
72 <authorgroup>
73 <corpauthor>International Telecommunication Union (<ulink
74url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
75 </authorgroup>
76 <title>ITU-R Recommendation BT.470-6 "Conventional Television
77Systems"</title>
78 </biblioentry>
79
80 <biblioentry id="itu601">
81 <abbrev>ITU&nbsp;BT.601</abbrev>
82 <authorgroup>
83 <corpauthor>International Telecommunication Union (<ulink
84url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
85 </authorgroup>
86 <title>ITU-R Recommendation BT.601-5 "Studio Encoding Parameters
87of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect
88Ratios"</title>
89 </biblioentry>
90
91 <biblioentry id="itu653">
92 <abbrev>ITU&nbsp;BT.653</abbrev>
93 <authorgroup>
94 <corpauthor>International Telecommunication Union (<ulink
95url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
96 </authorgroup>
97 <title>ITU-R Recommendation BT.653-3 "Teletext systems"</title>
98 </biblioentry>
99
100 <biblioentry id="itu709">
101 <abbrev>ITU&nbsp;BT.709</abbrev>
102 <authorgroup>
103 <corpauthor>International Telecommunication Union (<ulink
104url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
105 </authorgroup>
106 <title>ITU-R Recommendation BT.709-5 "Parameter values for the
107HDTV standards for production and international programme
108exchange"</title>
109 </biblioentry>
110
111 <biblioentry id="itu1119">
112 <abbrev>ITU&nbsp;BT.1119</abbrev>
113 <authorgroup>
114 <corpauthor>International Telecommunication Union (<ulink
115url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor>
116 </authorgroup>
117 <title>ITU-R Recommendation BT.1119 "625-line
118television Wide Screen Signalling (WSS)"</title>
119 </biblioentry>
120
121 <biblioentry id="jfif">
122 <abbrev>JFIF</abbrev>
123 <authorgroup>
124 <corpauthor>Independent JPEG Group (<ulink
125url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor>
126 </authorgroup>
127 <title>JPEG File Interchange Format</title>
128 <subtitle>Version 1.02</subtitle>
129 </biblioentry>
130
131 <biblioentry id="smpte12m">
132 <abbrev>SMPTE&nbsp;12M</abbrev>
133 <authorgroup>
134 <corpauthor>Society of Motion Picture and Television Engineers
135(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
136 </authorgroup>
137 <title>SMPTE 12M-1999 "Television, Audio and Film - Time and
138Control Code"</title>
139 </biblioentry>
140
141 <biblioentry id="smpte170m">
142 <abbrev>SMPTE&nbsp;170M</abbrev>
143 <authorgroup>
144 <corpauthor>Society of Motion Picture and Television Engineers
145(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
146 </authorgroup>
147 <title>SMPTE 170M-1999 "Television - Composite Analog Video
148Signal - NTSC for Studio Applications"</title>
149 </biblioentry>
150
151 <biblioentry id="smpte240m">
152 <abbrev>SMPTE&nbsp;240M</abbrev>
153 <authorgroup>
154 <corpauthor>Society of Motion Picture and Television Engineers
155(<ulink url="http://www.smpte.org">http://www.smpte.org</ulink>)</corpauthor>
156 </authorgroup>
157 <title>SMPTE 240M-1999 "Television - Signal Parameters -
1581125-Line High-Definition Production"</title>
159 </biblioentry>
160
161 <biblioentry id="en50067">
162 <abbrev>EN&nbsp;50067</abbrev>
163 <authorgroup>
164 <corpauthor>European Committee for Electrotechnical Standardization
165(<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor>
166 </authorgroup>
167 <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting
168in the frequency range from 87,5 to 108,0 MHz</title>
169 </biblioentry>
170
171 <biblioentry id="nrsc4">
172 <abbrev>NRSC-4</abbrev>
173 <authorgroup>
174 <corpauthor>National Radio Systems Committee
175(<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor>
176 </authorgroup>
177 <title>NTSC-4: United States RBDS Standard</title>
178 </biblioentry>
179
180 </bibliography>
181
182 <!--
183Local Variables:
184mode: sgml
185sgml-parent-document: "v4l2.sgml"
186indent-tabs-mode: nil
187End:
188 -->
diff --git a/Documentation/DocBook/media/v4l/capture.c.xml b/Documentation/DocBook/media/v4l/capture.c.xml
new file mode 100644
index 000000000000..1c5c49a2de59
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/capture.c.xml
@@ -0,0 +1,659 @@
1<programlisting>
2/*
3 * V4L2 video capture example
4 *
5 * This program can be used and distributed without restrictions.
6 *
7 * This program is provided with the V4L2 API
8 * see http://linuxtv.org/docs.php for more information
9 */
10
11#include &lt;stdio.h&gt;
12#include &lt;stdlib.h&gt;
13#include &lt;string.h&gt;
14#include &lt;assert.h&gt;
15
16#include &lt;getopt.h&gt; /* getopt_long() */
17
18#include &lt;fcntl.h&gt; /* low-level i/o */
19#include &lt;unistd.h&gt;
20#include &lt;errno.h&gt;
21#include &lt;sys/stat.h&gt;
22#include &lt;sys/types.h&gt;
23#include &lt;sys/time.h&gt;
24#include &lt;sys/mman.h&gt;
25#include &lt;sys/ioctl.h&gt;
26
27#include &lt;linux/videodev2.h&gt;
28
29#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
30
31enum io_method {
32 IO_METHOD_READ,
33 IO_METHOD_MMAP,
34 IO_METHOD_USERPTR,
35};
36
37struct buffer {
38 void *start;
39 size_t length;
40};
41
42static char *dev_name;
43static enum io_method io = IO_METHOD_MMAP;
44static int fd = -1;
45struct buffer *buffers;
46static unsigned int n_buffers;
47static int out_buf;
48static int force_format;
49static int frame_count = 70;
50
51static void errno_exit(const char *s)
52{
53 fprintf(stderr, "%s error %d, %s\n", s, errno, strerror(errno));
54 exit(EXIT_FAILURE);
55}
56
57static int xioctl(int fh, int request, void *arg)
58{
59 int r;
60
61 do {
62 r = ioctl(fh, request, arg);
63 } while (-1 == r &amp;&amp; EINTR == errno);
64
65 return r;
66}
67
68static void process_image(const void *p, int size)
69{
70 if (out_buf)
71 fwrite(p, size, 1, stdout);
72
73 fflush(stderr);
74 fprintf(stderr, ".");
75 fflush(stdout);
76}
77
78static int read_frame(void)
79{
80 struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
81 unsigned int i;
82
83 switch (io) {
84 case IO_METHOD_READ:
85 if (-1 == read(fd, buffers[0].start, buffers[0].length)) {
86 switch (errno) {
87 case EAGAIN:
88 return 0;
89
90 case EIO:
91 /* Could ignore EIO, see spec. */
92
93 /* fall through */
94
95 default:
96 errno_exit("read");
97 }
98 }
99
100 process_image(buffers[0].start, buffers[0].length);
101 break;
102
103 case IO_METHOD_MMAP:
104 CLEAR(buf);
105
106 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
107 buf.memory = V4L2_MEMORY_MMAP;
108
109 if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
110 switch (errno) {
111 case EAGAIN:
112 return 0;
113
114 case EIO:
115 /* Could ignore EIO, see spec. */
116
117 /* fall through */
118
119 default:
120 errno_exit("VIDIOC_DQBUF");
121 }
122 }
123
124 assert(buf.index &lt; n_buffers);
125
126 process_image(buffers[buf.index].start, buf.bytesused);
127
128 if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
129 errno_exit("VIDIOC_QBUF");
130 break;
131
132 case IO_METHOD_USERPTR:
133 CLEAR(buf);
134
135 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
136 buf.memory = V4L2_MEMORY_USERPTR;
137
138 if (-1 == xioctl(fd, VIDIOC_DQBUF, &amp;buf)) {
139 switch (errno) {
140 case EAGAIN:
141 return 0;
142
143 case EIO:
144 /* Could ignore EIO, see spec. */
145
146 /* fall through */
147
148 default:
149 errno_exit("VIDIOC_DQBUF");
150 }
151 }
152
153 for (i = 0; i &lt; n_buffers; ++i)
154 if (buf.m.userptr == (unsigned long)buffers[i].start
155 &amp;&amp; buf.length == buffers[i].length)
156 break;
157
158 assert(i &lt; n_buffers);
159
160 process_image((void *)buf.m.userptr, buf.bytesused);
161
162 if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
163 errno_exit("VIDIOC_QBUF");
164 break;
165 }
166
167 return 1;
168}
169
170static void mainloop(void)
171{
172 unsigned int count;
173
174 count = frame_count;
175
176 while (count-- &gt; 0) {
177 for (;;) {
178 fd_set fds;
179 struct timeval tv;
180 int r;
181
182 FD_ZERO(&amp;fds);
183 FD_SET(fd, &amp;fds);
184
185 /* Timeout. */
186 tv.tv_sec = 2;
187 tv.tv_usec = 0;
188
189 r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
190
191 if (-1 == r) {
192 if (EINTR == errno)
193 continue;
194 errno_exit("select");
195 }
196
197 if (0 == r) {
198 fprintf(stderr, "select timeout\n");
199 exit(EXIT_FAILURE);
200 }
201
202 if (read_frame())
203 break;
204 /* EAGAIN - continue select loop. */
205 }
206 }
207}
208
209static void stop_capturing(void)
210{
211 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
212
213 switch (io) {
214 case IO_METHOD_READ:
215 /* Nothing to do. */
216 break;
217
218 case IO_METHOD_MMAP:
219 case IO_METHOD_USERPTR:
220 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
221 if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &amp;type))
222 errno_exit("VIDIOC_STREAMOFF");
223 break;
224 }
225}
226
227static void start_capturing(void)
228{
229 unsigned int i;
230 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
231
232 switch (io) {
233 case IO_METHOD_READ:
234 /* Nothing to do. */
235 break;
236
237 case IO_METHOD_MMAP:
238 for (i = 0; i &lt; n_buffers; ++i) {
239 struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
240
241 CLEAR(buf);
242 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
243 buf.memory = V4L2_MEMORY_MMAP;
244 buf.index = i;
245
246 if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
247 errno_exit("VIDIOC_QBUF");
248 }
249 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
250 if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
251 errno_exit("VIDIOC_STREAMON");
252 break;
253
254 case IO_METHOD_USERPTR:
255 for (i = 0; i &lt; n_buffers; ++i) {
256 struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
257
258 CLEAR(buf);
259 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
260 buf.memory = V4L2_MEMORY_USERPTR;
261 buf.index = i;
262 buf.m.userptr = (unsigned long)buffers[i].start;
263 buf.length = buffers[i].length;
264
265 if (-1 == xioctl(fd, VIDIOC_QBUF, &amp;buf))
266 errno_exit("VIDIOC_QBUF");
267 }
268 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
269 if (-1 == xioctl(fd, VIDIOC_STREAMON, &amp;type))
270 errno_exit("VIDIOC_STREAMON");
271 break;
272 }
273}
274
275static void uninit_device(void)
276{
277 unsigned int i;
278
279 switch (io) {
280 case IO_METHOD_READ:
281 free(buffers[0].start);
282 break;
283
284 case IO_METHOD_MMAP:
285 for (i = 0; i &lt; n_buffers; ++i)
286 if (-1 == munmap(buffers[i].start, buffers[i].length))
287 errno_exit("munmap");
288 break;
289
290 case IO_METHOD_USERPTR:
291 for (i = 0; i &lt; n_buffers; ++i)
292 free(buffers[i].start);
293 break;
294 }
295
296 free(buffers);
297}
298
299static void init_read(unsigned int buffer_size)
300{
301 buffers = calloc(1, sizeof(*buffers));
302
303 if (!buffers) {
304 fprintf(stderr, "Out of memory\n");
305 exit(EXIT_FAILURE);
306 }
307
308 buffers[0].length = buffer_size;
309 buffers[0].start = malloc(buffer_size);
310
311 if (!buffers[0].start) {
312 fprintf(stderr, "Out of memory\n");
313 exit(EXIT_FAILURE);
314 }
315}
316
317static void init_mmap(void)
318{
319 struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
320
321 CLEAR(req);
322
323 req.count = 4;
324 req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
325 req.memory = V4L2_MEMORY_MMAP;
326
327 if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
328 if (EINVAL == errno) {
329 fprintf(stderr, "%s does not support "
330 "memory mapping\n", dev_name);
331 exit(EXIT_FAILURE);
332 } else {
333 errno_exit("VIDIOC_REQBUFS");
334 }
335 }
336
337 if (req.count &lt; 2) {
338 fprintf(stderr, "Insufficient buffer memory on %s\n",
339 dev_name);
340 exit(EXIT_FAILURE);
341 }
342
343 buffers = calloc(req.count, sizeof(*buffers));
344
345 if (!buffers) {
346 fprintf(stderr, "Out of memory\n");
347 exit(EXIT_FAILURE);
348 }
349
350 for (n_buffers = 0; n_buffers &lt; req.count; ++n_buffers) {
351 struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
352
353 CLEAR(buf);
354
355 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
356 buf.memory = V4L2_MEMORY_MMAP;
357 buf.index = n_buffers;
358
359 if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &amp;buf))
360 errno_exit("VIDIOC_QUERYBUF");
361
362 buffers[n_buffers].length = buf.length;
363 buffers[n_buffers].start =
364 mmap(NULL /* start anywhere */,
365 buf.length,
366 PROT_READ | PROT_WRITE /* required */,
367 MAP_SHARED /* recommended */,
368 fd, buf.m.offset);
369
370 if (MAP_FAILED == buffers[n_buffers].start)
371 errno_exit("mmap");
372 }
373}
374
375static void init_userp(unsigned int buffer_size)
376{
377 struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
378
379 CLEAR(req);
380
381 req.count = 4;
382 req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
383 req.memory = V4L2_MEMORY_USERPTR;
384
385 if (-1 == xioctl(fd, VIDIOC_REQBUFS, &amp;req)) {
386 if (EINVAL == errno) {
387 fprintf(stderr, "%s does not support "
388 "user pointer i/o\n", dev_name);
389 exit(EXIT_FAILURE);
390 } else {
391 errno_exit("VIDIOC_REQBUFS");
392 }
393 }
394
395 buffers = calloc(4, sizeof(*buffers));
396
397 if (!buffers) {
398 fprintf(stderr, "Out of memory\n");
399 exit(EXIT_FAILURE);
400 }
401
402 for (n_buffers = 0; n_buffers &lt; 4; ++n_buffers) {
403 buffers[n_buffers].length = buffer_size;
404 buffers[n_buffers].start = malloc(buffer_size);
405
406 if (!buffers[n_buffers].start) {
407 fprintf(stderr, "Out of memory\n");
408 exit(EXIT_FAILURE);
409 }
410 }
411}
412
413static void init_device(void)
414{
415 struct <link linkend="v4l2-capability">v4l2_capability</link> cap;
416 struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> cropcap;
417 struct <link linkend="v4l2-crop">v4l2_crop</link> crop;
418 struct <link linkend="v4l2-format">v4l2_format</link> fmt;
419 unsigned int min;
420
421 if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &amp;cap)) {
422 if (EINVAL == errno) {
423 fprintf(stderr, "%s is no V4L2 device\n",
424 dev_name);
425 exit(EXIT_FAILURE);
426 } else {
427 errno_exit("VIDIOC_QUERYCAP");
428 }
429 }
430
431 if (!(cap.capabilities &amp; V4L2_CAP_VIDEO_CAPTURE)) {
432 fprintf(stderr, "%s is no video capture device\n",
433 dev_name);
434 exit(EXIT_FAILURE);
435 }
436
437 switch (io) {
438 case IO_METHOD_READ:
439 if (!(cap.capabilities &amp; V4L2_CAP_READWRITE)) {
440 fprintf(stderr, "%s does not support read i/o\n",
441 dev_name);
442 exit(EXIT_FAILURE);
443 }
444 break;
445
446 case IO_METHOD_MMAP:
447 case IO_METHOD_USERPTR:
448 if (!(cap.capabilities &amp; V4L2_CAP_STREAMING)) {
449 fprintf(stderr, "%s does not support streaming i/o\n",
450 dev_name);
451 exit(EXIT_FAILURE);
452 }
453 break;
454 }
455
456
457 /* Select video input, video standard and tune here. */
458
459
460 CLEAR(cropcap);
461
462 cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
463
464 if (0 == xioctl(fd, VIDIOC_CROPCAP, &amp;cropcap)) {
465 crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
466 crop.c = cropcap.defrect; /* reset to default */
467
468 if (-1 == xioctl(fd, VIDIOC_S_CROP, &amp;crop)) {
469 switch (errno) {
470 case EINVAL:
471 /* Cropping not supported. */
472 break;
473 default:
474 /* Errors ignored. */
475 break;
476 }
477 }
478 } else {
479 /* Errors ignored. */
480 }
481
482
483 CLEAR(fmt);
484
485 fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
486 if (force_format) {
487 fmt.fmt.pix.width = 640;
488 fmt.fmt.pix.height = 480;
489 fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
490 fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
491
492 if (-1 == xioctl(fd, VIDIOC_S_FMT, &amp;fmt))
493 errno_exit("VIDIOC_S_FMT");
494
495 /* Note VIDIOC_S_FMT may change width and height. */
496 } else {
497 /* Preserve original settings as set by v4l2-ctl for example */
498 if (-1 == xioctl(fd, VIDIOC_G_FMT, &amp;fmt))
499 errno_exit("VIDIOC_G_FMT");
500 }
501
502 /* Buggy driver paranoia. */
503 min = fmt.fmt.pix.width * 2;
504 if (fmt.fmt.pix.bytesperline &lt; min)
505 fmt.fmt.pix.bytesperline = min;
506 min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height;
507 if (fmt.fmt.pix.sizeimage &lt; min)
508 fmt.fmt.pix.sizeimage = min;
509
510 switch (io) {
511 case IO_METHOD_READ:
512 init_read(fmt.fmt.pix.sizeimage);
513 break;
514
515 case IO_METHOD_MMAP:
516 init_mmap();
517 break;
518
519 case IO_METHOD_USERPTR:
520 init_userp(fmt.fmt.pix.sizeimage);
521 break;
522 }
523}
524
525static void close_device(void)
526{
527 if (-1 == close(fd))
528 errno_exit("close");
529
530 fd = -1;
531}
532
533static void open_device(void)
534{
535 struct stat st;
536
537 if (-1 == stat(dev_name, &amp;st)) {
538 fprintf(stderr, "Cannot identify '%s': %d, %s\n",
539 dev_name, errno, strerror(errno));
540 exit(EXIT_FAILURE);
541 }
542
543 if (!S_ISCHR(st.st_mode)) {
544 fprintf(stderr, "%s is no device\n", dev_name);
545 exit(EXIT_FAILURE);
546 }
547
548 fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0);
549
550 if (-1 == fd) {
551 fprintf(stderr, "Cannot open '%s': %d, %s\n",
552 dev_name, errno, strerror(errno));
553 exit(EXIT_FAILURE);
554 }
555}
556
557static void usage(FILE *fp, int argc, char **argv)
558{
559 fprintf(fp,
560 "Usage: %s [options]\n\n"
561 "Version 1.3\n"
562 "Options:\n"
563 "-d | --device name Video device name [%s]\n"
564 "-h | --help Print this message\n"
565 "-m | --mmap Use memory mapped buffers [default]\n"
566 "-r | --read Use read() calls\n"
567 "-u | --userp Use application allocated buffers\n"
568 "-o | --output Outputs stream to stdout\n"
569 "-f | --format Force format to 640x480 YUYV\n"
570 "-c | --count Number of frames to grab [%i]\n"
571 "",
572 argv[0], dev_name, frame_count);
573}
574
575static const char short_options[] = "d:hmruofc:";
576
577static const struct option
578long_options[] = {
579 { "device", required_argument, NULL, 'd' },
580 { "help", no_argument, NULL, 'h' },
581 { "mmap", no_argument, NULL, 'm' },
582 { "read", no_argument, NULL, 'r' },
583 { "userp", no_argument, NULL, 'u' },
584 { "output", no_argument, NULL, 'o' },
585 { "format", no_argument, NULL, 'f' },
586 { "count", required_argument, NULL, 'c' },
587 { 0, 0, 0, 0 }
588};
589
590int main(int argc, char **argv)
591{
592 dev_name = "/dev/video0";
593
594 for (;;) {
595 int idx;
596 int c;
597
598 c = getopt_long(argc, argv,
599 short_options, long_options, &amp;idx);
600
601 if (-1 == c)
602 break;
603
604 switch (c) {
605 case 0: /* getopt_long() flag */
606 break;
607
608 case 'd':
609 dev_name = optarg;
610 break;
611
612 case 'h':
613 usage(stdout, argc, argv);
614 exit(EXIT_SUCCESS);
615
616 case 'm':
617 io = IO_METHOD_MMAP;
618 break;
619
620 case 'r':
621 io = IO_METHOD_READ;
622 break;
623
624 case 'u':
625 io = IO_METHOD_USERPTR;
626 break;
627
628 case 'o':
629 out_buf++;
630 break;
631
632 case 'f':
633 force_format++;
634 break;
635
636 case 'c':
637 errno = 0;
638 frame_count = strtol(optarg, NULL, 0);
639 if (errno)
640 errno_exit(optarg);
641 break;
642
643 default:
644 usage(stderr, argc, argv);
645 exit(EXIT_FAILURE);
646 }
647 }
648
649 open_device();
650 init_device();
651 start_capturing();
652 mainloop();
653 stop_capturing();
654 uninit_device();
655 close_device();
656 fprintf(stderr, "\n");
657 return 0;
658}
659</programlisting>
diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
new file mode 100644
index 000000000000..9028721438dc
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -0,0 +1,1197 @@
1 <title>Common API Elements</title>
2
3 <para>Programming a V4L2 device consists of these
4steps:</para>
5
6 <itemizedlist>
7 <listitem>
8 <para>Opening the device</para>
9 </listitem>
10 <listitem>
11 <para>Changing device properties, selecting a video and audio
12input, video standard, picture brightness a.&nbsp;o.</para>
13 </listitem>
14 <listitem>
15 <para>Negotiating a data format</para>
16 </listitem>
17 <listitem>
18 <para>Negotiating an input/output method</para>
19 </listitem>
20 <listitem>
21 <para>The actual input/output loop</para>
22 </listitem>
23 <listitem>
24 <para>Closing the device</para>
25 </listitem>
26 </itemizedlist>
27
28 <para>In practice most steps are optional and can be executed out of
29order. It depends on the V4L2 device type, you can read about the
30details in <xref linkend="devices" />. In this chapter we will discuss
31the basic concepts applicable to all devices.</para>
32
33 <section id="open">
34 <title>Opening and Closing Devices</title>
35
36 <section>
37 <title>Device Naming</title>
38
39 <para>V4L2 drivers are implemented as kernel modules, loaded
40manually by the system administrator or automatically when a device is
41first opened. The driver modules plug into the "videodev" kernel
42module. It provides helper functions and a common application
43interface specified in this document.</para>
44
45 <para>Each driver thus loaded registers one or more device nodes
46with major number 81 and a minor number between 0 and 255. Assigning
47minor numbers to V4L2 devices is entirely up to the system administrator,
48this is primarily intended to solve conflicts between devices.<footnote>
49 <para>Access permissions are associated with character
50device special files, hence we must ensure device numbers cannot
51change with the module load order. To this end minor numbers are no
52longer automatically assigned by the "videodev" module as in V4L but
53requested by the driver. The defaults will suffice for most people
54unless two drivers compete for the same minor numbers.</para>
55 </footnote> The module options to select minor numbers are named
56after the device special file with a "_nr" suffix. For example "video_nr"
57for <filename>/dev/video</filename> video capture devices. The number is
58an offset to the base minor number associated with the device type.
59<footnote>
60 <para>In earlier versions of the V4L2 API the module options
61where named after the device special file with a "unit_" prefix, expressing
62the minor number itself, not an offset. Rationale for this change is unknown.
63Lastly the naming and semantics are just a convention among driver writers,
64the point to note is that minor numbers are not supposed to be hardcoded
65into drivers.</para>
66 </footnote> When the driver supports multiple devices of the same
67type more than one minor number can be assigned, separated by commas:
68<informalexample>
69 <screen>
70&gt; insmod mydriver.o video_nr=0,1 radio_nr=0,1</screen>
71 </informalexample></para>
72
73 <para>In <filename>/etc/modules.conf</filename> this may be
74written as: <informalexample>
75 <screen>
76alias char-major-81-0 mydriver
77alias char-major-81-1 mydriver
78alias char-major-81-64 mydriver <co id="alias" />
79options mydriver video_nr=0,1 radio_nr=0,1 <co id="options" />
80 </screen>
81 <calloutlist>
82 <callout arearefs="alias">
83 <para>When an application attempts to open a device
84special file with major number 81 and minor number 0, 1, or 64, load
85"mydriver" (and the "videodev" module it depends upon).</para>
86 </callout>
87 <callout arearefs="options">
88 <para>Register the first two video capture devices with
89minor number 0 and 1 (base number is 0), the first two radio device
90with minor number 64 and 65 (base 64).</para>
91 </callout>
92 </calloutlist>
93 </informalexample> When no minor number is given as module
94option the driver supplies a default. <xref linkend="devices" />
95recommends the base minor numbers to be used for the various device
96types. Obviously minor numbers must be unique. When the number is
97already in use the <emphasis>offending device</emphasis> will not be
98registered. <!-- Blessed by Linus Torvalds on
99linux-kernel@vger.kernel.org, 2002-11-20. --></para>
100
101 <para>By convention system administrators create various
102character device special files with these major and minor numbers in
103the <filename>/dev</filename> directory. The names recommended for the
104different V4L2 device types are listed in <xref linkend="devices" />.
105</para>
106
107 <para>The creation of character special files (with
108<application>mknod</application>) is a privileged operation and
109devices cannot be opened by major and minor number. That means
110applications cannot <emphasis>reliable</emphasis> scan for loaded or
111installed drivers. The user must enter a device name, or the
112application can try the conventional device names.</para>
113
114 <para>Under the device filesystem (devfs) the minor number
115options are ignored. V4L2 drivers (or by proxy the "videodev" module)
116automatically create the required device files in the
117<filename>/dev/v4l</filename> directory using the conventional device
118names above.</para>
119 </section>
120
121 <section id="related">
122 <title>Related Devices</title>
123
124 <para>Devices can support several related functions. For example
125video capturing, video overlay and VBI capturing are related because
126these functions share, amongst other, the same video input and tuner
127frequency. V4L and earlier versions of V4L2 used the same device name
128and minor number for video capturing and overlay, but different ones
129for VBI. Experience showed this approach has several problems<footnote>
130 <para>Given a device file name one cannot reliable find
131related devices. For once names are arbitrary and in a system with
132multiple devices, where only some support VBI capturing, a
133<filename>/dev/video2</filename> is not necessarily related to
134<filename>/dev/vbi2</filename>. The V4L
135<constant>VIDIOCGUNIT</constant> ioctl would require a search for a
136device file with a particular major and minor number.</para>
137 </footnote>, and to make things worse the V4L videodev module
138used to prohibit multiple opens of a device.</para>
139
140 <para>As a remedy the present version of the V4L2 API relaxed the
141concept of device types with specific names and minor numbers. For
142compatibility with old applications drivers must still register different
143minor numbers to assign a default function to the device. But if related
144functions are supported by the driver they must be available under all
145registered minor numbers. The desired function can be selected after
146opening the device as described in <xref linkend="devices" />.</para>
147
148 <para>Imagine a driver supporting video capturing, video
149overlay, raw VBI capturing, and FM radio reception. It registers three
150devices with minor number 0, 64 and 224 (this numbering scheme is
151inherited from the V4L API). Regardless if
152<filename>/dev/video</filename> (81, 0) or
153<filename>/dev/vbi</filename> (81, 224) is opened the application can
154select any one of the video capturing, overlay or VBI capturing
155functions. Without programming (e.&nbsp;g. reading from the device
156with <application>dd</application> or <application>cat</application>)
157<filename>/dev/video</filename> captures video images, while
158<filename>/dev/vbi</filename> captures raw VBI data.
159<filename>/dev/radio</filename> (81, 64) is invariable a radio device,
160unrelated to the video functions. Being unrelated does not imply the
161devices can be used at the same time, however. The &func-open;
162function may very well return an &EBUSY;.</para>
163
164 <para>Besides video input or output the hardware may also
165support audio sampling or playback. If so, these functions are
166implemented as OSS or ALSA PCM devices and eventually OSS or ALSA
167audio mixer. The V4L2 API makes no provisions yet to find these
168related devices. If you have an idea please write to the linux-media
169mailing list: &v4l-ml;.</para>
170 </section>
171
172 <section>
173 <title>Multiple Opens</title>
174
175 <para>In general, V4L2 devices can be opened more than once.
176When this is supported by the driver, users can for example start a
177"panel" application to change controls like brightness or audio
178volume, while another application captures video and audio. In other words, panel
179applications are comparable to an OSS or ALSA audio mixer application.
180When a device supports multiple functions like capturing and overlay
181<emphasis>simultaneously</emphasis>, multiple opens allow concurrent
182use of the device by forked processes or specialized applications.</para>
183
184 <para>Multiple opens are optional, although drivers should
185permit at least concurrent accesses without data exchange, &ie; panel
186applications. This implies &func-open; can return an &EBUSY; when the
187device is already in use, as well as &func-ioctl; functions initiating
188data exchange (namely the &VIDIOC-S-FMT; ioctl), and the &func-read;
189and &func-write; functions.</para>
190
191 <para>Mere opening a V4L2 device does not grant exclusive
192access.<footnote>
193 <para>Drivers could recognize the
194<constant>O_EXCL</constant> open flag. Presently this is not required,
195so applications cannot know if it really works.</para>
196 </footnote> Initiating data exchange however assigns the right
197to read or write the requested type of data, and to change related
198properties, to this file descriptor. Applications can request
199additional access privileges using the priority mechanism described in
200<xref linkend="app-pri" />.</para>
201 </section>
202
203 <section>
204 <title>Shared Data Streams</title>
205
206 <para>V4L2 drivers should not support multiple applications
207reading or writing the same data stream on a device by copying
208buffers, time multiplexing or similar means. This is better handled by
209a proxy application in user space. When the driver supports stream
210sharing anyway it must be implemented transparently. The V4L2 API does
211not specify how conflicts are solved. <!-- For example O_EXCL when the
212application does not want to be preempted, PROT_READ mmapped buffers
213which can be mapped twice, what happens when image formats do not
214match etc.--></para>
215 </section>
216
217 <section>
218 <title>Functions</title>
219
220 <para>To open and close V4L2 devices applications use the
221&func-open; and &func-close; function, respectively. Devices are
222programmed using the &func-ioctl; function as explained in the
223following sections.</para>
224 </section>
225 </section>
226
227 <section id="querycap">
228 <title>Querying Capabilities</title>
229
230 <para>Because V4L2 covers a wide variety of devices not all
231aspects of the API are equally applicable to all types of devices.
232Furthermore devices of the same type have different capabilities and
233this specification permits the omission of a few complicated and less
234important parts of the API.</para>
235
236 <para>The &VIDIOC-QUERYCAP; ioctl is available to check if the kernel
237device is compatible with this specification, and to query the <link
238linkend="devices">functions</link> and <link linkend="io">I/O
239methods</link> supported by the device. Other features can be queried
240by calling the respective ioctl, for example &VIDIOC-ENUMINPUT;
241to learn about the number, types and names of video connectors on the
242device. Although abstraction is a major objective of this API, the
243ioctl also allows driver specific applications to reliable identify
244the driver.</para>
245
246 <para>All V4L2 drivers must support
247<constant>VIDIOC_QUERYCAP</constant>. Applications should always call
248this ioctl after opening the device.</para>
249 </section>
250
251 <section id="app-pri">
252 <title>Application Priority</title>
253
254 <para>When multiple applications share a device it may be
255desirable to assign them different priorities. Contrary to the
256traditional "rm -rf /" school of thought a video recording application
257could for example block other applications from changing video
258controls or switching the current TV channel. Another objective is to
259permit low priority applications working in background, which can be
260preempted by user controlled applications and automatically regain
261control of the device at a later time.</para>
262
263 <para>Since these features cannot be implemented entirely in user
264space V4L2 defines the &VIDIOC-G-PRIORITY; and &VIDIOC-S-PRIORITY;
265ioctls to request and query the access priority associate with a file
266descriptor. Opening a device assigns a medium priority, compatible
267with earlier versions of V4L2 and drivers not supporting these ioctls.
268Applications requiring a different priority will usually call
269<constant>VIDIOC_S_PRIORITY</constant> after verifying the device with
270the &VIDIOC-QUERYCAP; ioctl.</para>
271
272 <para>Ioctls changing driver properties, such as &VIDIOC-S-INPUT;,
273return an &EBUSY; after another application obtained higher priority.
274An event mechanism to notify applications about asynchronous property
275changes has been proposed but not added yet.</para>
276 </section>
277
278 <section id="video">
279 <title>Video Inputs and Outputs</title>
280
281 <para>Video inputs and outputs are physical connectors of a
282device. These can be for example RF connectors (antenna/cable), CVBS
283a.k.a. Composite Video, S-Video or RGB connectors. Only video and VBI
284capture devices have inputs, output devices have outputs, at least one
285each. Radio devices have no video inputs or outputs.</para>
286
287 <para>To learn about the number and attributes of the
288available inputs and outputs applications can enumerate them with the
289&VIDIOC-ENUMINPUT; and &VIDIOC-ENUMOUTPUT; ioctl, respectively. The
290&v4l2-input; returned by the <constant>VIDIOC_ENUMINPUT</constant>
291ioctl also contains signal status information applicable when the
292current video input is queried.</para>
293
294 <para>The &VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; ioctl return the
295index of the current video input or output. To select a different
296input or output applications call the &VIDIOC-S-INPUT; and
297&VIDIOC-S-OUTPUT; ioctl. Drivers must implement all the input ioctls
298when the device has one or more inputs, all the output ioctls when the
299device has one or more outputs.</para>
300
301 <!--
302 <figure id=io-tree>
303 <title>Input and output enumeration is the root of most device properties.</title>
304 <mediaobject>
305 <imageobject>
306 <imagedata fileref="links.pdf" format="ps" />
307 </imageobject>
308 <imageobject>
309 <imagedata fileref="links.gif" format="gif" />
310 </imageobject>
311 <textobject>
312 <phrase>Links between various device property structures.</phrase>
313 </textobject>
314 </mediaobject>
315 </figure>
316 -->
317
318 <example>
319 <title>Information about the current video input</title>
320
321 <programlisting>
322&v4l2-input; input;
323int index;
324
325if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;index)) {
326 perror ("VIDIOC_G_INPUT");
327 exit (EXIT_FAILURE);
328}
329
330memset (&amp;input, 0, sizeof (input));
331input.index = index;
332
333if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
334 perror ("VIDIOC_ENUMINPUT");
335 exit (EXIT_FAILURE);
336}
337
338printf ("Current input: %s\n", input.name);
339 </programlisting>
340 </example>
341
342 <example>
343 <title>Switching to the first video input</title>
344
345 <programlisting>
346int index;
347
348index = 0;
349
350if (-1 == ioctl (fd, &VIDIOC-S-INPUT;, &amp;index)) {
351 perror ("VIDIOC_S_INPUT");
352 exit (EXIT_FAILURE);
353}
354 </programlisting>
355 </example>
356 </section>
357
358 <section id="audio">
359 <title>Audio Inputs and Outputs</title>
360
361 <para>Audio inputs and outputs are physical connectors of a
362device. Video capture devices have inputs, output devices have
363outputs, zero or more each. Radio devices have no audio inputs or
364outputs. They have exactly one tuner which in fact
365<emphasis>is</emphasis> an audio source, but this API associates
366tuners with video inputs or outputs only, and radio devices have
367none of these.<footnote>
368 <para>Actually &v4l2-audio; ought to have a
369<structfield>tuner</structfield> field like &v4l2-input;, not only
370making the API more consistent but also permitting radio devices with
371multiple tuners.</para>
372 </footnote> A connector on a TV card to loop back the received
373audio signal to a sound card is not considered an audio output.</para>
374
375 <para>Audio and video inputs and outputs are associated. Selecting
376a video source also selects an audio source. This is most evident when
377the video and audio source is a tuner. Further audio connectors can
378combine with more than one video input or output. Assumed two
379composite video inputs and two audio inputs exist, there may be up to
380four valid combinations. The relation of video and audio connectors
381is defined in the <structfield>audioset</structfield> field of the
382respective &v4l2-input; or &v4l2-output;, where each bit represents
383the index number, starting at zero, of one audio input or output.</para>
384
385 <para>To learn about the number and attributes of the
386available inputs and outputs applications can enumerate them with the
387&VIDIOC-ENUMAUDIO; and &VIDIOC-ENUMAUDOUT; ioctl, respectively. The
388&v4l2-audio; returned by the <constant>VIDIOC_ENUMAUDIO</constant> ioctl
389also contains signal status information applicable when the current
390audio input is queried.</para>
391
392 <para>The &VIDIOC-G-AUDIO; and &VIDIOC-G-AUDOUT; ioctl report
393the current audio input and output, respectively. Note that, unlike
394&VIDIOC-G-INPUT; and &VIDIOC-G-OUTPUT; these ioctls return a structure
395as <constant>VIDIOC_ENUMAUDIO</constant> and
396<constant>VIDIOC_ENUMAUDOUT</constant> do, not just an index.</para>
397
398 <para>To select an audio input and change its properties
399applications call the &VIDIOC-S-AUDIO; ioctl. To select an audio
400output (which presently has no changeable properties) applications
401call the &VIDIOC-S-AUDOUT; ioctl.</para>
402
403 <para>Drivers must implement all input ioctls when the device
404has one or more inputs, all output ioctls when the device has one
405or more outputs. When the device has any audio inputs or outputs the
406driver must set the <constant>V4L2_CAP_AUDIO</constant> flag in the
407&v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl.</para>
408
409 <example>
410 <title>Information about the current audio input</title>
411
412 <programlisting>
413&v4l2-audio; audio;
414
415memset (&amp;audio, 0, sizeof (audio));
416
417if (-1 == ioctl (fd, &VIDIOC-G-AUDIO;, &amp;audio)) {
418 perror ("VIDIOC_G_AUDIO");
419 exit (EXIT_FAILURE);
420}
421
422printf ("Current input: %s\n", audio.name);
423 </programlisting>
424 </example>
425
426 <example>
427 <title>Switching to the first audio input</title>
428
429 <programlisting>
430&v4l2-audio; audio;
431
432memset (&amp;audio, 0, sizeof (audio)); /* clear audio.mode, audio.reserved */
433
434audio.index = 0;
435
436if (-1 == ioctl (fd, &VIDIOC-S-AUDIO;, &amp;audio)) {
437 perror ("VIDIOC_S_AUDIO");
438 exit (EXIT_FAILURE);
439}
440 </programlisting>
441 </example>
442 </section>
443
444 <section id="tuner">
445 <title>Tuners and Modulators</title>
446
447 <section>
448 <title>Tuners</title>
449
450 <para>Video input devices can have one or more tuners
451demodulating a RF signal. Each tuner is associated with one or more
452video inputs, depending on the number of RF connectors on the tuner.
453The <structfield>type</structfield> field of the respective
454&v4l2-input; returned by the &VIDIOC-ENUMINPUT; ioctl is set to
455<constant>V4L2_INPUT_TYPE_TUNER</constant> and its
456<structfield>tuner</structfield> field contains the index number of
457the tuner.</para>
458
459 <para>Radio devices have exactly one tuner with index zero, no
460video inputs.</para>
461
462 <para>To query and change tuner properties applications use the
463&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The
464&v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also
465contains signal status information applicable when the tuner of the
466current video input, or a radio tuner is queried. Note that
467<constant>VIDIOC_S_TUNER</constant> does not switch the current tuner,
468when there is more than one at all. The tuner is solely determined by
469the current video input. Drivers must support both ioctls and set the
470<constant>V4L2_CAP_TUNER</constant> flag in the &v4l2-capability;
471returned by the &VIDIOC-QUERYCAP; ioctl when the device has one or
472more tuners.</para>
473 </section>
474
475 <section>
476 <title>Modulators</title>
477
478 <para>Video output devices can have one or more modulators, uh,
479modulating a video signal for radiation or connection to the antenna
480input of a TV set or video recorder. Each modulator is associated with
481one or more video outputs, depending on the number of RF connectors on
482the modulator. The <structfield>type</structfield> field of the
483respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is
484set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its
485<structfield>modulator</structfield> field contains the index number
486of the modulator. This specification does not define radio output
487devices.</para>
488
489 <para>To query and change modulator properties applications use
490the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that
491<constant>VIDIOC_S_MODULATOR</constant> does not switch the current
492modulator, when there is more than one at all. The modulator is solely
493determined by the current video output. Drivers must support both
494ioctls and set the <constant>V4L2_CAP_MODULATOR</constant> flag in
495the &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl when the
496device has one or more modulators.</para>
497 </section>
498
499 <section>
500 <title>Radio Frequency</title>
501
502 <para>To get and set the tuner or modulator radio frequency
503applications use the &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;
504ioctl which both take a pointer to a &v4l2-frequency;. These ioctls
505are used for TV and radio devices alike. Drivers must support both
506ioctls when the tuner or modulator ioctls are supported, or
507when the device is a radio device.</para>
508 </section>
509 </section>
510
511 <section id="standard">
512 <title>Video Standards</title>
513
514 <para>Video devices typically support one or more different video
515standards or variations of standards. Each video input and output may
516support another set of standards. This set is reported by the
517<structfield>std</structfield> field of &v4l2-input; and
518&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
519&VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
520
521 <para>V4L2 defines one bit for each analog video standard
522currently in use worldwide, and sets aside bits for driver defined
523standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
524and vice versa. Applications can use the predefined bits to select a
525particular standard, although presenting the user a menu of supported
526standards is preferred. To enumerate and query the attributes of the
527supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
528
529 <para>Many of the defined standards are actually just variations
530of a few major standards. The hardware may in fact not distinguish
531between them, or do so internal and switch automatically. Therefore
532enumerated standards also contain sets of one or more standard
533bits.</para>
534
535 <para>Assume a hypothetic tuner capable of demodulating B/PAL,
536G/PAL and I/PAL signals. The first enumerated standard is a set of B
537and G/PAL, switched automatically depending on the selected radio
538frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
539choice. Similar a Composite input may collapse standards, enumerating
540"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
541 <para>Some users are already confused by technical terms PAL,
542NTSC and SECAM. There is no point asking them to distinguish between
543B, G, D, or K when the software or hardware can do that
544automatically.</para>
545 </footnote></para>
546
547 <para>To query and select the standard used by the current video
548input or output applications call the &VIDIOC-G-STD; and
549&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
550standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote>
551 <para>An alternative to the current scheme is to use pointers
552to indices as arguments of <constant>VIDIOC_G_STD</constant> and
553<constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
554&v4l2-output; <structfield>std</structfield> field would be a set of
555indices like <structfield>audioset</structfield>.</para>
556 <para>Indices are consistent with the rest of the API
557and identify the standard unambiguously. In the present scheme of
558things an enumerated standard is looked up by &v4l2-std-id;. Now the
559standards supported by the inputs of a device can overlap. Just
560assume the tuner and composite input in the example above both
561exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
562a choice which does not exist. We cannot merge or omit sets, because
563applications would be unable to find the standards reported by
564<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
565for each input. Also selecting a standard by &v4l2-std-id; can be
566ambiguous. Advantage of this method is that applications need not
567identify the standard indirectly, after enumerating.</para><para>So in
568summary, the lookup itself is unavoidable. The difference is only
569whether the lookup is necessary to find an enumerated standard or to
570switch to a standard by &v4l2-std-id;.</para>
571 </footnote> Drivers must implement all video standard ioctls
572when the device has one or more video inputs or outputs.</para>
573
574 <para>Special rules apply to USB cameras where the notion of video
575standards makes little sense. More generally any capture device,
576output devices accordingly, which is <itemizedlist>
577 <listitem>
578 <para>incapable of capturing fields or frames at the nominal
579rate of the video standard, or</para>
580 </listitem>
581 <listitem>
582 <para>where <link linkend="buffer">timestamps</link> refer
583to the instant the field or frame was received by the driver, not the
584capture time, or</para>
585 </listitem>
586 <listitem>
587 <para>where <link linkend="buffer">sequence numbers</link>
588refer to the frames received by the driver, not the captured
589frames.</para>
590 </listitem>
591 </itemizedlist> Here the driver shall set the
592<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
593to zero, the <constant>VIDIOC_G_STD</constant>,
594<constant>VIDIOC_S_STD</constant>,
595<constant>VIDIOC_QUERYSTD</constant> and
596<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
597&EINVAL;.<footnote>
598 <para>See <xref linkend="buffer" /> for a rationale. Probably
599even USB cameras follow some well known video standard. It might have
600been better to explicitly indicate elsewhere if a device cannot live
601up to normal expectations, instead of this exception.</para>
602 </footnote></para>
603
604 <example>
605 <title>Information about the current video standard</title>
606
607 <programlisting>
608&v4l2-std-id; std_id;
609&v4l2-standard; standard;
610
611if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
612 /* Note when VIDIOC_ENUMSTD always returns EINVAL this
613 is no video device or it falls under the USB exception,
614 and VIDIOC_G_STD returning EINVAL is no error. */
615
616 perror ("VIDIOC_G_STD");
617 exit (EXIT_FAILURE);
618}
619
620memset (&amp;standard, 0, sizeof (standard));
621standard.index = 0;
622
623while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
624 if (standard.id &amp; std_id) {
625 printf ("Current video standard: %s\n", standard.name);
626 exit (EXIT_SUCCESS);
627 }
628
629 standard.index++;
630}
631
632/* EINVAL indicates the end of the enumeration, which cannot be
633 empty unless this device falls under the USB exception. */
634
635if (errno == EINVAL || standard.index == 0) {
636 perror ("VIDIOC_ENUMSTD");
637 exit (EXIT_FAILURE);
638}
639 </programlisting>
640 </example>
641
642 <example>
643 <title>Listing the video standards supported by the current
644input</title>
645
646 <programlisting>
647&v4l2-input; input;
648&v4l2-standard; standard;
649
650memset (&amp;input, 0, sizeof (input));
651
652if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
653 perror ("VIDIOC_G_INPUT");
654 exit (EXIT_FAILURE);
655}
656
657if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
658 perror ("VIDIOC_ENUM_INPUT");
659 exit (EXIT_FAILURE);
660}
661
662printf ("Current input %s supports:\n", input.name);
663
664memset (&amp;standard, 0, sizeof (standard));
665standard.index = 0;
666
667while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
668 if (standard.id &amp; input.std)
669 printf ("%s\n", standard.name);
670
671 standard.index++;
672}
673
674/* EINVAL indicates the end of the enumeration, which cannot be
675 empty unless this device falls under the USB exception. */
676
677if (errno != EINVAL || standard.index == 0) {
678 perror ("VIDIOC_ENUMSTD");
679 exit (EXIT_FAILURE);
680}
681 </programlisting>
682 </example>
683
684 <example>
685 <title>Selecting a new video standard</title>
686
687 <programlisting>
688&v4l2-input; input;
689&v4l2-std-id; std_id;
690
691memset (&amp;input, 0, sizeof (input));
692
693if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
694 perror ("VIDIOC_G_INPUT");
695 exit (EXIT_FAILURE);
696}
697
698if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
699 perror ("VIDIOC_ENUM_INPUT");
700 exit (EXIT_FAILURE);
701}
702
703if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
704 fprintf (stderr, "Oops. B/G PAL is not supported.\n");
705 exit (EXIT_FAILURE);
706}
707
708/* Note this is also supposed to work when only B
709 <emphasis>or</emphasis> G/PAL is supported. */
710
711std_id = V4L2_STD_PAL_BG;
712
713if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
714 perror ("VIDIOC_S_STD");
715 exit (EXIT_FAILURE);
716}
717 </programlisting>
718 </example>
719 <section id="dv-timings">
720 <title>Digital Video (DV) Timings</title>
721 <para>
722 The video standards discussed so far has been dealing with Analog TV and the
723corresponding video timings. Today there are many more different hardware interfaces
724such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
725video signals and there is a need to extend the API to select the video timings
726for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
727the limited bits available, a new set of IOCTLs is added to set/get video timings at
728the input and output: </para><itemizedlist>
729 <listitem>
730 <para>DV Presets: Digital Video (DV) presets. These are IDs representing a
731video timing at the input/output. Presets are pre-defined timings implemented
732by the hardware according to video standards. A __u32 data type is used to represent
733a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
734to support as many different presets as needed.</para>
735 </listitem>
736 <listitem>
737 <para>Custom DV Timings: This will allow applications to define more detailed
738custom video timings for the interface. This includes parameters such as width, height,
739polarities, frontporch, backporch etc.
740 </para>
741 </listitem>
742 </itemizedlist>
743 <para>To enumerate and query the attributes of DV presets supported by a device,
744applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset,
745applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the
746&VIDIOC-S-DV-PRESET; ioctl.</para>
747 <para>To set custom DV timings for the device, applications use the
748&VIDIOC-S-DV-TIMINGS; ioctl and to get current custom DV timings they use the
749&VIDIOC-G-DV-TIMINGS; ioctl.</para>
750 <para>Applications can make use of the <xref linkend="input-capabilities" /> and
751<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
752video timings for the device.</para>
753 </section>
754 </section>
755
756 &sub-controls;
757
758 <section id="format">
759 <title>Data Formats</title>
760
761 <section>
762 <title>Data Format Negotiation</title>
763
764 <para>Different devices exchange different kinds of data with
765applications, for example video images, raw or sliced VBI data, RDS
766datagrams. Even within one kind many different formats are possible,
767in particular an abundance of image formats. Although drivers must
768provide a default and the selection persists across closing and
769reopening a device, applications should always negotiate a data format
770before engaging in data exchange. Negotiation means the application
771asks for a particular format and the driver selects and reports the
772best the hardware can do to satisfy the request. Of course
773applications can also just query the current selection.</para>
774
775 <para>A single mechanism exists to negotiate all data formats
776using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
777&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
778used to examine what the hardware <emphasis>could</emphasis> do,
779without actually selecting a new data format. The data formats
780supported by the V4L2 API are covered in the respective device section
781in <xref linkend="devices" />. For a closer look at image formats see
782<xref linkend="pixfmt" />.</para>
783
784 <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
785turning-point in the initialization sequence. Prior to this point
786multiple panel applications can access the same device concurrently to
787select the current input, change controls or modify other properties.
788The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
789(video data, VBI data etc.) exclusively to one file descriptor.</para>
790
791 <para>Exclusive means no other application, more precisely no
792other file descriptor, can grab this stream or change device
793properties inconsistent with the negotiated parameters. A video
794standard change for example, when the new standard uses a different
795number of scan lines, can invalidate the selected image format.
796Therefore only the file descriptor owning the stream can make
797invalidating changes. Accordingly multiple file descriptors which
798grabbed different logical streams prevent each other from interfering
799with their settings. When for example video overlay is about to start
800or already in progress, simultaneous video capturing may be restricted
801to the same cropping and image size.</para>
802
803 <para>When applications omit the
804<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
805implied by the next step, the selection of an I/O method with the
806&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
807&func-write; call.</para>
808
809 <para>Generally only one logical stream can be assigned to a
810file descriptor, the exception being drivers permitting simultaneous
811video capturing and overlay using the same file descriptor for
812compatibility with V4L and earlier versions of V4L2. Switching the
813logical stream or returning into "panel mode" is possible by closing
814and reopening the device. Drivers <emphasis>may</emphasis> support a
815switch using <constant>VIDIOC_S_FMT</constant>.</para>
816
817 <para>All drivers exchanging data with
818applications must support the <constant>VIDIOC_G_FMT</constant> and
819<constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
820<constant>VIDIOC_TRY_FMT</constant> is highly recommended but
821optional.</para>
822 </section>
823
824 <section>
825 <title>Image Format Enumeration</title>
826
827 <para>Apart of the generic format negotiation functions
828a special ioctl to enumerate all image formats supported by video
829capture, overlay or output devices is available.<footnote>
830 <para>Enumerating formats an application has no a-priori
831knowledge of (otherwise it could explicitly ask for them and need not
832enumerate) seems useless, but there are applications serving as proxy
833between drivers and the actual video applications for which this is
834useful.</para>
835 </footnote></para>
836
837 <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
838by all drivers exchanging image data with applications.</para>
839
840 <important>
841 <para>Drivers are not supposed to convert image formats in
842kernel space. They must enumerate only formats directly supported by
843the hardware. If necessary driver writers should publish an example
844conversion routine or library for integration into applications.</para>
845 </important>
846 </section>
847 </section>
848
849 &sub-planar-apis;
850
851 <section id="crop">
852 <title>Image Cropping, Insertion and Scaling</title>
853
854 <para>Some video capture devices can sample a subsection of the
855picture and shrink or enlarge it to an image of arbitrary size. We
856call these abilities cropping and scaling. Some video output devices
857can scale an image up or down and insert it at an arbitrary scan line
858and horizontal offset into a video signal.</para>
859
860 <para>Applications can use the following API to select an area in
861the video signal, query the default area and the hardware limits.
862<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
863and &VIDIOC-S-CROP; ioctls apply to input as well as output
864devices.</emphasis></para>
865
866 <para>Scaling requires a source and a target. On a video capture
867or overlay device the source is the video signal, and the cropping
868ioctls determine the area actually sampled. The target are images
869read by the application or overlaid onto the graphics screen. Their
870size (and position for an overlay) is negotiated with the
871&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
872
873 <para>On a video output device the source are the images passed in
874by the application, and their size is again negotiated with the
875<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
876compressed video stream. The target is the video signal, and the
877cropping ioctls determine the area where the images are
878inserted.</para>
879
880 <para>Source and target rectangles are defined even if the device
881does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
882ioctls. Their size (and position where applicable) will be fixed in
883this case. <emphasis>All capture and output device must support the
884<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
885determine if scaling takes place.</emphasis></para>
886
887 <section>
888 <title>Cropping Structures</title>
889
890 <figure id="crop-scale">
891 <title>Image Cropping, Insertion and Scaling</title>
892 <mediaobject>
893 <imageobject>
894 <imagedata fileref="crop.pdf" format="PS" />
895 </imageobject>
896 <imageobject>
897 <imagedata fileref="crop.gif" format="GIF" />
898 </imageobject>
899 <textobject>
900 <phrase>The cropping, insertion and scaling process</phrase>
901 </textobject>
902 </mediaobject>
903 </figure>
904
905 <para>For capture devices the coordinates of the top left
906corner, width and height of the area which can be sampled is given by
907the <structfield>bounds</structfield> substructure of the
908&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
909ioctl. To support a wide range of hardware this specification does not
910define an origin or units. However by convention drivers should
911horizontally count unscaled samples relative to 0H (the leading edge
912of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
913Vertically ITU-R line
914numbers of the first field (<xref linkend="vbi-525" />, <xref
915linkend="vbi-625" />), multiplied by two if the driver can capture both
916fields.</para>
917
918 <para>The top left corner, width and height of the source
919rectangle, that is the area actually sampled, is given by &v4l2-crop;
920using the same coordinate system as &v4l2-cropcap;. Applications can
921use the <constant>VIDIOC_G_CROP</constant> and
922<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
923rectangle. It must lie completely within the capture boundaries and
924the driver may further adjust the requested size and/or position
925according to hardware limitations.</para>
926
927 <para>Each capture device has a default source rectangle, given
928by the <structfield>defrect</structfield> substructure of
929&v4l2-cropcap;. The center of this rectangle shall align with the
930center of the active picture area of the video signal, and cover what
931the driver writer considers the complete picture. Drivers shall reset
932the source rectangle to the default when the driver is first loaded,
933but not later.</para>
934
935 <para>For output devices these structures and ioctls are used
936accordingly, defining the <emphasis>target</emphasis> rectangle where
937the images will be inserted into the video signal.</para>
938
939 </section>
940
941 <section>
942 <title>Scaling Adjustments</title>
943
944 <para>Video hardware can have various cropping, insertion and
945scaling limitations. It may only scale up or down, support only
946discrete scaling factors, or have different scaling abilities in
947horizontal and vertical direction. Also it may not support scaling at
948all. At the same time the &v4l2-crop; rectangle may have to be
949aligned, and both the source and target rectangles may have arbitrary
950upper and lower size limits. In particular the maximum
951<structfield>width</structfield> and <structfield>height</structfield>
952in &v4l2-crop; may be smaller than the
953&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
954usual, drivers are expected to adjust the requested parameters and
955return the actual values selected.</para>
956
957 <para>Applications can change the source or the target rectangle
958first, as they may prefer a particular image size or a certain area in
959the video signal. If the driver has to adjust both to satisfy hardware
960limitations, the last requested rectangle shall take priority, and the
961driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
962ioctl however shall not change the driver state and therefore only
963adjust the requested rectangle.</para>
964
965 <para>Suppose scaling on a video capture device is restricted to
966a factor 1:1 or 2:1 in either direction and the target image size must
967be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
968rectangle is set to defaults, which are also the upper limit in this
969example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
970application requests an image size of 300&nbsp;&times;&nbsp;225
971pixels, assuming video will be scaled down from the "full picture"
972accordingly. The driver sets the image size to the closest possible
973values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
974closest to the requested size, that is 608&nbsp;&times;&nbsp;224
975(224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
9760,&nbsp;0 is still valid, thus unmodified. Given the default cropping
977rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
978application can easily propose another offset to center the cropping
979rectangle.</para>
980
981 <para>Now the application may insist on covering an area using a
982picture aspect ratio closer to the original request, so it asks for a
983cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
984scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
985driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
986the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
987
988 </section>
989
990 <section>
991 <title>Examples</title>
992
993 <para>Source and target rectangles shall remain unchanged across
994closing and reopening a device, such that piping data into or out of a
995device will work without special preparations. More advanced
996applications should ensure the parameters are suitable before starting
997I/O.</para>
998
999 <example>
1000 <title>Resetting the cropping parameters</title>
1001
1002 <para>(A video capture device is assumed; change
1003<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
1004devices.)</para>
1005
1006 <programlisting>
1007&v4l2-cropcap; cropcap;
1008&v4l2-crop; crop;
1009
1010memset (&amp;cropcap, 0, sizeof (cropcap));
1011cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1012
1013if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1014 perror ("VIDIOC_CROPCAP");
1015 exit (EXIT_FAILURE);
1016}
1017
1018memset (&amp;crop, 0, sizeof (crop));
1019crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1020crop.c = cropcap.defrect;
1021
1022/* Ignore if cropping is not supported (EINVAL). */
1023
1024if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
1025 &amp;&amp; errno != EINVAL) {
1026 perror ("VIDIOC_S_CROP");
1027 exit (EXIT_FAILURE);
1028}
1029 </programlisting>
1030 </example>
1031
1032 <example>
1033 <title>Simple downscaling</title>
1034
1035 <para>(A video capture device is assumed.)</para>
1036
1037 <programlisting>
1038&v4l2-cropcap; cropcap;
1039&v4l2-format; format;
1040
1041reset_cropping_parameters ();
1042
1043/* Scale down to 1/4 size of full picture. */
1044
1045memset (&amp;format, 0, sizeof (format)); /* defaults */
1046
1047format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1048
1049format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
1050format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
1051format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1052
1053if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
1054 perror ("VIDIOC_S_FORMAT");
1055 exit (EXIT_FAILURE);
1056}
1057
1058/* We could check the actual image size now, the actual scaling factor
1059 or if the driver can scale at all. */
1060 </programlisting>
1061 </example>
1062
1063 <example>
1064 <title>Selecting an output area</title>
1065
1066 <programlisting>
1067&v4l2-cropcap; cropcap;
1068&v4l2-crop; crop;
1069
1070memset (&amp;cropcap, 0, sizeof (cropcap));
1071cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1072
1073if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
1074 perror ("VIDIOC_CROPCAP");
1075 exit (EXIT_FAILURE);
1076}
1077
1078memset (&amp;crop, 0, sizeof (crop));
1079
1080crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1081crop.c = cropcap.defrect;
1082
1083/* Scale the width and height to 50 % of their original size
1084 and center the output. */
1085
1086crop.c.width /= 2;
1087crop.c.height /= 2;
1088crop.c.left += crop.c.width / 2;
1089crop.c.top += crop.c.height / 2;
1090
1091/* Ignore if cropping is not supported (EINVAL). */
1092
1093if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1094 &amp;&amp; errno != EINVAL) {
1095 perror ("VIDIOC_S_CROP");
1096 exit (EXIT_FAILURE);
1097}
1098</programlisting>
1099 </example>
1100
1101 <example>
1102 <title>Current scaling factor and pixel aspect</title>
1103
1104 <para>(A video capture device is assumed.)</para>
1105
1106 <programlisting>
1107&v4l2-cropcap; cropcap;
1108&v4l2-crop; crop;
1109&v4l2-format; format;
1110double hscale, vscale;
1111double aspect;
1112int dwidth, dheight;
1113
1114memset (&amp;cropcap, 0, sizeof (cropcap));
1115cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1116
1117if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1118 perror ("VIDIOC_CROPCAP");
1119 exit (EXIT_FAILURE);
1120}
1121
1122memset (&amp;crop, 0, sizeof (crop));
1123crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1124
1125if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1126 if (errno != EINVAL) {
1127 perror ("VIDIOC_G_CROP");
1128 exit (EXIT_FAILURE);
1129 }
1130
1131 /* Cropping not supported. */
1132 crop.c = cropcap.defrect;
1133}
1134
1135memset (&amp;format, 0, sizeof (format));
1136format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1137
1138if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1139 perror ("VIDIOC_G_FMT");
1140 exit (EXIT_FAILURE);
1141}
1142
1143/* The scaling applied by the driver. */
1144
1145hscale = format.fmt.pix.width / (double) crop.c.width;
1146vscale = format.fmt.pix.height / (double) crop.c.height;
1147
1148aspect = cropcap.pixelaspect.numerator /
1149 (double) cropcap.pixelaspect.denominator;
1150aspect = aspect * hscale / vscale;
1151
1152/* Devices following ITU-R BT.601 do not capture
1153 square pixels. For playback on a computer monitor
1154 we should scale the images to this size. */
1155
1156dwidth = format.fmt.pix.width / aspect;
1157dheight = format.fmt.pix.height;
1158 </programlisting>
1159 </example>
1160 </section>
1161 </section>
1162
1163 <section id="streaming-par">
1164 <title>Streaming Parameters</title>
1165
1166 <para>Streaming parameters are intended to optimize the video
1167capture process as well as I/O. Presently applications can request a
1168high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1169
1170 <para>The current video standard determines a nominal number of
1171frames per second. If less than this number of frames is to be
1172captured or output, applications can request frame skipping or
1173duplicating on the driver side. This is especially useful when using
1174the &func-read; or &func-write;, which are not augmented by timestamps
1175or sequence counters, and to avoid unnecessary data copying.</para>
1176
1177 <para>Finally these ioctls can be used to determine the number of
1178buffers used internally by a driver in read/write mode. For
1179implications see the section discussing the &func-read;
1180function.</para>
1181
1182 <para>To get and set the streaming parameters applications call
1183the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1184a pointer to a &v4l2-streamparm;, which contains a union holding
1185separate parameters for input and output devices.</para>
1186
1187 <para>These ioctls are optional, drivers need not implement
1188them. If so, they return the &EINVAL;.</para>
1189 </section>
1190
1191 <!--
1192Local Variables:
1193mode: sgml
1194sgml-parent-document: "v4l2.sgml"
1195indent-tabs-mode: nil
1196End:
1197 -->
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
new file mode 100644
index 000000000000..9f7cd4f25792
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -0,0 +1,2500 @@
1 <title>Changes</title>
2
3 <para>The following chapters document the evolution of the V4L2 API,
4errata or extensions. They are also intended to help application and
5driver writers to port or update their code.</para>
6
7 <section id="diff-v4l">
8 <title>Differences between V4L and V4L2</title>
9
10 <para>The Video For Linux API was first introduced in Linux 2.1 to
11unify and replace various TV and radio device related interfaces,
12developed independently by driver writers in prior years. Starting
13with Linux 2.5 the much improved V4L2 API replaces the V4L API,
14although existing drivers will continue to support V4L applications in
15the future, either directly or through the V4L2 compatibility layer in
16the <filename>videodev</filename> kernel module translating ioctls on
17the fly. For a transition period not all drivers will support the V4L2
18API.</para>
19
20 <section>
21 <title>Opening and Closing Devices</title>
22
23 <para>For compatibility reasons the character device file names
24recommended for V4L2 video capture, overlay, radio and raw
25vbi capture devices did not change from those used by V4L. They are
26listed in <xref linkend="devices" /> and below in <xref
27 linkend="v4l-dev" />.</para>
28
29 <para>The teletext devices (minor range 192-223) have been removed in
30V4L2 and no longer exist. There is no hardware available anymore for handling
31pure teletext. Instead raw or sliced VBI is used.</para>
32
33 <para>The V4L <filename>videodev</filename> module automatically
34assigns minor numbers to drivers in load order, depending on the
35registered device type. We recommend that V4L2 drivers by default
36register devices with the same numbers, but the system administrator
37can assign arbitrary minor numbers using driver module options. The
38major device number remains 81.</para>
39
40 <table id="v4l-dev">
41 <title>V4L Device Types, Names and Numbers</title>
42 <tgroup cols="3">
43 <thead>
44 <row>
45 <entry>Device Type</entry>
46 <entry>File Name</entry>
47 <entry>Minor Numbers</entry>
48 </row>
49 </thead>
50 <tbody valign="top">
51 <row>
52 <entry>Video capture and overlay</entry>
53 <entry><para><filename>/dev/video</filename> and
54<filename>/dev/bttv0</filename><footnote> <para>According to
55Documentation/devices.txt these should be symbolic links to
56<filename>/dev/video0</filename>. Note the original bttv interface is
57not compatible with V4L or V4L2.</para> </footnote>,
58<filename>/dev/video0</filename> to
59<filename>/dev/video63</filename></para></entry>
60 <entry>0-63</entry>
61 </row>
62 <row>
63 <entry>Radio receiver</entry>
64 <entry><para><filename>/dev/radio</filename><footnote>
65 <para>According to
66<filename>Documentation/devices.txt</filename> a symbolic link to
67<filename>/dev/radio0</filename>.</para>
68 </footnote>, <filename>/dev/radio0</filename> to
69<filename>/dev/radio63</filename></para></entry>
70 <entry>64-127</entry>
71 </row>
72 <row>
73 <entry>Raw VBI capture</entry>
74 <entry><para><filename>/dev/vbi</filename>,
75<filename>/dev/vbi0</filename> to
76<filename>/dev/vbi31</filename></para></entry>
77 <entry>224-255</entry>
78 </row>
79 </tbody>
80 </tgroup>
81 </table>
82
83 <para>V4L prohibits (or used to prohibit) multiple opens of a
84device file. V4L2 drivers <emphasis>may</emphasis> support multiple
85opens, see <xref linkend="open" /> for details and consequences.</para>
86
87 <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;. The
88compatibility layer in the V4L2 <filename>videodev</filename> module
89can translate V4L ioctl requests to their V4L2 counterpart, however a
90V4L2 driver usually needs more preparation to become fully V4L
91compatible. This is covered in more detail in <xref
92 linkend="driver" />.</para>
93 </section>
94
95 <section>
96 <title>Querying Capabilities</title>
97
98 <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is
99equivalent to V4L2's &VIDIOC-QUERYCAP;.</para>
100
101 <para>The <structfield>name</structfield> field in struct
102<structname>video_capability</structname> became
103<structfield>card</structfield> in &v4l2-capability;,
104<structfield>type</structfield> was replaced by
105<structfield>capabilities</structfield>. Note V4L2 does not
106distinguish between device types like this, better think of basic
107video input, video output and radio devices supporting a set of
108related functions like video capturing, video overlay and VBI
109capturing. See <xref linkend="open" /> for an
110introduction.<informaltable>
111 <tgroup cols="3">
112 <thead>
113 <row>
114 <entry>struct
115<structname>video_capability</structname>
116<structfield>type</structfield></entry>
117 <entry>&v4l2-capability;
118<structfield>capabilities</structfield> flags</entry>
119 <entry>Purpose</entry>
120 </row>
121 </thead>
122 <tbody valign="top">
123 <row>
124 <entry><constant>VID_TYPE_CAPTURE</constant></entry>
125 <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
126 <entry>The <link linkend="capture">video
127capture</link> interface is supported.</entry>
128 </row>
129 <row>
130 <entry><constant>VID_TYPE_TUNER</constant></entry>
131 <entry><constant>V4L2_CAP_TUNER</constant></entry>
132 <entry>The device has a <link linkend="tuner">tuner or
133modulator</link>.</entry>
134 </row>
135 <row>
136 <entry><constant>VID_TYPE_TELETEXT</constant></entry>
137 <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
138 <entry>The <link linkend="raw-vbi">raw VBI
139capture</link> interface is supported.</entry>
140 </row>
141 <row>
142 <entry><constant>VID_TYPE_OVERLAY</constant></entry>
143 <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
144 <entry>The <link linkend="overlay">video
145overlay</link> interface is supported.</entry>
146 </row>
147 <row>
148 <entry><constant>VID_TYPE_CHROMAKEY</constant></entry>
149 <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in
150field <structfield>capability</structfield> of
151&v4l2-framebuffer;</entry>
152 <entry>Whether chromakey overlay is supported. For
153more information on overlay see
154<xref linkend="overlay" />.</entry>
155 </row>
156 <row>
157 <entry><constant>VID_TYPE_CLIPPING</constant></entry>
158 <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant>
159and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field
160<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
161 <entry>Whether clipping the overlaid image is
162supported, see <xref linkend="overlay" />.</entry>
163 </row>
164 <row>
165 <entry><constant>VID_TYPE_FRAMERAM</constant></entry>
166 <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
167<emphasis>not set</emphasis> in field
168<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
169 <entry>Whether overlay overwrites frame buffer memory,
170see <xref linkend="overlay" />.</entry>
171 </row>
172 <row>
173 <entry><constant>VID_TYPE_SCALES</constant></entry>
174 <entry><constant>-</constant></entry>
175 <entry>This flag indicates if the hardware can scale
176images. The V4L2 API implies the scale factor by setting the cropping
177dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT;
178ioctl, respectively. The driver returns the closest sizes possible.
179For more information on cropping and scaling see <xref
180 linkend="crop" />.</entry>
181 </row>
182 <row>
183 <entry><constant>VID_TYPE_MONOCHROME</constant></entry>
184 <entry><constant>-</constant></entry>
185 <entry>Applications can enumerate the supported image
186formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
187supports grey scale capturing only. For more information on image
188formats see <xref linkend="pixfmt" />.</entry>
189 </row>
190 <row>
191 <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry>
192 <entry><constant>-</constant></entry>
193 <entry>Applications can call the &VIDIOC-G-CROP; ioctl
194to determine if the device supports capturing a subsection of the full
195picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;.
196For more information on cropping and scaling see <xref
197 linkend="crop" />.</entry>
198 </row>
199 <row>
200 <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry>
201 <entry><constant>-</constant></entry>
202 <entry>Applications can enumerate the supported image
203formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
204supports MPEG streams.</entry>
205 </row>
206 <row>
207 <entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry>
208 <entry><constant>-</constant></entry>
209 <entry>See above.</entry>
210 </row>
211 <row>
212 <entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry>
213 <entry><constant>-</constant></entry>
214 <entry>See above.</entry>
215 </row>
216 <row>
217 <entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry>
218 <entry><constant>-</constant></entry>
219 <entry>See above.</entry>
220 </row>
221 </tbody>
222 </tgroup>
223 </informaltable></para>
224
225 <para>The <structfield>audios</structfield> field was replaced
226by <structfield>capabilities</structfield> flag
227<constant>V4L2_CAP_AUDIO</constant>, indicating
228<emphasis>if</emphasis> the device has any audio inputs or outputs. To
229determine their number applications can enumerate audio inputs with
230the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref
231 linkend="audio" />.</para>
232
233 <para>The <structfield>maxwidth</structfield>,
234<structfield>maxheight</structfield>,
235<structfield>minwidth</structfield> and
236<structfield>minheight</structfield> fields were removed. Calling the
237&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions
238returns the closest size possible, taking into account the current
239video standard, cropping and scaling limitations.</para>
240 </section>
241
242 <section>
243 <title>Video Sources</title>
244
245 <para>V4L provides the <constant>VIDIOCGCHAN</constant> and
246<constant>VIDIOCSCHAN</constant> ioctl using struct
247<structname>video_channel</structname> to enumerate
248the video inputs of a V4L device. The equivalent V4L2 ioctls
249are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT;
250using &v4l2-input; as discussed in <xref linkend="video" />.</para>
251
252 <para>The <structfield>channel</structfield> field counting
253inputs was renamed to <structfield>index</structfield>, the video
254input types were renamed as follows: <informaltable>
255 <tgroup cols="2">
256 <thead>
257 <row>
258 <entry>struct <structname>video_channel</structname>
259<structfield>type</structfield></entry>
260 <entry>&v4l2-input;
261<structfield>type</structfield></entry>
262 </row>
263 </thead>
264 <tbody valign="top">
265 <row>
266 <entry><constant>VIDEO_TYPE_TV</constant></entry>
267 <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
268 </row>
269 <row>
270 <entry><constant>VIDEO_TYPE_CAMERA</constant></entry>
271 <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
272 </row>
273 </tbody>
274 </tgroup>
275 </informaltable></para>
276
277 <para>Unlike the <structfield>tuners</structfield> field
278expressing the number of tuners of this input, V4L2 assumes each video
279input is connected to at most one tuner. However a tuner can have more
280than one input, &ie; RF connectors, and a device can have multiple
281tuners. The index number of the tuner associated with the input, if
282any, is stored in field <structfield>tuner</structfield> of
283&v4l2-input;. Enumeration of tuners is discussed in <xref
284 linkend="tuner" />.</para>
285
286 <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was
287dropped. Video inputs associated with a tuner are of type
288<constant>V4L2_INPUT_TYPE_TUNER</constant>. The
289<constant>VIDEO_VC_AUDIO</constant> flag was replaced by the
290<structfield>audioset</structfield> field. V4L2 considers devices with
291up to 32 audio inputs. Each set bit in the
292<structfield>audioset</structfield> field represents one audio input
293this video input combines with. For information about audio inputs and
294how to switch between them see <xref linkend="audio" />.</para>
295
296 <para>The <structfield>norm</structfield> field describing the
297supported video standards was replaced by
298<structfield>std</structfield>. The V4L specification mentions a flag
299<constant>VIDEO_VC_NORM</constant> indicating whether the standard can
300be changed. This flag was a later addition together with the
301<structfield>norm</structfield> field and has been removed in the
302meantime. V4L2 has a similar, albeit more comprehensive approach
303to video standards, see <xref linkend="standard" /> for more
304information.</para>
305 </section>
306
307 <section>
308 <title>Tuning</title>
309
310 <para>The V4L <constant>VIDIOCGTUNER</constant> and
311<constant>VIDIOCSTUNER</constant> ioctl and struct
312<structname>video_tuner</structname> can be used to enumerate the
313tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
314&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are
315covered in <xref linkend="tuner" />.</para>
316
317 <para>The <structfield>tuner</structfield> field counting tuners
318was renamed to <structfield>index</structfield>. The fields
319<structfield>name</structfield>, <structfield>rangelow</structfield>
320and <structfield>rangehigh</structfield> remained unchanged.</para>
321
322 <para>The <constant>VIDEO_TUNER_PAL</constant>,
323<constant>VIDEO_TUNER_NTSC</constant> and
324<constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported
325video standards were dropped. This information is now contained in the
326associated &v4l2-input;. No replacement exists for the
327<constant>VIDEO_TUNER_NORM</constant> flag indicating whether the
328video standard can be switched. The <structfield>mode</structfield>
329field to select a different video standard was replaced by a whole new
330set of ioctls and structures described in <xref linkend="standard" />.
331Due to its ubiquity it should be mentioned the BTTV driver supports
332several standards in addition to the regular
333<constant>VIDEO_MODE_PAL</constant> (0),
334<constant>VIDEO_MODE_NTSC</constant>,
335<constant>VIDEO_MODE_SECAM</constant> and
336<constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina,
337M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para>
338
339 <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag
340indicating stereo reception became
341<constant>V4L2_TUNER_SUB_STEREO</constant> in field
342<structfield>rxsubchans</structfield>. This field also permits the
343detection of monaural and bilingual audio, see the definition of
344&v4l2-tuner; for details. Presently no replacement exists for the
345<constant>VIDEO_TUNER_RDS_ON</constant> and
346<constant>VIDEO_TUNER_MBS_ON</constant> flags.</para>
347
348 <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed
349to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner;
350<structfield>capability</structfield> field.</para>
351
352 <para>The <constant>VIDIOCGFREQ</constant> and
353<constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency
354where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They
355take a pointer to a &v4l2-frequency; instead of an unsigned long
356integer.</para>
357 </section>
358
359 <section id="v4l-image-properties">
360 <title>Image Properties</title>
361
362 <para>V4L2 has no equivalent of the
363<constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant>
364ioctl and struct <structname>video_picture</structname>. The following
365fields where replaced by V4L2 controls accessible with the
366&VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable>
367 <tgroup cols="2">
368 <thead>
369 <row>
370 <entry>struct <structname>video_picture</structname></entry>
371 <entry>V4L2 Control ID</entry>
372 </row>
373 </thead>
374 <tbody valign="top">
375 <row>
376 <entry><structfield>brightness</structfield></entry>
377 <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
378 </row>
379 <row>
380 <entry><structfield>hue</structfield></entry>
381 <entry><constant>V4L2_CID_HUE</constant></entry>
382 </row>
383 <row>
384 <entry><structfield>colour</structfield></entry>
385 <entry><constant>V4L2_CID_SATURATION</constant></entry>
386 </row>
387 <row>
388 <entry><structfield>contrast</structfield></entry>
389 <entry><constant>V4L2_CID_CONTRAST</constant></entry>
390 </row>
391 <row>
392 <entry><structfield>whiteness</structfield></entry>
393 <entry><constant>V4L2_CID_WHITENESS</constant></entry>
394 </row>
395 </tbody>
396 </tgroup>
397 </informaltable></para>
398
399 <para>The V4L picture controls are assumed to range from 0 to
40065535 with no particular reset value. The V4L2 API permits arbitrary
401limits and defaults which can be queried with the &VIDIOC-QUERYCTRL;
402ioctl. For general information about controls see <xref
403linkend="control" />.</para>
404
405 <para>The <structfield>depth</structfield> (average number of
406bits per pixel) of a video image is implied by the selected image
407format. V4L2 does not explicitely provide such information assuming
408applications recognizing the format are aware of the image depth and
409others need not know. The <structfield>palette</structfield> field
410moved into the &v4l2-pix-format;:<informaltable>
411 <tgroup cols="2">
412 <thead>
413 <row>
414 <entry>struct <structname>video_picture</structname>
415<structfield>palette</structfield></entry>
416 <entry>&v4l2-pix-format;
417<structfield>pixfmt</structfield></entry>
418 </row>
419 </thead>
420 <tbody valign="top">
421 <row>
422 <entry><constant>VIDEO_PALETTE_GREY</constant></entry>
423 <entry><para><link
424linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry>
425 </row>
426 <row>
427 <entry><constant>VIDEO_PALETTE_HI240</constant></entry>
428 <entry><para><link
429linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote>
430 <para>This is a custom format used by the BTTV
431driver, not one of the V4L2 standard formats.</para>
432 </footnote></para></entry>
433 </row>
434 <row>
435 <entry><constant>VIDEO_PALETTE_RGB565</constant></entry>
436 <entry><para><link
437linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry>
438 </row>
439 <row>
440 <entry><constant>VIDEO_PALETTE_RGB555</constant></entry>
441 <entry><para><link
442linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry>
443 </row>
444 <row>
445 <entry><constant>VIDEO_PALETTE_RGB24</constant></entry>
446 <entry><para><link
447linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry>
448 </row>
449 <row>
450 <entry><constant>VIDEO_PALETTE_RGB32</constant></entry>
451 <entry><para><link
452linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote>
453 <para>Presumably all V4L RGB formats are
454little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue
455swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para>
456 </footnote></para></entry>
457 </row>
458 <row>
459 <entry><constant>VIDEO_PALETTE_YUV422</constant></entry>
460 <entry><para><link
461linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
462 </row>
463 <row>
464 <entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote>
465 <para><constant>VIDEO_PALETTE_YUV422</constant>
466and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some
467V4L drivers respond to one, some to the other.</para>
468 </footnote></para></entry>
469 <entry><para><link
470linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
471 </row>
472 <row>
473 <entry><constant>VIDEO_PALETTE_UYVY</constant></entry>
474 <entry><para><link
475linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry>
476 </row>
477 <row>
478 <entry><constant>VIDEO_PALETTE_YUV420</constant></entry>
479 <entry>None</entry>
480 </row>
481 <row>
482 <entry><constant>VIDEO_PALETTE_YUV411</constant></entry>
483 <entry><para><link
484linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote>
485 <para>Not to be confused with
486<constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar
487format.</para> </footnote></para></entry>
488 </row>
489 <row>
490 <entry><constant>VIDEO_PALETTE_RAW</constant></entry>
491 <entry><para>None<footnote> <para>V4L explains this
492as: "RAW capture (BT848)"</para> </footnote></para></entry>
493 </row>
494 <row>
495 <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry>
496 <entry><para><link
497linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry>
498 </row>
499 <row>
500 <entry><constant>VIDEO_PALETTE_YUV411P</constant></entry>
501 <entry><para><link
502linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote>
503 <para>Not to be confused with
504<constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed
505format.</para> </footnote></para></entry>
506 </row>
507 <row>
508 <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry>
509 <entry><para><link
510linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry>
511 </row>
512 <row>
513 <entry><constant>VIDEO_PALETTE_YUV410P</constant></entry>
514 <entry><para><link
515linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry>
516 </row>
517 </tbody>
518 </tgroup>
519 </informaltable></para>
520
521 <para>V4L2 image formats are defined in <xref
522linkend="pixfmt" />. The image format can be selected with the
523&VIDIOC-S-FMT; ioctl.</para>
524 </section>
525
526 <section>
527 <title>Audio</title>
528
529 <para>The <constant>VIDIOCGAUDIO</constant> and
530<constant>VIDIOCSAUDIO</constant> ioctl and struct
531<structname>video_audio</structname> are used to enumerate the
532audio inputs of a V4L device. The equivalent V4L2 ioctls are
533&VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as
534discussed in <xref linkend="audio" />.</para>
535
536 <para>The <structfield>audio</structfield> "channel number"
537field counting audio inputs was renamed to
538<structfield>index</structfield>.</para>
539
540 <para>On <constant>VIDIOCSAUDIO</constant> the
541<structfield>mode</structfield> field selects <emphasis>one</emphasis>
542of the <constant>VIDEO_SOUND_MONO</constant>,
543<constant>VIDEO_SOUND_STEREO</constant>,
544<constant>VIDEO_SOUND_LANG1</constant> or
545<constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When
546the current audio standard is BTSC
547<constant>VIDEO_SOUND_LANG2</constant> refers to SAP and
548<constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also
549undocumented in the V4L specification, there is no way to query the
550selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns
551the <emphasis>actually received</emphasis> audio programmes in this
552field. In the V4L2 API this information is stored in the &v4l2-tuner;
553<structfield>rxsubchans</structfield> and
554<structfield>audmode</structfield> fields, respectively. See <xref
555linkend="tuner" /> for more information on tuners. Related to audio
556modes &v4l2-audio; also reports if this is a mono or stereo
557input, regardless if the source is a tuner.</para>
558
559 <para>The following fields where replaced by V4L2 controls
560accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and
561&VIDIOC-S-CTRL; ioctls:<informaltable>
562 <tgroup cols="2">
563 <thead>
564 <row>
565 <entry>struct
566<structname>video_audio</structname></entry>
567 <entry>V4L2 Control ID</entry>
568 </row>
569 </thead>
570 <tbody valign="top">
571 <row>
572 <entry><structfield>volume</structfield></entry>
573 <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
574 </row>
575 <row>
576 <entry><structfield>bass</structfield></entry>
577 <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
578 </row>
579 <row>
580 <entry><structfield>treble</structfield></entry>
581 <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
582 </row>
583 <row>
584 <entry><structfield>balance</structfield></entry>
585 <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
586 </row>
587 </tbody>
588 </tgroup>
589 </informaltable></para>
590
591 <para>To determine which of these controls are supported by a
592driver V4L provides the <structfield>flags</structfield>
593<constant>VIDEO_AUDIO_VOLUME</constant>,
594<constant>VIDEO_AUDIO_BASS</constant>,
595<constant>VIDEO_AUDIO_TREBLE</constant> and
596<constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the
597&VIDIOC-QUERYCTRL; ioctl reports if the respective control is
598supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant>
599and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the
600boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para>
601
602 <para>All V4L2 controls have a <structfield>step</structfield>
603attribute replacing the struct <structname>video_audio</structname>
604<structfield>step</structfield> field. The V4L audio controls are
605assumed to range from 0 to 65535 with no particular reset value. The
606V4L2 API permits arbitrary limits and defaults which can be queried
607with the &VIDIOC-QUERYCTRL; ioctl. For general information about
608controls see <xref linkend="control" />.</para>
609 </section>
610
611 <section>
612 <title>Frame Buffer Overlay</title>
613
614 <para>The V4L2 ioctls equivalent to
615<constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant>
616are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The
617<structfield>base</structfield> field of struct
618<structname>video_buffer</structname> remained unchanged, except V4L2
619defines a flag to indicate non-destructive overlays instead of a
620<constant>NULL</constant> pointer. All other fields moved into the
621&v4l2-pix-format; <structfield>fmt</structfield> substructure of
622&v4l2-framebuffer;. The <structfield>depth</structfield> field was
623replaced by <structfield>pixelformat</structfield>. See <xref
624 linkend="pixfmt-rgb" /> for a list of RGB formats and their
625respective color depths.</para>
626
627 <para>Instead of the special ioctls
628<constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant>
629V4L2 uses the general-purpose data format negotiation ioctls
630&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
631&v4l2-format; as argument. Here the <structfield>win</structfield>
632member of the <structfield>fmt</structfield> union is used, a
633&v4l2-window;.</para>
634
635 <para>The <structfield>x</structfield>,
636<structfield>y</structfield>, <structfield>width</structfield> and
637<structfield>height</structfield> fields of struct
638<structname>video_window</structname> moved into &v4l2-rect;
639substructure <structfield>w</structfield> of struct
640<structname>v4l2_window</structname>. The
641<structfield>chromakey</structfield>,
642<structfield>clips</structfield>, and
643<structfield>clipcount</structfield> fields remained unchanged. Struct
644<structname>video_clip</structname> was renamed to &v4l2-clip;, also
645containing a struct <structname>v4l2_rect</structname>, but the
646semantics are still the same.</para>
647
648 <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was
649dropped. Instead applications must set the
650<structfield>field</structfield> field to
651<constant>V4L2_FIELD_ANY</constant> or
652<constant>V4L2_FIELD_INTERLACED</constant>. The
653<constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into
654&v4l2-framebuffer;, under the new name
655<constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para>
656
657 <para>In V4L, storing a bitmap pointer in
658<structfield>clips</structfield> and setting
659<structfield>clipcount</structfield> to
660<constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap
661clipping, using a fixed size bitmap of 1024 &times; 625 bits. Struct
662<structname>v4l2_window</structname> has a separate
663<structfield>bitmap</structfield> pointer field for this purpose and
664the bitmap size is determined by <structfield>w.width</structfield> and
665<structfield>w.height</structfield>.</para>
666
667 <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or
668disable overlay was renamed to &VIDIOC-OVERLAY;.</para>
669 </section>
670
671 <section>
672 <title>Cropping</title>
673
674 <para>To capture only a subsection of the full picture V4L
675defines the <constant>VIDIOCGCAPTURE</constant> and
676<constant>VIDIOCSCAPTURE</constant> ioctls using struct
677<structname>video_capture</structname>. The equivalent V4L2 ioctls are
678&VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related
679&VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see
680<xref linkend="crop" /> for details.</para>
681
682 <para>The <structfield>x</structfield>,
683<structfield>y</structfield>, <structfield>width</structfield> and
684<structfield>height</structfield> fields moved into &v4l2-rect;
685substructure <structfield>c</structfield> of struct
686<structname>v4l2_crop</structname>. The
687<structfield>decimation</structfield> field was dropped. In the V4L2
688API the scaling factor is implied by the size of the cropping
689rectangle and the size of the captured or overlaid image.</para>
690
691 <para>The <constant>VIDEO_CAPTURE_ODD</constant>
692and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the
693odd or even field, respectively, were replaced by
694<constant>V4L2_FIELD_TOP</constant> and
695<constant>V4L2_FIELD_BOTTOM</constant> in the field named
696<structfield>field</structfield> of &v4l2-pix-format; and
697&v4l2-window;. These structures are used to select a capture or
698overlay format with the &VIDIOC-S-FMT; ioctl.</para>
699 </section>
700
701 <section>
702 <title>Reading Images, Memory Mapping</title>
703
704 <section>
705 <title>Capturing using the read method</title>
706
707 <para>There is no essential difference between reading images
708from a V4L or V4L2 device using the &func-read; function, however V4L2
709drivers are not required to support this I/O method. Applications can
710determine if the function is available with the &VIDIOC-QUERYCAP;
711ioctl. All V4L2 devices exchanging data with applications must support
712the &func-select; and &func-poll; functions.</para>
713
714 <para>To select an image format and size, V4L provides the
715<constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant>
716ioctls. V4L2 uses the general-purpose data format negotiation ioctls
717&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
718&v4l2-format; as argument, here the &v4l2-pix-format; named
719<structfield>pix</structfield> of its <structfield>fmt</structfield>
720union is used.</para>
721
722 <para>For more information about the V4L2 read interface see
723<xref linkend="rw" />.</para>
724 </section>
725 <section>
726 <title>Capturing using memory mapping</title>
727
728 <para>Applications can read from V4L devices by mapping
729buffers in device memory, or more often just buffers allocated in
730DMA-able system memory, into their address space. This avoids the data
731copying overhead of the read method. V4L2 supports memory mapping as
732well, with a few differences.</para>
733
734 <informaltable>
735 <tgroup cols="2">
736 <thead>
737 <row>
738 <entry>V4L</entry>
739 <entry>V4L2</entry>
740 </row>
741 </thead>
742 <tbody valign="top">
743 <row>
744 <entry></entry>
745 <entry>The image format must be selected before
746buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format
747is selected the driver may use the last, possibly by another
748application requested format.</entry>
749 </row>
750 <row>
751 <entry><para>Applications cannot change the number of
752buffers. The it is built into the driver, unless it has a module
753option to change the number when the driver module is
754loaded.</para></entry>
755 <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the
756desired number of buffers, this is a required step in the initialization
757sequence.</para></entry>
758 </row>
759 <row>
760 <entry><para>Drivers map all buffers as one contiguous
761range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is
762available to query the number of buffers, the offset of each buffer
763from the start of the virtual file, and the overall amount of memory
764used, which can be used as arguments for the &func-mmap;
765function.</para></entry>
766 <entry><para>Buffers are individually mapped. The
767offset and size of each buffer can be determined with the
768&VIDIOC-QUERYBUF; ioctl.</para></entry>
769 </row>
770 <row>
771 <entry><para>The <constant>VIDIOCMCAPTURE</constant>
772ioctl prepares a buffer for capturing. It also determines the image
773format for this buffer. The ioctl returns immediately, eventually with
774an &EAGAIN; if no video signal had been detected. When the driver
775supports more than one buffer applications can call the ioctl multiple
776times and thus have multiple outstanding capture
777requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl
778suspends execution until a particular buffer has been
779filled.</para></entry>
780 <entry><para>Drivers maintain an incoming and outgoing
781queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming
782queue. Filled buffers are dequeued from the outgoing queue with the
783&VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this
784function, &func-select; or &func-poll; can be used. The
785&VIDIOC-STREAMON; ioctl must be called once after enqueuing one or
786more buffers to start capturing. Its counterpart
787&VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both
788queues. Applications can query the signal status, if known, with the
789&VIDIOC-ENUMINPUT; ioctl.</para></entry>
790 </row>
791 </tbody>
792 </tgroup>
793 </informaltable>
794
795 <para>For a more in-depth discussion of memory mapping and
796examples, see <xref linkend="mmap" />.</para>
797 </section>
798 </section>
799
800 <section>
801 <title>Reading Raw VBI Data</title>
802
803 <para>Originally the V4L API did not specify a raw VBI capture
804interface, only the device file <filename>/dev/vbi</filename> was
805reserved for this purpose. The only driver supporting this interface
806was the BTTV driver, de-facto defining the V4L VBI interface. Reading
807from the device yields a raw VBI image with the following
808parameters:<informaltable>
809 <tgroup cols="2">
810 <thead>
811 <row>
812 <entry>&v4l2-vbi-format;</entry>
813 <entry>V4L, BTTV driver</entry>
814 </row>
815 </thead>
816 <tbody valign="top">
817 <row>
818 <entry>sampling_rate</entry>
819 <entry>28636363&nbsp;Hz NTSC (or any other 525-line
820standard); 35468950&nbsp;Hz PAL and SECAM (625-line standards)</entry>
821 </row>
822 <row>
823 <entry>offset</entry>
824 <entry>?</entry>
825 </row>
826 <row>
827 <entry>samples_per_line</entry>
828 <entry>2048</entry>
829 </row>
830 <row>
831 <entry>sample_format</entry>
832 <entry>V4L2_PIX_FMT_GREY. The last four bytes (a
833machine endianess integer) contain a frame counter.</entry>
834 </row>
835 <row>
836 <entry>start[]</entry>
837 <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry>
838 </row>
839 <row>
840 <entry>count[]</entry>
841 <entry><para>16, 16<footnote><para>Old driver
842versions used different values, eventually the custom
843<constant>BTTV_VBISIZE</constant> ioctl was added to query the
844correct values.</para></footnote></para></entry>
845 </row>
846 <row>
847 <entry>flags</entry>
848 <entry>0</entry>
849 </row>
850 </tbody>
851 </tgroup>
852 </informaltable></para>
853
854 <para>Undocumented in the V4L specification, in Linux 2.3 the
855<constant>VIDIOCGVBIFMT</constant> and
856<constant>VIDIOCSVBIFMT</constant> ioctls using struct
857<structname>vbi_format</structname> were added to determine the VBI
858image parameters. These ioctls are only partially compatible with the
859V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para>
860
861 <para>An <structfield>offset</structfield> field does not
862exist, <structfield>sample_format</structfield> is supposed to be
863<constant>VIDEO_PALETTE_RAW</constant>, equivalent to
864<constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are
865probably equivalent to &v4l2-vbi-format;.</para>
866
867 <para>Apparently only the Zoran (ZR 36120) driver implements
868these ioctls. The semantics differ from those specified for V4L2 in two
869ways. The parameters are reset on &func-open; and
870<constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the
871parameters are invalid.</para>
872 </section>
873
874 <section>
875 <title>Miscellaneous</title>
876
877 <para>V4L2 has no equivalent of the
878<constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI
879device associated with a video capture device (or vice versa) by
880reopening the device and requesting VBI data. For details see
881<xref linkend="open" />.</para>
882
883 <para>No replacement exists for <constant>VIDIOCKEY</constant>,
884and the V4L functions for microcode programming. A new interface for
885MPEG compression and playback devices is documented in <xref
886 linkend="extended-controls" />.</para>
887 </section>
888
889 </section>
890
891 <section id="hist-v4l2">
892 <title>Changes of the V4L2 API</title>
893
894 <para>Soon after the V4L API was added to the kernel it was
895criticised as too inflexible. In August 1998 Bill Dirks proposed a
896number of improvements and began to work on documentation, example
897drivers and applications. With the help of other volunteers this
898eventually became the V4L2 API, not just an extension but a
899replacement for the V4L API. However it took another four years and
900two stable kernel releases until the new API was finally accepted for
901inclusion into the kernel in its present form.</para>
902
903 <section>
904 <title>Early Versions</title>
905 <para>1998-08-20: First version.</para>
906
907 <para>1998-08-27: The &func-select; function was introduced.</para>
908
909 <para>1998-09-10: New video standard interface.</para>
910
911 <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl
912was replaced by the otherwise meaningless <constant>O_TRUNC</constant>
913&func-open; flag, and the aliases <constant>O_NONCAP</constant> and
914<constant>O_NOIO</constant> were defined. Applications can set this
915flag if they intend to access controls only, as opposed to capture
916applications which need exclusive access. The
917<constant>VIDEO_STD_XXX</constant> identifiers are now ordinals
918instead of flags, and the <function>video_std_construct()</function>
919helper function takes id and transmission arguments.</para>
920
921 <para>1998-09-28: Revamped video standard. Made video controls
922individually enumerable.</para>
923
924 <para>1998-10-02: The <structfield>id</structfield> field was
925removed from struct <structname>video_standard</structname> and the
926color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was
927renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A
928first draft of the Codec API was released.</para>
929
930 <para>1998-11-08: Many minor changes. Most symbols have been
931renamed. Some material changes to &v4l2-capability;.</para>
932
933 <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para>
934
935 <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant>
936changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and
937<constant>V4L2_PIX_FMT_RGB32</constant> changed to
938<constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now
939accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under
940names starting with <constant>V4L2_CID_AUDIO</constant>. The
941<constant>V4L2_MAJOR</constant> define was removed from
942<filename>videodev.h</filename> since it was only used once in the
943<filename>videodev</filename> kernel module. The
944<constant>YUV422</constant> and <constant>YUV411</constant> planar
945image formats were added.</para>
946
947 <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and
948video output devices were added.</para>
949
950 <para>1999-01-14: A raw VBI capture interface was added.</para>
951
952 <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl
953 was removed.</para>
954 </section>
955
956 <section>
957 <title>V4L2 Version 0.16 1999-01-31</title>
958 <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
959are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
960digital zoom (cropping) controls.</para>
961 </section>
962
963 <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill
964 forgot to bump the version number or never released it. -->
965
966 <section>
967 <title>V4L2 Version 0.18 1999-03-16</title>
968 <para>Added a v4l to V4L2 ioctl compatibility layer to
969videodev.c. Driver writers, this changes how you implement your ioctl
970handler. See the Driver Writer's Guide. Added some more control id
971codes.</para>
972 </section>
973
974 <section>
975 <title>V4L2 Version 0.19 1999-06-05</title>
976 <para>1999-03-18: Fill in the category and catname fields of
977v4l2_queryctrl objects before passing them to the driver. Required a
978minor change to the VIDIOC_QUERYCTRL handlers in the sample
979drivers.</para>
980 <para>1999-03-31: Better compatibility for v4l memory capture
981ioctls. Requires changes to drivers to fully support new compatibility
982features, see Driver Writer's Guide and v4l2cap.c. Added new control
983IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
984and _YUV411P to _YUV411P.</para>
985 <para>1999-04-04: Added a few more control IDs.</para>
986 <para>1999-04-07: Added the button control type.</para>
987 <para>1999-05-02: Fixed a typo in videodev.h, and added the
988V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para>
989 <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
990a malfunction of this ioctl.</para>
991 <para>1999-06-05: Changed the value of
992V4L2_CID_WHITENESS.</para>
993 </section>
994
995 <section>
996 <title>V4L2 Version 0.20 (1999-09-10)</title>
997
998 <para>Version 0.20 introduced a number of changes which were
999<emphasis>not backward compatible</emphasis> with 0.19 and earlier
1000versions. Purpose of these changes was to simplify the API, while
1001making it more extensible and following common Linux driver API
1002conventions.</para>
1003
1004 <orderedlist>
1005 <listitem>
1006 <para>Some typos in <constant>V4L2_FMT_FLAG</constant>
1007symbols were fixed. &v4l2-clip; was changed for compatibility with
1008v4l. (1999-08-30)</para>
1009 </listitem>
1010
1011 <listitem>
1012 <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added.
1013(1999-09-05)</para>
1014 </listitem>
1015
1016 <listitem>
1017 <para>All ioctl() commands that used an integer argument now
1018take a pointer to an integer. Where it makes sense, ioctls will return
1019the actual new value in the integer pointed to by the argument, a
1020common convention in the V4L2 API. The affected ioctls are:
1021VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
1022VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
1023<programlisting>
1024err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
1025</programlisting> becomes <programlisting>
1026int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &amp;a);
1027</programlisting>
1028 </para>
1029 </listitem>
1030
1031 <listitem>
1032 <para>All the different get- and set-format commands were
1033swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union
1034and a type field selecting the union member as parameter. Purpose is to
1035simplify the API by eliminating several ioctls and to allow new and
1036driver private data streams without adding new ioctls.</para>
1037
1038 <para>This change obsoletes the following ioctls:
1039<constant>VIDIOC_S_INFMT</constant>,
1040<constant>VIDIOC_G_INFMT</constant>,
1041<constant>VIDIOC_S_OUTFMT</constant>,
1042<constant>VIDIOC_G_OUTFMT</constant>,
1043<constant>VIDIOC_S_VBIFMT</constant> and
1044<constant>VIDIOC_G_VBIFMT</constant>. The image format structure
1045<structname>v4l2_format</structname> was renamed to &v4l2-pix-format;,
1046while &v4l2-format; is now the envelopping structure for all format
1047negotiations.</para>
1048 </listitem>
1049
1050 <listitem>
1051 <para>Similar to the changes above, the
1052<constant>VIDIOC_G_PARM</constant> and
1053<constant>VIDIOC_S_PARM</constant> ioctls were merged with
1054<constant>VIDIOC_G_OUTPARM</constant> and
1055<constant>VIDIOC_S_OUTPARM</constant>. A
1056<structfield>type</structfield> field in the new &v4l2-streamparm;
1057selects the respective union member.</para>
1058
1059 <para>This change obsoletes the
1060<constant>VIDIOC_G_OUTPARM</constant> and
1061<constant>VIDIOC_S_OUTPARM</constant> ioctls.</para>
1062 </listitem>
1063
1064 <listitem>
1065 <para>Control enumeration was simplified, and two new
1066control flags were introduced and one dropped. The
1067<structfield>catname</structfield> field was replaced by a
1068<structfield>group</structfield> field.</para>
1069
1070 <para>Drivers can now flag unsupported and temporarily
1071unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant>
1072and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The
1073<structfield>group</structfield> name indicates a possibly narrower
1074classification than the <structfield>category</structfield>. In other
1075words, there may be multiple groups within a category. Controls within
1076a group would typically be drawn within a group box. Controls in
1077different categories might have a greater separation, or may even
1078appear in separate windows.</para>
1079 </listitem>
1080
1081 <listitem>
1082 <para>The &v4l2-buffer; <structfield>timestamp</structfield>
1083was changed to a 64 bit integer, containing the sampling or output
1084time of the frame in nanoseconds. Additionally timestamps will be in
1085absolute system time, not starting from zero at the beginning of a
1086stream. The data type name for timestamps is stamp_t, defined as a
1087signed 64-bit integer. Output devices should not send a buffer out
1088until the time in the timestamp field has arrived. I would like to
1089follow SGI's lead, and adopt a multimedia timestamping system like
1090their UST (Unadjusted System Time). See
1091http://web.archive.org/web/*/http://reality.sgi.com
1092/cpirazzi_engr/lg/time/intro.html.
1093UST uses timestamps that are 64-bit signed integers
1094(not struct timeval's) and given in nanosecond units. The UST clock
1095starts at zero when the system is booted and runs continuously and
1096uniformly. It takes a little over 292 years for UST to overflow. There
1097is no way to set the UST clock. The regular Linux time-of-day clock
1098can be changed periodically, which would cause errors if it were being
1099used for timestamping a multimedia stream. A real UST style clock will
1100require some support in the kernel that is not there yet. But in
1101anticipation, I will change the timestamp field to a 64-bit integer,
1102and I will change the v4l2_masterclock_gettime() function (used only
1103by drivers) to return a 64-bit integer.</para>
1104 </listitem>
1105
1106 <listitem>
1107 <para>A <structfield>sequence</structfield> field was added
1108to &v4l2-buffer;. The <structfield>sequence</structfield> field counts
1109captured frames, it is ignored by output devices. When a capture
1110driver drops a frame, the sequence number of that frame is
1111skipped.</para>
1112 </listitem>
1113 </orderedlist>
1114 </section>
1115
1116 <section>
1117 <title>V4L2 Version 0.20 incremental changes</title>
1118 <!-- Version number didn't change anymore, reason unknown. -->
1119
1120 <para>1999-12-23: In &v4l2-vbi-format; the
1121<structfield>reserved1</structfield> field became
1122<structfield>offset</structfield>. Previously drivers were required to
1123clear the <structfield>reserved1</structfield> field.</para>
1124
1125 <para>2000-01-13: The
1126 <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para>
1127
1128 <para>2000-07-31: The <filename>linux/poll.h</filename> header
1129is now included by <filename>videodev.h</filename> for compatibility
1130with the original <filename>videodev.h</filename> file.</para>
1131
1132 <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and
1133<constant>V4L2_PIX_FMT_Y41P</constant> were added.</para>
1134
1135 <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was
1136added.</para>
1137
1138 <para>2000-12-04: A couple typos in symbol names were fixed.</para>
1139
1140 <para>2001-01-18: To avoid namespace conflicts the
1141<constant>fourcc</constant> macro defined in the
1142<filename>videodev.h</filename> header file was renamed to
1143<constant>v4l2_fourcc</constant>.</para>
1144
1145 <para>2001-01-25: A possible driver-level compatibility problem
1146between the <filename>videodev.h</filename> file in Linux 2.4.0 and
1147the <filename>videodev.h</filename> file included in the
1148<filename>videodevX</filename> patch was fixed. Users of an earlier
1149version of <filename>videodevX</filename> on Linux 2.4.0 should
1150recompile their V4L and V4L2 drivers.</para>
1151
1152 <para>2001-01-26: A possible kernel-level incompatibility
1153between the <filename>videodev.h</filename> file in the
1154<filename>videodevX</filename> patch and the
1155<filename>videodev.h</filename> file in Linux 2.2.x with devfs patches
1156applied was fixed.</para>
1157
1158 <para>2001-03-02: Certain V4L ioctls which pass data in both
1159direction although they are defined with read-only parameter, did not
1160work correctly through the backward compatibility layer.
1161[Solution?]</para>
1162
1163 <para>2001-04-13: Big endian 16-bit RGB formats were added.</para>
1164
1165 <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and
1166&VIDIOC-S-FREQUENCY; ioctls were added. (The old
1167<constant>VIDIOC_G_FREQ</constant> and
1168<constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners
1169into account.)</para>
1170
1171 <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was
1172added. This may <emphasis>break compatibility</emphasis> as the
1173&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct
1174<structname>v4l2_fmt</structname> <structfield>type</structfield>
1175field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the
1176documentation of the &v4l2-vbi-format;
1177<structfield>offset</structfield> field the ambiguous phrase "rising
1178edge" was changed to "leading edge".</para>
1179 </section>
1180
1181 <section>
1182 <title>V4L2 Version 0.20 2000-11-23</title>
1183
1184 <para>A number of changes were made to the raw VBI
1185interface.</para>
1186
1187 <orderedlist>
1188 <listitem>
1189 <para>Figures clarifying the line numbering scheme were
1190added to the V4L2 API specification. The
1191<structfield>start</structfield>[0] and
1192<structfield>start</structfield>[1] fields no longer count line
1193numbers beginning at zero. Rationale: a) The previous definition was
1194unclear. b) The <structfield>start</structfield>[] values are ordinal
1195numbers. c) There is no point in inventing a new line numbering
1196scheme. We now use line number as defined by ITU-R, period.
1197Compatibility: Add one to the start values. Applications depending on
1198the previous semantics may not function correctly.</para>
1199 </listitem>
1200
1201 <listitem>
1202 <para>The restriction "count[0] &gt; 0 and count[1] &gt; 0"
1203has been relaxed to "(count[0] + count[1]) &gt; 0". Rationale:
1204Drivers may allocate resources at scan line granularity and some data
1205services are transmitted only on the first field. The comment that
1206both <structfield>count</structfield> values will usually be equal is
1207misleading and pointless and has been removed. This change
1208<emphasis>breaks compatibility</emphasis> with earlier versions:
1209Drivers may return EINVAL, applications may not function
1210correctly.</para>
1211 </listitem>
1212
1213 <listitem>
1214 <para>Drivers are again permitted to return negative
1215(unknown) start values as proposed earlier. Why this feature was
1216dropped is unclear. This change may <emphasis>break
1217compatibility</emphasis> with applications depending on the start
1218values being positive. The use of <constant>EBUSY</constant> and
1219<constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl
1220was clarified. The &EBUSY; was finally documented, and the
1221<structfield>reserved2</structfield> field which was previously
1222mentioned only in the <filename>videodev.h</filename> header
1223file.</para>
1224 </listitem>
1225
1226 <listitem>
1227 <para>New buffer types
1228<constant>V4L2_TYPE_VBI_INPUT</constant> and
1229<constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an
1230alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was
1231missing in the <filename>videodev.h</filename> file.</para>
1232 </listitem>
1233 </orderedlist>
1234 </section>
1235
1236 <section>
1237 <title>V4L2 Version 0.20 2002-07-25</title>
1238 <para>Added sliced VBI interface proposal.</para>
1239 </section>
1240
1241 <section>
1242 <title>V4L2 in Linux 2.5.46, 2002-10</title>
1243
1244 <para>Around October-November 2002, prior to an announced
1245feature freeze of Linux 2.5, the API was revised, drawing from
1246experience with V4L2 0.20. This unnamed version was finally merged
1247into Linux 2.5.46.</para>
1248
1249 <orderedlist>
1250 <listitem>
1251 <para>As specified in <xref linkend="related" />, drivers
1252must make related device functions available under all minor device
1253numbers.</para>
1254 </listitem>
1255
1256 <listitem>
1257 <para>The &func-open; function requires access mode
1258<constant>O_RDWR</constant> regardless of the device type. All V4L2
1259drivers exchanging data with applications must support the
1260<constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant>
1261flag, a V4L2 symbol which aliased the meaningless
1262<constant>O_TRUNC</constant> to indicate accesses without data
1263exchange (panel applications) was dropped. Drivers must stay in "panel
1264mode" until the application attempts to initiate a data exchange, see
1265<xref linkend="open" />.</para>
1266 </listitem>
1267
1268 <listitem>
1269 <para>The &v4l2-capability; changed dramatically. Note that
1270also the size of the structure changed, which is encoded in the ioctl
1271request code, thus older V4L2 devices will respond with an &EINVAL; to
1272the new &VIDIOC-QUERYCAP; ioctl.</para>
1273
1274 <para>There are new fields to identify the driver, a new RDS
1275device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
1276<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
1277any audio connectors, another I/O capability
1278<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
1279these changes the <structfield>type</structfield> field became a bit
1280set and was merged into the <structfield>flags</structfield> field.
1281<constant>V4L2_FLAG_TUNER</constant> was renamed to
1282<constant>V4L2_CAP_TUNER</constant>,
1283<constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced
1284<constant>V4L2_FLAG_PREVIEW</constant> and
1285<constant>V4L2_CAP_VBI_CAPTURE</constant> and
1286<constant>V4L2_CAP_VBI_OUTPUT</constant> replaced
1287<constant>V4L2_FLAG_DATA_SERVICE</constant>.
1288<constant>V4L2_FLAG_READ</constant> and
1289<constant>V4L2_FLAG_WRITE</constant> were merged into
1290<constant>V4L2_CAP_READWRITE</constant>.</para>
1291
1292 <para>The redundant fields
1293<structfield>inputs</structfield>, <structfield>outputs</structfield>
1294and <structfield>audios</structfield> were removed. These properties
1295can be determined as described in <xref linkend="video" /> and <xref
1296linkend="audio" />.</para>
1297
1298 <para>The somewhat volatile and therefore barely useful
1299fields <structfield>maxwidth</structfield>,
1300<structfield>maxheight</structfield>,
1301<structfield>minwidth</structfield>,
1302<structfield>minheight</structfield>,
1303<structfield>maxframerate</structfield> were removed. This information
1304is available as described in <xref linkend="format" /> and
1305<xref linkend="standard" />.</para>
1306
1307 <para><constant>V4L2_FLAG_SELECT</constant> was removed. We
1308believe the select() function is important enough to require support
1309of it in all V4L2 drivers exchanging data with applications. The
1310redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed,
1311this information is available as described in <xref
1312 linkend="format" />.</para>
1313 </listitem>
1314
1315 <listitem>
1316 <para>In &v4l2-input; the
1317<structfield>assoc_audio</structfield> field and the
1318<structfield>capability</structfield> field and its only flag
1319<constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new
1320<structfield>audioset</structfield> field. Instead of linking one
1321video input to one audio input this field reports all audio inputs
1322this video input combines with.</para>
1323
1324 <para>New fields are <structfield>tuner</structfield>
1325(reversing the former link from tuners to video inputs),
1326<structfield>std</structfield> and
1327<structfield>status</structfield>.</para>
1328
1329 <para>Accordingly &v4l2-output; lost its
1330<structfield>capability</structfield> and
1331<structfield>assoc_audio</structfield> fields.
1332<structfield>audioset</structfield>,
1333<structfield>modulator</structfield> and
1334<structfield>std</structfield> where added instead.</para>
1335 </listitem>
1336
1337 <listitem>
1338 <para>The &v4l2-audio; field
1339<structfield>audio</structfield> was renamed to
1340<structfield>index</structfield>, for consistency with other
1341structures. A new capability flag
1342<constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the
1343audio input in question supports stereo sound.
1344<constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding
1345<constant>V4L2_AUDMODE</constant> flags where removed. This can be
1346easily implemented using controls. (However the same applies to AVL
1347which is still there.)</para>
1348
1349 <para>Again for consistency the &v4l2-audioout; field
1350<structfield>audio</structfield> was renamed to
1351<structfield>index</structfield>.</para>
1352 </listitem>
1353
1354 <listitem>
1355 <para>The &v4l2-tuner;
1356<structfield>input</structfield> field was replaced by an
1357<structfield>index</structfield> field, permitting devices with
1358multiple tuners. The link between video inputs and tuners is now
1359reversed, inputs point to their tuner. The
1360<structfield>std</structfield> substructure became a
1361simple set (more about this below) and moved into &v4l2-input;. A
1362<structfield>type</structfield> field was added.</para>
1363
1364 <para>Accordingly in &v4l2-modulator; the
1365<structfield>output</structfield> was replaced by an
1366<structfield>index</structfield> field.</para>
1367
1368 <para>In &v4l2-frequency; the
1369<structfield>port</structfield> field was replaced by a
1370<structfield>tuner</structfield> field containing the respective tuner
1371or modulator index number. A tuner <structfield>type</structfield>
1372field was added and the <structfield>reserved</structfield> field
1373became larger for future extensions (satellite tuners in
1374particular).</para>
1375 </listitem>
1376
1377 <listitem>
1378 <para>The idea of completely transparent video standards was
1379dropped. Experience showed that applications must be able to work with
1380video standards beyond presenting the user a menu. Instead of
1381enumerating supported standards with an ioctl applications can now
1382refer to standards by &v4l2-std-id; and symbols defined in the
1383<filename>videodev2.h</filename> header file. For details see <xref
1384 linkend="standard" />. The &VIDIOC-G-STD; and
1385&VIDIOC-S-STD; now take a pointer to this type as argument.
1386&VIDIOC-QUERYSTD; was added to autodetect the received standard, if
1387the hardware has this capability. In &v4l2-standard; an
1388<structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;.
1389A &v4l2-std-id; field named <structfield>id</structfield> was added as
1390machine readable identifier, also replacing the
1391<structfield>transmission</structfield> field. The misleading
1392<structfield>framerate</structfield> field was renamed
1393to <structfield>frameperiod</structfield>. The now obsolete
1394<structfield>colorstandard</structfield> information, originally
1395needed to distguish between variations of standards, were
1396removed.</para>
1397
1398 <para>Struct <structname>v4l2_enumstd</structname> ceased to
1399be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard;
1400directly. The information which standards are supported by a
1401particular video input or output moved into &v4l2-input; and
1402&v4l2-output; fields named <structfield>std</structfield>,
1403respectively.</para>
1404 </listitem>
1405
1406 <listitem>
1407 <para>The &v4l2-queryctrl; fields
1408<structfield>category</structfield> and
1409<structfield>group</structfield> did not catch on and/or were not
1410implemented as expected and therefore removed.</para>
1411 </listitem>
1412
1413 <listitem>
1414 <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data
1415formats as with &VIDIOC-S-FMT;, but without the overhead of
1416programming the hardware and regardless of I/O in progress.</para>
1417
1418 <para>In &v4l2-format; the <structfield>fmt</structfield>
1419union was extended to contain &v4l2-window;. All image format
1420negotiations are now possible with <constant>VIDIOC_G_FMT</constant>,
1421<constant>VIDIOC_S_FMT</constant> and
1422<constant>VIDIOC_TRY_FMT</constant>; ioctl. The
1423<constant>VIDIOC_G_WIN</constant> and
1424<constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video
1425overlay were removed. The <structfield>type</structfield> field
1426changed to type &v4l2-buf-type; and the buffer type names changed as
1427follows.<informaltable>
1428 <tgroup cols="2">
1429 <thead>
1430 <row>
1431 <entry>Old defines</entry>
1432 <entry>&v4l2-buf-type;</entry>
1433 </row>
1434 </thead>
1435 <tbody valign="top">
1436 <row>
1437 <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry>
1438 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
1439 </row>
1440 <row>
1441 <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry>
1442 <entry>Omitted for now</entry>
1443 </row>
1444 <row>
1445 <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry>
1446 <entry>Omitted for now</entry>
1447 </row>
1448 <row>
1449 <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry>
1450 <entry>Omitted for now</entry>
1451 </row>
1452 <row>
1453 <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry>
1454 <entry>Omitted for now</entry>
1455 </row>
1456 <row>
1457 <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry>
1458 <entry>Omitted for now</entry>
1459 </row>
1460 <row>
1461 <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry>
1462 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
1463 </row>
1464 <row>
1465 <entry><constant>-</constant></entry>
1466 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
1467 </row>
1468 <row>
1469 <entry><constant>-</constant></entry>
1470 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
1471 </row>
1472 <row>
1473 <entry><constant>-</constant></entry>
1474 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
1475 </row>
1476 <row>
1477 <entry><constant>-</constant></entry>
1478 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
1479 </row>
1480 <row>
1481 <entry><constant>-</constant></entry>
1482 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
1483 </row>
1484 <row>
1485 <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry>
1486 <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
1487 </row>
1488 </tbody>
1489 </tgroup>
1490 </informaltable></para>
1491 </listitem>
1492
1493 <listitem>
1494 <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named
1495<structfield>type</structfield> was added as in &v4l2-format;. The
1496<constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and
1497was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with
1498type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
1499 </listitem>
1500
1501 <listitem>
1502 <para>In &v4l2-pix-format; the
1503<structfield>depth</structfield> field was removed, assuming
1504applications which recognize the format by its four-character-code
1505already know the color depth, and others do not care about it. The
1506same rationale lead to the removal of the
1507<constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The
1508<constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed
1509because drivers are not supposed to convert images in kernel space. A
1510user library of conversion functions should be provided instead. The
1511<constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant.
1512Applications can set the <structfield>bytesperline</structfield> field
1513to zero to get a reasonable default. Since the remaining flags were
1514replaced as well, the <structfield>flags</structfield> field itself
1515was removed.</para>
1516 <para>The interlace flags were replaced by a &v4l2-field;
1517value in a newly added <structfield>field</structfield>
1518field.<informaltable>
1519 <tgroup cols="2">
1520 <thead>
1521 <row>
1522 <entry>Old flag</entry>
1523 <entry>&v4l2-field;</entry>
1524 </row>
1525 </thead>
1526 <tbody valign="top">
1527 <row>
1528 <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry>
1529 <entry>?</entry>
1530 </row>
1531 <row>
1532 <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant>
1533= <constant>V4L2_FMT_FLAG_COMBINED</constant></entry>
1534 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1535 </row>
1536 <row>
1537 <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant>
1538= <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry>
1539 <entry><constant>V4L2_FIELD_TOP</constant></entry>
1540 </row>
1541 <row>
1542 <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant>
1543= <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry>
1544 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1545 </row>
1546 <row>
1547 <entry><constant>-</constant></entry>
1548 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1549 </row>
1550 <row>
1551 <entry><constant>-</constant></entry>
1552 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1553 </row>
1554 <row>
1555 <entry><constant>-</constant></entry>
1556 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1557 </row>
1558 </tbody>
1559 </tgroup>
1560 </informaltable></para>
1561
1562 <para>The color space flags were replaced by a
1563&v4l2-colorspace; value in a newly added
1564<structfield>colorspace</structfield> field, where one of
1565<constant>V4L2_COLORSPACE_SMPTE170M</constant>,
1566<constant>V4L2_COLORSPACE_BT878</constant>,
1567<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or
1568<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces
1569<constant>V4L2_FMT_CS_601YUV</constant>.</para>
1570 </listitem>
1571
1572 <listitem>
1573 <para>In &v4l2-requestbuffers; the
1574<structfield>type</structfield> field was properly defined as
1575&v4l2-buf-type;. Buffer types changed as mentioned above. A new
1576<structfield>memory</structfield> field of type &v4l2-memory; was
1577added to distinguish between I/O methods using buffers allocated
1578by the driver or the application. See <xref linkend="io" /> for
1579details.</para>
1580 </listitem>
1581
1582 <listitem>
1583 <para>In &v4l2-buffer; the <structfield>type</structfield>
1584field was properly defined as &v4l2-buf-type;. Buffer types changed as
1585mentioned above. A <structfield>field</structfield> field of type
1586&v4l2-field; was added to indicate if a buffer contains a top or
1587bottom field. The old field flags were removed. Since no unadjusted
1588system time clock was added to the kernel as planned, the
1589<structfield>timestamp</structfield> field changed back from type
1590stamp_t, an unsigned 64 bit integer expressing the sample time in
1591nanoseconds, to struct <structname>timeval</structname>. With the
1592addition of a second memory mapping method the
1593<structfield>offset</structfield> field moved into union
1594<structfield>m</structfield>, and a new
1595<structfield>memory</structfield> field of type &v4l2-memory; was
1596added to distinguish between I/O methods. See <xref linkend="io" />
1597for details.</para>
1598
1599 <para>The <constant>V4L2_BUF_REQ_CONTIG</constant>
1600flag was used by the V4L compatibility layer, after changes to this
1601code it was no longer needed. The
1602<constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if
1603the buffer was indeed allocated in device memory rather than DMA-able
1604system memory. It was barely useful and so was removed.</para>
1605 </listitem>
1606
1607 <listitem>
1608 <para>In &v4l2-framebuffer; the
1609<structfield>base[3]</structfield> array anticipating double- and
1610triple-buffering in off-screen video memory, however without defining
1611a synchronization mechanism, was replaced by a single pointer. The
1612<constant>V4L2_FBUF_CAP_SCALEUP</constant> and
1613<constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed.
1614Applications can determine this capability more accurately using the
1615new cropping and scaling interface. The
1616<constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by
1617<constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and
1618<constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para>
1619 </listitem>
1620
1621 <listitem>
1622 <para>In &v4l2-clip; the <structfield>x</structfield>,
1623<structfield>y</structfield>, <structfield>width</structfield> and
1624<structfield>height</structfield> field moved into a
1625<structfield>c</structfield> substructure of type &v4l2-rect;. The
1626<structfield>x</structfield> and <structfield>y</structfield> fields
1627were renamed to <structfield>left</structfield> and
1628<structfield>top</structfield>, &ie; offsets to a context dependent
1629origin.</para>
1630 </listitem>
1631
1632 <listitem>
1633 <para>In &v4l2-window; the <structfield>x</structfield>,
1634<structfield>y</structfield>, <structfield>width</structfield> and
1635<structfield>height</structfield> field moved into a
1636<structfield>w</structfield> substructure as above. A
1637<structfield>field</structfield> field of type %v4l2-field; was added
1638to distinguish between field and frame (interlaced) overlay.</para>
1639 </listitem>
1640
1641 <listitem>
1642 <para>The digital zoom interface, including struct
1643<structname>v4l2_zoomcap</structname>, struct
1644<structname>v4l2_zoom</structname>,
1645<constant>V4L2_ZOOM_NONCAP</constant> and
1646<constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new
1647cropping and scaling interface. The previously unused struct
1648<structname>v4l2_cropcap</structname> and
1649<structname>v4l2_crop</structname> where redefined for this purpose.
1650See <xref linkend="crop" /> for details.</para>
1651 </listitem>
1652
1653 <listitem>
1654 <para>In &v4l2-vbi-format; the
1655<structfield>SAMPLE_FORMAT</structfield> field now contains a
1656four-character-code as used to identify video image formats and
1657<constant>V4L2_PIX_FMT_GREY</constant> replaces the
1658<constant>V4L2_VBI_SF_UBYTE</constant> define. The
1659<structfield>reserved</structfield> field was extended.</para>
1660 </listitem>
1661
1662 <listitem>
1663 <para>In &v4l2-captureparm; the type of the
1664<structfield>timeperframe</structfield> field changed from unsigned
1665long to &v4l2-fract;. This allows the accurate expression of multiples
1666of the NTSC-M frame rate 30000 / 1001. A new field
1667<structfield>readbuffers</structfield> was added to control the driver
1668behaviour in read I/O mode.</para>
1669
1670 <para>Similar changes were made to &v4l2-outputparm;.</para>
1671 </listitem>
1672
1673 <listitem>
1674 <para>The struct <structname>v4l2_performance</structname>
1675and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when
1676using the <link linkend="rw">read/write I/O method</link>, which is
1677limited anyway, this information is already available to
1678applications.</para>
1679 </listitem>
1680
1681 <listitem>
1682 <para>The example transformation from RGB to YCbCr color
1683space in the old V4L2 documentation was inaccurate, this has been
1684corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be
16850.587, and 127/112 != 255/224 --></para>
1686 </listitem>
1687 </orderedlist>
1688 </section>
1689
1690 <section>
1691 <title>V4L2 2003-06-19</title>
1692
1693 <orderedlist>
1694 <listitem>
1695 <para>A new capability flag
1696<constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior
1697to this change radio devices would identify solely by having exactly one
1698tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para>
1699 </listitem>
1700
1701 <listitem>
1702 <para>An optional driver access priority mechanism was
1703added, see <xref linkend="app-pri" /> for details.</para>
1704 </listitem>
1705
1706 <listitem>
1707 <para>The audio input and output interface was found to be
1708incomplete.</para>
1709 <para>Previously the &VIDIOC-G-AUDIO;
1710ioctl would enumerate the available audio inputs. An ioctl to
1711determine the current audio input, if more than one combines with the
1712current video input, did not exist. So
1713<constant>VIDIOC_G_AUDIO</constant> was renamed to
1714<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl was removed on
1715Kernel 2.6.39. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
1716audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
1717input.</para>
1718 <para>The same changes were made to &VIDIOC-G-AUDOUT; and
1719&VIDIOC-ENUMAUDOUT;.</para>
1720 <para>Until further the "videodev" module will automatically
1721translate between the old and new ioctls, but drivers and applications
1722must be updated to successfully compile again.</para>
1723 </listitem>
1724
1725 <listitem>
1726 <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
1727write-read parameter. It was changed to write-only, while the write-read
1728version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
1729ioctl was removed on Kernel 2.6.39. Until further the "videodev"
1730kernel module will automatically translate to the new version, so drivers
1731must be recompiled, but not applications.</para>
1732 </listitem>
1733
1734 <listitem>
1735 <para><xref linkend="overlay" /> incorrectly stated that
1736clipping rectangles define regions where the video can be seen.
1737Correct is that clipping rectangles define regions where
1738<emphasis>no</emphasis> video shall be displayed and so the graphics
1739surface can be seen.</para>
1740 </listitem>
1741
1742 <listitem>
1743 <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were
1744defined with write-only parameter, inconsistent with other ioctls
1745modifying their argument. They were changed to write-read, while a
1746<constant>_OLD</constant> suffix was added to the write-only versions.
1747The old ioctls were removed on Kernel 2.6.39. Drivers and
1748applications assuming a constant parameter need an update.</para>
1749 </listitem>
1750 </orderedlist>
1751 </section>
1752
1753 <section>
1754 <title>V4L2 2003-11-05</title>
1755 <orderedlist>
1756 <listitem>
1757 <para>In <xref linkend="pixfmt-rgb" /> the following pixel
1758formats were incorrectly transferred from Bill Dirks' V4L2
1759specification. Descriptions below refer to bytes in memory, in
1760ascending address order.<informaltable>
1761 <tgroup cols="3">
1762 <thead>
1763 <row>
1764 <entry>Symbol</entry>
1765 <entry>In this document prior to revision
17660.5</entry>
1767 <entry>Corrected</entry>
1768 </row>
1769 </thead>
1770 <tbody valign="top">
1771 <row>
1772 <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
1773 <entry>B, G, R</entry>
1774 <entry>R, G, B</entry>
1775 </row>
1776 <row>
1777 <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
1778 <entry>R, G, B</entry>
1779 <entry>B, G, R</entry>
1780 </row>
1781 <row>
1782 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
1783 <entry>B, G, R, X</entry>
1784 <entry>R, G, B, X</entry>
1785 </row>
1786 <row>
1787 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
1788 <entry>R, G, B, X</entry>
1789 <entry>B, G, R, X</entry>
1790 </row>
1791 </tbody>
1792 </tgroup>
1793 </informaltable> The
1794<constant>V4L2_PIX_FMT_BGR24</constant> example was always
1795correct.</para>
1796 <para>In <xref linkend="v4l-image-properties" /> the mapping
1797of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and
1798<constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats
1799was accordingly corrected.</para>
1800 </listitem>
1801
1802 <listitem>
1803 <para>Unrelated to the fixes above, drivers may still
1804interpret some V4L2 RGB pixel formats differently. These issues have
1805yet to be addressed, for details see <xref
1806 linkend="pixfmt-rgb" />.</para>
1807 </listitem>
1808 </orderedlist>
1809 </section>
1810
1811 <section>
1812 <title>V4L2 in Linux 2.6.6, 2004-05-09</title>
1813 <orderedlist>
1814 <listitem>
1815 <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined
1816with read-only parameter. It is now defined as write-read ioctl, while
1817the read-only version was renamed to
1818<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl was removed
1819on Kernel 2.6.39.</para>
1820 </listitem>
1821 </orderedlist>
1822 </section>
1823
1824 <section>
1825 <title>V4L2 in Linux 2.6.8</title>
1826 <orderedlist>
1827 <listitem>
1828 <para>A new field <structfield>input</structfield> (former
1829<structfield>reserved[0]</structfield>) was added to the &v4l2-buffer;
1830structure. Purpose of this field is to alternate between video inputs
1831(&eg; cameras) in step with the video capturing process. This function
1832must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant>
1833flag. The <structfield>flags</structfield> field is no longer
1834read-only.</para>
1835 </listitem>
1836 </orderedlist>
1837 </section>
1838
1839 <section>
1840 <title>V4L2 spec erratum 2004-08-01</title>
1841
1842 <orderedlist>
1843 <listitem>
1844 <para>The return value of the
1845<xref linkend="func-open" /> function was incorrectly documented.</para>
1846 </listitem>
1847
1848 <listitem>
1849 <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para>
1850 </listitem>
1851
1852 <listitem>
1853 <para>In the Current Audio Input example the
1854<constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong
1855argument.</para>
1856 </listitem>
1857
1858 <listitem>
1859 <para>The documentation of the &VIDIOC-QBUF; and
1860&VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer;
1861<structfield>memory</structfield> field. It was also missing from
1862examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO;
1863was not documented.</para>
1864 </listitem>
1865 </orderedlist>
1866 </section>
1867
1868 <section>
1869 <title>V4L2 in Linux 2.6.14</title>
1870 <orderedlist>
1871 <listitem>
1872 <para>A new sliced VBI interface was added. It is documented
1873in <xref linkend="sliced" /> and replaces the interface first
1874proposed in V4L2 specification 0.8.</para>
1875 </listitem>
1876 </orderedlist>
1877 </section>
1878
1879 <section>
1880 <title>V4L2 in Linux 2.6.15</title>
1881 <orderedlist>
1882 <listitem>
1883 <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para>
1884 </listitem>
1885
1886 <listitem>
1887 <para>New video standards
1888<constant>V4L2_STD_NTSC_443</constant>,
1889<constant>V4L2_STD_SECAM_LC</constant>,
1890<constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1),
1891and <constant>V4L2_STD_ATSC</constant> (a set of
1892<constant>V4L2_STD_ATSC_8_VSB</constant> and
1893<constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the
1894<constant>V4L2_STD_525_60</constant> set now includes
1895<constant>V4L2_STD_NTSC_443</constant>. See also <xref
1896 linkend="v4l2-std-id" />.</para>
1897 </listitem>
1898
1899 <listitem>
1900 <para>The <constant>VIDIOC_G_COMP</constant> and
1901<constant>VIDIOC_S_COMP</constant> ioctl were renamed to
1902<constant>VIDIOC_G_MPEGCOMP</constant> and
1903<constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument
1904was replaced by a struct
1905<structname>v4l2_mpeg_compression</structname> pointer. (The
1906<constant>VIDIOC_G_MPEGCOMP</constant> and
1907<constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux
19082.6.25.)</para>
1909 </listitem>
1910 </orderedlist>
1911 </section>
1912
1913 <section>
1914 <title>V4L2 spec erratum 2005-11-27</title>
1915 <para>The capture example in <xref linkend="capture-example" />
1916called the &VIDIOC-S-CROP; ioctl without checking if cropping is
1917supported. In the video standard selection example in
1918<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong
1919argument type.</para>
1920 </section>
1921
1922 <section>
1923 <title>V4L2 spec erratum 2006-01-10</title>
1924 <orderedlist>
1925 <listitem>
1926 <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in
1927&v4l2-input; not only indicates if the color killer is enabled, but
1928also if it is active. (The color killer disables color decoding when
1929it detects no color in the video signal to improve the image
1930quality.)</para>
1931 </listitem>
1932
1933 <listitem>
1934 <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as
1935stated on its reference page. The ioctl changed in 2003 as noted above.</para>
1936 </listitem>
1937 </orderedlist>
1938 </section>
1939
1940 <section>
1941 <title>V4L2 spec erratum 2006-02-03</title>
1942 <orderedlist>
1943 <listitem>
1944 <para>In &v4l2-captureparm; and &v4l2-outputparm; the
1945<structfield>timeperframe</structfield> field gives the time in
1946seconds, not microseconds.</para>
1947 </listitem>
1948 </orderedlist>
1949 </section>
1950
1951 <section>
1952 <title>V4L2 spec erratum 2006-02-04</title>
1953 <orderedlist>
1954 <listitem>
1955 <para>The <structfield>clips</structfield> field in
1956&v4l2-window; must point to an array of &v4l2-clip;, not a linked
1957list, because drivers ignore the struct
1958<structname>v4l2_clip</structname>.<structfield>next</structfield>
1959pointer.</para>
1960 </listitem>
1961 </orderedlist>
1962 </section>
1963
1964 <section>
1965 <title>V4L2 in Linux 2.6.17</title>
1966 <orderedlist>
1967 <listitem>
1968 <para>New video standard macros were added:
1969<constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the
1970sets <constant>V4L2_STD_MN</constant>,
1971<constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and
1972<constant>V4L2_STD_DK</constant>. The
1973<constant>V4L2_STD_NTSC</constant> and
1974<constant>V4L2_STD_SECAM</constant> sets now include
1975<constant>V4L2_STD_NTSC_M_KR</constant> and
1976<constant>V4L2_STD_SECAM_LC</constant> respectively.</para>
1977 </listitem>
1978
1979 <listitem>
1980 <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant>
1981was defined to record both languages of a bilingual program. The
1982use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose
1983is deprecated now. See the &VIDIOC-G-TUNER; section for
1984details.</para>
1985 </listitem>
1986 </orderedlist>
1987 </section>
1988
1989 <section>
1990 <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title>
1991 <orderedlist>
1992 <listitem>
1993 <para>In various places
1994<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and
1995<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI
1996interface were not mentioned along with other buffer types.</para>
1997 </listitem>
1998
1999 <listitem>
2000 <para>In <xref linkend="vidioc-g-audio" /> it was clarified
2001that the &v4l2-audio; <structfield>mode</structfield> field is a flags
2002field.</para>
2003 </listitem>
2004
2005 <listitem>
2006 <para><xref linkend="vidioc-querycap" /> did not mention the
2007sliced VBI and radio capability flags.</para>
2008 </listitem>
2009
2010 <listitem>
2011 <para>In <xref linkend="vidioc-g-frequency" /> it was
2012clarified that applications must initialize the tuner
2013<structfield>type</structfield> field of &v4l2-frequency; before
2014calling &VIDIOC-S-FREQUENCY;.</para>
2015 </listitem>
2016
2017 <listitem>
2018 <para>The <structfield>reserved</structfield> array
2019in &v4l2-requestbuffers; has 2 elements, not 32.</para>
2020 </listitem>
2021
2022 <listitem>
2023 <para>In <xref linkend="output" /> and <xref
2024 linkend="raw-vbi" /> the device file names
2025<filename>/dev/vout</filename> which never caught on were replaced
2026by <filename>/dev/video</filename>.</para>
2027 </listitem>
2028
2029 <listitem>
2030 <para>With Linux 2.6.15 the possible range for VBI device minor
2031numbers was extended from 224-239 to 224-255. Accordingly device file names
2032<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are
2033possible now.</para>
2034 </listitem>
2035 </orderedlist>
2036 </section>
2037
2038 <section>
2039 <title>V4L2 in Linux 2.6.18</title>
2040 <orderedlist>
2041 <listitem>
2042 <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS;
2043and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported
2044controls with &VIDIOC-QUERYCTRL;, new control types
2045<constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
2046<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref
2047 linkend="v4l2-ctrl-type" />), and new control flags
2048<constant>V4L2_CTRL_FLAG_READ_ONLY</constant>,
2049<constant>V4L2_CTRL_FLAG_UPDATE</constant>,
2050<constant>V4L2_CTRL_FLAG_INACTIVE</constant> and
2051<constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref
2052 linkend="control-flags" />). See <xref
2053 linkend="extended-controls" /> for details.</para>
2054 </listitem>
2055 </orderedlist>
2056 </section>
2057
2058 <section>
2059 <title>V4L2 in Linux 2.6.19</title>
2060 <orderedlist>
2061 <listitem>
2062 <para>In &v4l2-sliced-vbi-cap; a buffer type field was added
2063replacing a reserved field. Note on architectures where the size of
2064enum types differs from int types the size of the structure changed.
2065The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only
2066to write-read. Applications must initialize the type field and clear
2067the reserved fields now. These changes may <emphasis>break the
2068compatibility</emphasis> with older drivers and applications.</para>
2069 </listitem>
2070
2071 <listitem>
2072 <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and
2073&VIDIOC-ENUM-FRAMEINTERVALS; were added.</para>
2074 </listitem>
2075
2076 <listitem>
2077 <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref
2078linkend="rgb-formats" />) was added.</para>
2079 </listitem>
2080 </orderedlist>
2081 </section>
2082
2083 <section>
2084 <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title>
2085 <orderedlist>
2086 <listitem>
2087 <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref
2088linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para>
2089 </listitem>
2090 </orderedlist>
2091 </section>
2092
2093 <section>
2094 <title>V4L2 in Linux 2.6.21</title>
2095 <orderedlist>
2096 <listitem>
2097 <para>The <filename>videodev2.h</filename> header file is
2098now dual licensed under GNU General Public License version two or
2099later, and under a 3-clause BSD-style license.</para>
2100 </listitem>
2101 </orderedlist>
2102 </section>
2103
2104 <section>
2105 <title>V4L2 in Linux 2.6.22</title>
2106 <orderedlist>
2107 <listitem>
2108 <para>Two new field orders
2109 <constant>V4L2_FIELD_INTERLACED_TB</constant> and
2110 <constant>V4L2_FIELD_INTERLACED_BT</constant> were
2111 added. See <xref linkend="v4l2-field" /> for details.</para>
2112 </listitem>
2113
2114 <listitem>
2115 <para>Three new clipping/blending methods with a global or
2116straight or inverted local alpha value were added to the video overlay
2117interface. See the description of the &VIDIOC-G-FBUF; and
2118&VIDIOC-S-FBUF; ioctls for details.</para>
2119 <para>A new <structfield>global_alpha</structfield> field
2120was added to <link
2121linkend="v4l2-window"><structname>v4l2_window</structname></link>,
2122extending the structure. This may <emphasis>break
2123compatibility</emphasis> with applications using a struct
2124<structname>v4l2_window</structname> directly. However the <link
2125linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a
2126pointer to a <link linkend="v4l2-format">v4l2_format</link> parent
2127structure with padding bytes at the end, are not affected.</para>
2128 </listitem>
2129
2130 <listitem>
2131 <para>The format of the <structfield>chromakey</structfield>
2132field in &v4l2-window; changed from "host order RGB32" to a pixel
2133value in the same format as the framebuffer. This may <emphasis>break
2134compatibility</emphasis> with existing applications. Drivers
2135supporting the "host order RGB32" format are not known.</para>
2136 </listitem>
2137
2138 </orderedlist>
2139 </section>
2140
2141 <section>
2142 <title>V4L2 in Linux 2.6.24</title>
2143 <orderedlist>
2144 <listitem>
2145 <para>The pixel formats
2146<constant>V4L2_PIX_FMT_PAL8</constant>,
2147<constant>V4L2_PIX_FMT_YUV444</constant>,
2148<constant>V4L2_PIX_FMT_YUV555</constant>,
2149<constant>V4L2_PIX_FMT_YUV565</constant> and
2150<constant>V4L2_PIX_FMT_YUV32</constant> were added.</para>
2151 </listitem>
2152 </orderedlist>
2153 </section>
2154
2155 <section>
2156 <title>V4L2 in Linux 2.6.25</title>
2157 <orderedlist>
2158 <listitem>
2159 <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16">
2160<constant>V4L2_PIX_FMT_Y16</constant></link> and <link
2161linkend="V4L2-PIX-FMT-SBGGR16">
2162<constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para>
2163 </listitem>
2164 <listitem>
2165 <para>New <link linkend="control">controls</link>
2166<constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>,
2167<constant>V4L2_CID_HUE_AUTO</constant>,
2168<constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>,
2169<constant>V4L2_CID_SHARPNESS</constant> and
2170<constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The
2171controls <constant>V4L2_CID_BLACK_LEVEL</constant>,
2172<constant>V4L2_CID_WHITENESS</constant>,
2173<constant>V4L2_CID_HCENTER</constant> and
2174<constant>V4L2_CID_VCENTER</constant> were deprecated.
2175</para>
2176 </listitem>
2177 <listitem>
2178 <para>A <link linkend="camera-controls">Camera controls
2179class</link> was added, with the new controls
2180<constant>V4L2_CID_EXPOSURE_AUTO</constant>,
2181<constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>,
2182<constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>,
2183<constant>V4L2_CID_PAN_RELATIVE</constant>,
2184<constant>V4L2_CID_TILT_RELATIVE</constant>,
2185<constant>V4L2_CID_PAN_RESET</constant>,
2186<constant>V4L2_CID_TILT_RESET</constant>,
2187<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
2188<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
2189<constant>V4L2_CID_FOCUS_ABSOLUTE</constant>,
2190<constant>V4L2_CID_FOCUS_RELATIVE</constant> and
2191<constant>V4L2_CID_FOCUS_AUTO</constant>.</para>
2192 </listitem>
2193 <listitem>
2194 <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and
2195<constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded
2196by the <link linkend="extended-controls">extended controls</link>
2197interface in Linux 2.6.18, where finally removed from the
2198<filename>videodev2.h</filename> header file.</para>
2199 </listitem>
2200 </orderedlist>
2201 </section>
2202
2203 <section>
2204 <title>V4L2 in Linux 2.6.26</title>
2205 <orderedlist>
2206 <listitem>
2207 <para>The pixel formats
2208<constant>V4L2_PIX_FMT_Y16</constant> and
2209<constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para>
2210 </listitem>
2211 <listitem>
2212 <para>Added user controls
2213<constant>V4L2_CID_CHROMA_AGC</constant> and
2214<constant>V4L2_CID_COLOR_KILLER</constant>.</para>
2215 </listitem>
2216 </orderedlist>
2217 </section>
2218
2219 <section>
2220 <title>V4L2 in Linux 2.6.27</title>
2221 <orderedlist>
2222 <listitem>
2223 <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the
2224<constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para>
2225 </listitem>
2226 <listitem>
2227 <para>The pixel formats
2228<constant>V4L2_PIX_FMT_YVYU</constant>,
2229<constant>V4L2_PIX_FMT_PCA501</constant>,
2230<constant>V4L2_PIX_FMT_PCA505</constant>,
2231<constant>V4L2_PIX_FMT_PCA508</constant>,
2232<constant>V4L2_PIX_FMT_PCA561</constant>,
2233<constant>V4L2_PIX_FMT_SGBRG8</constant>,
2234<constant>V4L2_PIX_FMT_PAC207</constant> and
2235<constant>V4L2_PIX_FMT_PJPG</constant> were added.</para>
2236 </listitem>
2237 </orderedlist>
2238 </section>
2239
2240 <section>
2241 <title>V4L2 in Linux 2.6.28</title>
2242 <orderedlist>
2243 <listitem>
2244 <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and
2245<constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para>
2246 </listitem>
2247 <listitem>
2248 <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG
2249video encoding.</para>
2250 </listitem>
2251 <listitem>
2252 <para>The pixel formats
2253<constant>V4L2_PIX_FMT_SGRBG10</constant> and
2254<constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para>
2255 </listitem>
2256 </orderedlist>
2257 </section>
2258
2259 <section>
2260 <title>V4L2 in Linux 2.6.29</title>
2261 <orderedlist>
2262 <listitem>
2263 <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed
2264to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT;
2265was introduced in its place. The old struct <structname>v4l2_chip_ident</structname>
2266was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para>
2267 </listitem>
2268 <listitem>
2269 <para>The pixel formats
2270<constant>V4L2_PIX_FMT_VYUY</constant>,
2271<constant>V4L2_PIX_FMT_NV16</constant> and
2272<constant>V4L2_PIX_FMT_NV61</constant> were added.</para>
2273 </listitem>
2274 <listitem>
2275 <para>Added camera controls
2276<constant>V4L2_CID_ZOOM_ABSOLUTE</constant>,
2277<constant>V4L2_CID_ZOOM_RELATIVE</constant>,
2278<constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and
2279<constant>V4L2_CID_PRIVACY</constant>.</para>
2280 </listitem>
2281 </orderedlist>
2282 </section>
2283 <section>
2284 <title>V4L2 in Linux 2.6.30</title>
2285 <orderedlist>
2286 <listitem>
2287 <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para>
2288 </listitem>
2289 <listitem>
2290 <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para>
2291 </listitem>
2292 </orderedlist>
2293 </section>
2294 <section>
2295 <title>V4L2 in Linux 2.6.32</title>
2296 <orderedlist>
2297 <listitem>
2298 <para>In order to be easier to compare a V4L2 API and a kernel
2299version, now V4L2 API is numbered using the Linux Kernel version numeration.</para>
2300 </listitem>
2301 <listitem>
2302 <para>Finalized the RDS capture API. See <xref linkend="rds" /> for
2303more information.</para>
2304 </listitem>
2305 <listitem>
2306 <para>Added new capabilities for modulators and RDS encoders.</para>
2307 </listitem>
2308 <listitem>
2309 <para>Add description for libv4l API.</para>
2310 </listitem>
2311 <listitem>
2312 <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para>
2313 </listitem>
2314 <listitem>
2315 <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para>
2316 </listitem>
2317 <listitem>
2318 <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para>
2319 </listitem>
2320 <listitem>
2321 <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para>
2322 </listitem>
2323 </orderedlist>
2324 </section>
2325 <section>
2326 <title>V4L2 in Linux 2.6.33</title>
2327 <orderedlist>
2328 <listitem>
2329 <para>Added support for Digital Video timings in order to support HDTV receivers and transmitters.</para>
2330 </listitem>
2331 </orderedlist>
2332 </section>
2333 <section>
2334 <title>V4L2 in Linux 2.6.34</title>
2335 <orderedlist>
2336 <listitem>
2337 <para>Added
2338<constant>V4L2_CID_IRIS_ABSOLUTE</constant> and
2339<constant>V4L2_CID_IRIS_RELATIVE</constant> controls to the
2340 <link linkend="camera-controls">Camera controls class</link>.
2341 </para>
2342 </listitem>
2343 </orderedlist>
2344 </section>
2345 <section>
2346 <title>V4L2 in Linux 2.6.37</title>
2347 <orderedlist>
2348 <listitem>
2349 <para>Remove the vtx (videotext/teletext) API. This API was no longer
2350used and no hardware exists to verify the API. Nor were any userspace applications found
2351that used it. It was originally scheduled for removal in 2.6.35.
2352 </para>
2353 </listitem>
2354 </orderedlist>
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>
2370
2371 <section id="other">
2372 <title>Relation of V4L2 to other Linux multimedia APIs</title>
2373
2374 <section id="xvideo">
2375 <title>X Video Extension</title>
2376
2377 <para>The X Video Extension (abbreviated XVideo or just Xv) is
2378an extension of the X Window system, implemented for example by the
2379XFree86 project. Its scope is similar to V4L2, an API to video capture
2380and output devices for X clients. Xv allows applications to display
2381live video in a window, send window contents to a TV output, and
2382capture or output still images in XPixmaps<footnote>
2383 <para>This is not implemented in XFree86.</para>
2384 </footnote>. With their implementation XFree86 makes the
2385extension available across many operating systems and
2386architectures.</para>
2387
2388 <para>Because the driver is embedded into the X server Xv has a
2389number of advantages over the V4L2 <link linkend="overlay">video
2390overlay interface</link>. The driver can easily determine the overlay
2391target, &ie; visible graphics memory or off-screen buffers for a
2392destructive overlay. It can program the RAMDAC for a non-destructive
2393overlay, scaling or color-keying, or the clipping functions of the
2394video capture hardware, always in sync with drawing operations or
2395windows moving or changing their stacking order.</para>
2396
2397 <para>To combine the advantages of Xv and V4L a special Xv
2398driver exists in XFree86 and XOrg, just programming any overlay capable
2399Video4Linux device it finds. To enable it
2400<filename>/etc/X11/XF86Config</filename> must contain these lines:</para>
2401 <para><screen>
2402Section "Module"
2403 Load "v4l"
2404EndSection</screen></para>
2405
2406 <para>As of XFree86 4.2 this driver still supports only V4L
2407ioctls, however it should work just fine with all V4L2 devices through
2408the V4L2 backward-compatibility layer. Since V4L2 permits multiple
2409opens it is possible (if supported by the V4L2 driver) to capture
2410video while an X client requested video overlay. Restrictions of
2411simultaneous capturing and overlay are discussed in <xref
2412 linkend="overlay" /> apply.</para>
2413
2414 <para>Only marginally related to V4L2, XFree86 extended Xv to
2415support hardware YUV to RGB conversion and scaling for faster video
2416playback, and added an interface to MPEG-2 decoding hardware. This API
2417is useful to display images captured with V4L2 devices.</para>
2418 </section>
2419
2420 <section>
2421 <title>Digital Video</title>
2422
2423 <para>V4L2 does not support digital terrestrial, cable or
2424satellite broadcast. A separate project aiming at digital receivers
2425exists. You can find its homepage at <ulink
2426url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
2427has no connection to the V4L2 API except that drivers for hybrid
2428hardware may support both.</para>
2429 </section>
2430
2431 <section>
2432 <title>Audio Interfaces</title>
2433
2434 <para>[to do - OSS/ALSA]</para>
2435 </section>
2436 </section>
2437
2438 <section id="experimental">
2439 <title>Experimental API Elements</title>
2440
2441 <para>The following V4L2 API elements are currently experimental
2442and may change in the future.</para>
2443
2444 <itemizedlist>
2445 <listitem>
2446 <para>Video Output Overlay (OSD) Interface, <xref
2447 linkend="osd" />.</para>
2448 </listitem>
2449 <listitem>
2450 <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>,
2451 &v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para>
2452 </listitem>
2453 <listitem>
2454 <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>,
2455&VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para>
2456 </listitem>
2457 <listitem>
2458 <para>&VIDIOC-ENUM-FRAMESIZES; and
2459&VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para>
2460 </listitem>
2461 <listitem>
2462 <para>&VIDIOC-G-ENC-INDEX; ioctl.</para>
2463 </listitem>
2464 <listitem>
2465 <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD;
2466ioctls.</para>
2467 </listitem>
2468 <listitem>
2469 <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
2470ioctls.</para>
2471 </listitem>
2472 <listitem>
2473 <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
2474 </listitem>
2475 </itemizedlist>
2476 </section>
2477
2478 <section id="obsolete">
2479 <title>Obsolete API Elements</title>
2480
2481 <para>The following V4L2 API elements were superseded by new
2482interfaces and should not be implemented in new drivers.</para>
2483
2484 <itemizedlist>
2485 <listitem>
2486 <para><constant>VIDIOC_G_MPEGCOMP</constant> and
2487<constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls,
2488<xref linkend="extended-controls" />.</para>
2489 </listitem>
2490 </itemizedlist>
2491 </section>
2492 </section>
2493
2494 <!--
2495Local Variables:
2496mode: sgml
2497sgml-parent-document: "v4l2.sgml"
2498indent-tabs-mode: nil
2499End:
2500 -->
diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml
new file mode 100644
index 000000000000..a920ee80f640
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/controls.xml
@@ -0,0 +1,2103 @@
1 <section id="control">
2 <title>User Controls</title>
3
4 <para>Devices typically have a number of user-settable controls
5such as brightness, saturation and so on, which would be presented to
6the user on a graphical user interface. But, different devices
7will have different controls available, and furthermore, the range of
8possible values, and the default value will vary from device to
9device. The control ioctls provide the information and a mechanism to
10create a nice user interface for these controls that will work
11correctly with any device.</para>
12
13 <para>All controls are accessed using an ID value. V4L2 defines
14several IDs for specific purposes. Drivers can also implement their
15own custom controls using <constant>V4L2_CID_PRIVATE_BASE</constant>
16and higher values. The pre-defined control IDs have the prefix
17<constant>V4L2_CID_</constant>, and are listed in <xref
18linkend="control-id" />. The ID is used when querying the attributes of
19a control, and when getting or setting the current value.</para>
20
21 <para>Generally applications should present controls to the user
22without assumptions about their purpose. Each control comes with a
23name string the user is supposed to understand. When the purpose is
24non-intuitive the driver writer should provide a user manual, a user
25interface plug-in or a driver specific panel application. Predefined
26IDs were introduced to change a few controls programmatically, for
27example to mute a device during a channel switch.</para>
28
29 <para>Drivers may enumerate different controls after switching
30the current video input or output, tuner or modulator, or audio input
31or output. Different in the sense of other bounds, another default and
32current value, step size or other menu items. A control with a certain
33<emphasis>custom</emphasis> ID can also change name and
34type.<footnote>
35 <para>It will be more convenient for applications if drivers
36make use of the <constant>V4L2_CTRL_FLAG_DISABLED</constant> flag, but
37that was never required.</para>
38 </footnote> Control values are stored globally, they do not
39change when switching except to stay within the reported bounds. They
40also do not change &eg; when the device is opened or closed, when the
41tuner radio frequency is changed or generally never without
42application request. Since V4L2 specifies no event mechanism, panel
43applications intended to cooperate with other panel applications (be
44they built into a larger application, as a TV viewer) may need to
45regularly poll control values to update their user
46interface.<footnote>
47 <para>Applications could call an ioctl to request events.
48After another process called &VIDIOC-S-CTRL; or another ioctl changing
49shared properties the &func-select; function would indicate
50readability until any ioctl (querying the properties) is
51called.</para>
52 </footnote></para>
53
54 <table pgwide="1" frame="none" id="control-id">
55 <title>Control IDs</title>
56 <tgroup cols="3">
57 &cs-def;
58 <thead>
59 <row>
60 <entry>ID</entry>
61 <entry>Type</entry>
62 <entry>Description</entry>
63 </row>
64 </thead>
65 <tbody valign="top">
66 <row>
67 <entry><constant>V4L2_CID_BASE</constant></entry>
68 <entry></entry>
69 <entry>First predefined ID, equal to
70<constant>V4L2_CID_BRIGHTNESS</constant>.</entry>
71 </row>
72 <row>
73 <entry><constant>V4L2_CID_USER_BASE</constant></entry>
74 <entry></entry>
75 <entry>Synonym of <constant>V4L2_CID_BASE</constant>.</entry>
76 </row>
77 <row>
78 <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
79 <entry>integer</entry>
80 <entry>Picture brightness, or more precisely, the black
81level.</entry>
82 </row>
83 <row>
84 <entry><constant>V4L2_CID_CONTRAST</constant></entry>
85 <entry>integer</entry>
86 <entry>Picture contrast or luma gain.</entry>
87 </row>
88 <row>
89 <entry><constant>V4L2_CID_SATURATION</constant></entry>
90 <entry>integer</entry>
91 <entry>Picture color saturation or chroma gain.</entry>
92 </row>
93 <row>
94 <entry><constant>V4L2_CID_HUE</constant></entry>
95 <entry>integer</entry>
96 <entry>Hue or color balance.</entry>
97 </row>
98 <row>
99 <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
100 <entry>integer</entry>
101 <entry>Overall audio volume. Note some drivers also
102provide an OSS or ALSA mixer interface.</entry>
103 </row>
104 <row>
105 <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
106 <entry>integer</entry>
107 <entry>Audio stereo balance. Minimum corresponds to all
108the way left, maximum to right.</entry>
109 </row>
110 <row>
111 <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
112 <entry>integer</entry>
113 <entry>Audio bass adjustment.</entry>
114 </row>
115 <row>
116 <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
117 <entry>integer</entry>
118 <entry>Audio treble adjustment.</entry>
119 </row>
120 <row>
121 <entry><constant>V4L2_CID_AUDIO_MUTE</constant></entry>
122 <entry>boolean</entry>
123 <entry>Mute audio, &ie; set the volume to zero, however
124without affecting <constant>V4L2_CID_AUDIO_VOLUME</constant>. Like
125ALSA drivers, V4L2 drivers must mute at load time to avoid excessive
126noise. Actually the entire device should be reset to a low power
127consumption state.</entry>
128 </row>
129 <row>
130 <entry><constant>V4L2_CID_AUDIO_LOUDNESS</constant></entry>
131 <entry>boolean</entry>
132 <entry>Loudness mode (bass boost).</entry>
133 </row>
134 <row>
135 <entry><constant>V4L2_CID_BLACK_LEVEL</constant></entry>
136 <entry>integer</entry>
137 <entry>Another name for brightness (not a synonym of
138<constant>V4L2_CID_BRIGHTNESS</constant>). This control is deprecated
139and should not be used in new drivers and applications.</entry>
140 </row>
141 <row>
142 <entry><constant>V4L2_CID_AUTO_WHITE_BALANCE</constant></entry>
143 <entry>boolean</entry>
144 <entry>Automatic white balance (cameras).</entry>
145 </row>
146 <row>
147 <entry><constant>V4L2_CID_DO_WHITE_BALANCE</constant></entry>
148 <entry>button</entry>
149 <entry>This is an action control. When set (the value is
150ignored), the device will do a white balance and then hold the current
151setting. Contrast this with the boolean
152<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant>, which, when
153activated, keeps adjusting the white balance.</entry>
154 </row>
155 <row>
156 <entry><constant>V4L2_CID_RED_BALANCE</constant></entry>
157 <entry>integer</entry>
158 <entry>Red chroma balance.</entry>
159 </row>
160 <row>
161 <entry><constant>V4L2_CID_BLUE_BALANCE</constant></entry>
162 <entry>integer</entry>
163 <entry>Blue chroma balance.</entry>
164 </row>
165 <row>
166 <entry><constant>V4L2_CID_GAMMA</constant></entry>
167 <entry>integer</entry>
168 <entry>Gamma adjust.</entry>
169 </row>
170 <row>
171 <entry><constant>V4L2_CID_WHITENESS</constant></entry>
172 <entry>integer</entry>
173 <entry>Whiteness for grey-scale devices. This is a synonym
174for <constant>V4L2_CID_GAMMA</constant>. This control is deprecated
175and should not be used in new drivers and applications.</entry>
176 </row>
177 <row>
178 <entry><constant>V4L2_CID_EXPOSURE</constant></entry>
179 <entry>integer</entry>
180 <entry>Exposure (cameras). [Unit?]</entry>
181 </row>
182 <row>
183 <entry><constant>V4L2_CID_AUTOGAIN</constant></entry>
184 <entry>boolean</entry>
185 <entry>Automatic gain/exposure control.</entry>
186 </row>
187 <row>
188 <entry><constant>V4L2_CID_GAIN</constant></entry>
189 <entry>integer</entry>
190 <entry>Gain control.</entry>
191 </row>
192 <row>
193 <entry><constant>V4L2_CID_HFLIP</constant></entry>
194 <entry>boolean</entry>
195 <entry>Mirror the picture horizontally.</entry>
196 </row>
197 <row>
198 <entry><constant>V4L2_CID_VFLIP</constant></entry>
199 <entry>boolean</entry>
200 <entry>Mirror the picture vertically.</entry>
201 </row>
202 <row>
203 <entry><constant>V4L2_CID_HCENTER_DEPRECATED</constant> (formerly <constant>V4L2_CID_HCENTER</constant>)</entry>
204 <entry>integer</entry>
205 <entry>Horizontal image centering. This control is
206deprecated. New drivers and applications should use the <link
207linkend="camera-controls">Camera class controls</link>
208<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
209<constant>V4L2_CID_PAN_RELATIVE</constant> and
210<constant>V4L2_CID_PAN_RESET</constant> instead.</entry>
211 </row>
212 <row>
213 <entry><constant>V4L2_CID_VCENTER_DEPRECATED</constant>
214 (formerly <constant>V4L2_CID_VCENTER</constant>)</entry>
215 <entry>integer</entry>
216 <entry>Vertical image centering. Centering is intended to
217<emphasis>physically</emphasis> adjust cameras. For image cropping see
218<xref linkend="crop" />, for clipping <xref linkend="overlay" />. This
219control is deprecated. New drivers and applications should use the
220<link linkend="camera-controls">Camera class controls</link>
221<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
222<constant>V4L2_CID_TILT_RELATIVE</constant> and
223<constant>V4L2_CID_TILT_RESET</constant> instead.</entry>
224 </row>
225 <row id="v4l2-power-line-frequency">
226 <entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry>
227 <entry>enum</entry>
228 <entry>Enables a power line frequency filter to avoid
229flicker. Possible values for <constant>enum v4l2_power_line_frequency</constant> are:
230<constant>V4L2_CID_POWER_LINE_FREQUENCY_DISABLED</constant> (0),
231<constant>V4L2_CID_POWER_LINE_FREQUENCY_50HZ</constant> (1) and
232<constant>V4L2_CID_POWER_LINE_FREQUENCY_60HZ</constant> (2).</entry>
233 </row>
234 <row>
235 <entry><constant>V4L2_CID_HUE_AUTO</constant></entry>
236 <entry>boolean</entry>
237 <entry>Enables automatic hue control by the device. The
238effect of setting <constant>V4L2_CID_HUE</constant> while automatic
239hue control is enabled is undefined, drivers should ignore such
240request.</entry>
241 </row>
242 <row>
243 <entry><constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant></entry>
244 <entry>integer</entry>
245 <entry>This control specifies the white balance settings
246as a color temperature in Kelvin. A driver should have a minimum of
2472800 (incandescent) to 6500 (daylight). For more information about
248color temperature see <ulink
249url="http://en.wikipedia.org/wiki/Color_temperature">Wikipedia</ulink>.</entry>
250 </row>
251 <row>
252 <entry><constant>V4L2_CID_SHARPNESS</constant></entry>
253 <entry>integer</entry>
254 <entry>Adjusts the sharpness filters in a camera. The
255minimum value disables the filters, higher values give a sharper
256picture.</entry>
257 </row>
258 <row>
259 <entry><constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant></entry>
260 <entry>integer</entry>
261 <entry>Adjusts the backlight compensation in a camera. The
262minimum value disables backlight compensation.</entry>
263 </row>
264 <row>
265 <entry><constant>V4L2_CID_CHROMA_AGC</constant></entry>
266 <entry>boolean</entry>
267 <entry>Chroma automatic gain control.</entry>
268 </row>
269 <row>
270 <entry><constant>V4L2_CID_CHROMA_GAIN</constant></entry>
271 <entry>integer</entry>
272 <entry>Adjusts the Chroma gain control (for use when chroma AGC
273 is disabled).</entry>
274 </row>
275 <row>
276 <entry><constant>V4L2_CID_COLOR_KILLER</constant></entry>
277 <entry>boolean</entry>
278 <entry>Enable the color killer (&ie; force a black &amp; white image in case of a weak video signal).</entry>
279 </row>
280 <row id="v4l2-colorfx">
281 <entry><constant>V4L2_CID_COLORFX</constant></entry>
282 <entry>enum</entry>
283 <entry>Selects a color effect. Possible values for
284<constant>enum v4l2_colorfx</constant> are:
285<constant>V4L2_COLORFX_NONE</constant> (0),
286<constant>V4L2_COLORFX_BW</constant> (1),
287<constant>V4L2_COLORFX_SEPIA</constant> (2),
288<constant>V4L2_COLORFX_NEGATIVE</constant> (3),
289<constant>V4L2_COLORFX_EMBOSS</constant> (4),
290<constant>V4L2_COLORFX_SKETCH</constant> (5),
291<constant>V4L2_COLORFX_SKY_BLUE</constant> (6),
292<constant>V4L2_COLORFX_GRASS_GREEN</constant> (7),
293<constant>V4L2_COLORFX_SKIN_WHITEN</constant> (8) and
294<constant>V4L2_COLORFX_VIVID</constant> (9).</entry>
295 </row>
296 <row>
297 <entry><constant>V4L2_CID_ROTATE</constant></entry>
298 <entry>integer</entry>
299 <entry>Rotates the image by specified angle. Common angles are 90,
300 270 and 180. Rotating the image to 90 and 270 will reverse the height
301 and width of the display window. It is necessary to set the new height and
302 width of the picture using the &VIDIOC-S-FMT; ioctl according to
303 the rotation angle selected.</entry>
304 </row>
305 <row>
306 <entry><constant>V4L2_CID_BG_COLOR</constant></entry>
307 <entry>integer</entry>
308 <entry>Sets the background color on the current output device.
309 Background color needs to be specified in the RGB24 format. The
310 supplied 32 bit value is interpreted as bits 0-7 Red color information,
311 bits 8-15 Green color information, bits 16-23 Blue color
312 information and bits 24-31 must be zero.</entry>
313 </row>
314 <row>
315 <entry><constant>V4L2_CID_ILLUMINATORS_1</constant>
316 <constant>V4L2_CID_ILLUMINATORS_2</constant></entry>
317 <entry>boolean</entry>
318 <entry>Switch on or off the illuminator 1 or 2 of the device
319 (usually a microscope).</entry>
320 </row>
321 <row>
322 <entry><constant>V4L2_CID_LASTP1</constant></entry>
323 <entry></entry>
324 <entry>End of the predefined control IDs (currently
325<constant>V4L2_CID_ILLUMINATORS_2</constant> + 1).</entry>
326 </row>
327 <row>
328 <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry>
329 <entry></entry>
330 <entry>ID of the first custom (driver specific) control.
331Applications depending on particular custom controls should check the
332driver name and version, see <xref linkend="querycap" />.</entry>
333 </row>
334 </tbody>
335 </tgroup>
336 </table>
337
338 <para>Applications can enumerate the available controls with the
339&VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a
340control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls.
341Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,
342<constant>VIDIOC_G_CTRL</constant> and
343<constant>VIDIOC_S_CTRL</constant> when the device has one or more
344controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
345more menu type controls.</para>
346
347 <example>
348 <title>Enumerating all controls</title>
349
350 <programlisting>
351&v4l2-queryctrl; queryctrl;
352&v4l2-querymenu; querymenu;
353
354static void
355enumerate_menu (void)
356{
357 printf (" Menu items:\n");
358
359 memset (&amp;querymenu, 0, sizeof (querymenu));
360 querymenu.id = queryctrl.id;
361
362 for (querymenu.index = queryctrl.minimum;
363 querymenu.index &lt;= queryctrl.maximum;
364 querymenu.index++) {
365 if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
366 printf (" %s\n", querymenu.name);
367 }
368 }
369}
370
371memset (&amp;queryctrl, 0, sizeof (queryctrl));
372
373for (queryctrl.id = V4L2_CID_BASE;
374 queryctrl.id &lt; V4L2_CID_LASTP1;
375 queryctrl.id++) {
376 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
377 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
378 continue;
379
380 printf ("Control %s\n", queryctrl.name);
381
382 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
383 enumerate_menu ();
384 } else {
385 if (errno == EINVAL)
386 continue;
387
388 perror ("VIDIOC_QUERYCTRL");
389 exit (EXIT_FAILURE);
390 }
391}
392
393for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
394 queryctrl.id++) {
395 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
396 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
397 continue;
398
399 printf ("Control %s\n", queryctrl.name);
400
401 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
402 enumerate_menu ();
403 } else {
404 if (errno == EINVAL)
405 break;
406
407 perror ("VIDIOC_QUERYCTRL");
408 exit (EXIT_FAILURE);
409 }
410}
411</programlisting>
412 </example>
413
414 <example>
415 <title>Changing controls</title>
416
417 <programlisting>
418&v4l2-queryctrl; queryctrl;
419&v4l2-control; control;
420
421memset (&amp;queryctrl, 0, sizeof (queryctrl));
422queryctrl.id = V4L2_CID_BRIGHTNESS;
423
424if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
425 if (errno != EINVAL) {
426 perror ("VIDIOC_QUERYCTRL");
427 exit (EXIT_FAILURE);
428 } else {
429 printf ("V4L2_CID_BRIGHTNESS is not supported\n");
430 }
431} else if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) {
432 printf ("V4L2_CID_BRIGHTNESS is not supported\n");
433} else {
434 memset (&amp;control, 0, sizeof (control));
435 control.id = V4L2_CID_BRIGHTNESS;
436 control.value = queryctrl.default_value;
437
438 if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)) {
439 perror ("VIDIOC_S_CTRL");
440 exit (EXIT_FAILURE);
441 }
442}
443
444memset (&amp;control, 0, sizeof (control));
445control.id = V4L2_CID_CONTRAST;
446
447if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &amp;control)) {
448 control.value += 1;
449
450 /* The driver may clamp the value or return ERANGE, ignored here */
451
452 if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)
453 &amp;&amp; errno != ERANGE) {
454 perror ("VIDIOC_S_CTRL");
455 exit (EXIT_FAILURE);
456 }
457/* Ignore if V4L2_CID_CONTRAST is unsupported */
458} else if (errno != EINVAL) {
459 perror ("VIDIOC_G_CTRL");
460 exit (EXIT_FAILURE);
461}
462
463control.id = V4L2_CID_AUDIO_MUTE;
464control.value = TRUE; /* silence */
465
466/* Errors ignored */
467ioctl (fd, VIDIOC_S_CTRL, &amp;control);
468</programlisting>
469 </example>
470 </section>
471
472 <section id="extended-controls">
473 <title>Extended Controls</title>
474
475 <section>
476 <title>Introduction</title>
477
478 <para>The control mechanism as originally designed was meant
479to be used for user settings (brightness, saturation, etc). However,
480it turned out to be a very useful model for implementing more
481complicated driver APIs where each driver implements only a subset of
482a larger API.</para>
483
484 <para>The MPEG encoding API was the driving force behind
485designing and implementing this extended control mechanism: the MPEG
486standard is quite large and the currently supported hardware MPEG
487encoders each only implement a subset of this standard. Further more,
488many parameters relating to how the video is encoded into an MPEG
489stream are specific to the MPEG encoding chip since the MPEG standard
490only defines the format of the resulting MPEG stream, not how the
491video is actually encoded into that format.</para>
492
493 <para>Unfortunately, the original control API lacked some
494features needed for these new uses and so it was extended into the
495(not terribly originally named) extended control API.</para>
496
497 <para>Even though the MPEG encoding API was the first effort
498to use the Extended Control API, nowadays there are also other classes
499of Extended Controls, such as Camera Controls and FM Transmitter Controls.
500The Extended Controls API as well as all Extended Controls classes are
501described in the following text.</para>
502 </section>
503
504 <section>
505 <title>The Extended Control API</title>
506
507 <para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;,
508&VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on
509arrays of controls (as opposed to the &VIDIOC-G-CTRL; and
510&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed
511since it is often required to atomically change several controls at
512once.</para>
513
514 <para>Each of the new ioctls expects a pointer to a
515&v4l2-ext-controls;. This structure contains a pointer to the control
516array, a count of the number of controls in that array and a control
517class. Control classes are used to group similar controls into a
518single class. For example, control class
519<constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls
520(&ie; all controls that can also be set using the old
521<constant>VIDIOC_S_CTRL</constant> ioctl). Control class
522<constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls
523relating to MPEG encoding, etc.</para>
524
525 <para>All controls in the control array must belong to the
526specified control class. An error is returned if this is not the
527case.</para>
528
529 <para>It is also possible to use an empty control array (count
530== 0) to check whether the specified control class is
531supported.</para>
532
533 <para>The control array is a &v4l2-ext-control; array. The
534<structname>v4l2_ext_control</structname> structure is very similar to
535&v4l2-control;, except for the fact that it also allows for 64-bit
536values and pointers to be passed.</para>
537
538 <para>It is important to realize that due to the flexibility of
539controls it is necessary to check whether the control you want to set
540actually is supported in the driver and what the valid range of values
541is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to
542check this. Also note that it is possible that some of the menu
543indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant>
544may not be supported (<constant>VIDIOC_QUERYMENU</constant> will
545return an error). A good example is the list of supported MPEG audio
546bitrates. Some drivers only support one or two bitrates, others
547support a wider range.</para>
548 </section>
549
550 <section>
551 <title>Enumerating Extended Controls</title>
552
553 <para>The recommended way to enumerate over the extended
554controls is by using &VIDIOC-QUERYCTRL; in combination with the
555<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para>
556
557 <informalexample>
558 <programlisting>
559&v4l2-queryctrl; qctrl;
560
561qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
562while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
563 /* ... */
564 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
565}
566</programlisting>
567 </informalexample>
568
569 <para>The initial control ID is set to 0 ORed with the
570<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The
571<constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first
572control with a higher ID than the specified one. When no such controls
573are found an error is returned.</para>
574
575 <para>If you want to get all controls within a specific control
576class, then you can set the initial
577<structfield>qctrl.id</structfield> value to the control class and add
578an extra check to break out of the loop when a control of another
579control class is found:</para>
580
581 <informalexample>
582 <programlisting>
583qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
584while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
585 if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)
586 break;
587 /* ... */
588 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
589 }
590</programlisting>
591 </informalexample>
592
593 <para>The 32-bit <structfield>qctrl.id</structfield> value is
594subdivided into three bit ranges: the top 4 bits are reserved for
595flags (&eg; <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not
596actually part of the ID. The remaining 28 bits form the control ID, of
597which the most significant 12 bits define the control class and the
598least significant 16 bits identify the control within the control
599class. It is guaranteed that these last 16 bits are always non-zero
600for controls. The range of 0x1000 and up are reserved for
601driver-specific controls. The macro
602<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class
603ID based on a control ID.</para>
604
605 <para>If the driver does not support extended controls, then
606<constant>VIDIOC_QUERYCTRL</constant> will fail when used in
607combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
608that case the old method of enumerating control should be used (see
6091.8). But if it is supported, then it is guaranteed to enumerate over
610all controls, including driver-private controls.</para>
611 </section>
612
613 <section>
614 <title>Creating Control Panels</title>
615
616 <para>It is possible to create control panels for a graphical
617user interface where the user can select the various controls.
618Basically you will have to iterate over all controls using the method
619described above. Each control class starts with a control of type
620<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>.
621<constant>VIDIOC_QUERYCTRL</constant> will return the name of this
622control class which can be used as the title of a tab page within a
623control panel.</para>
624
625 <para>The flags field of &v4l2-queryctrl; also contains hints on
626the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation
627for more details.</para>
628 </section>
629
630 <section id="mpeg-controls">
631 <title>MPEG Control Reference</title>
632
633 <para>Below all controls within the MPEG control class are
634described. First the generic controls, then controls specific for
635certain hardware.</para>
636
637 <section>
638 <title>Generic MPEG Controls</title>
639
640 <table pgwide="1" frame="none" id="mpeg-control-id">
641 <title>MPEG Control IDs</title>
642 <tgroup cols="4">
643 <colspec colname="c1" colwidth="1*" />
644 <colspec colname="c2" colwidth="6*" />
645 <colspec colname="c3" colwidth="2*" />
646 <colspec colname="c4" colwidth="6*" />
647 <spanspec namest="c1" nameend="c2" spanname="id" />
648 <spanspec namest="c2" nameend="c4" spanname="descr" />
649 <thead>
650 <row>
651 <entry spanname="id" align="left">ID</entry>
652 <entry align="left">Type</entry>
653 </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
654 </row>
655 </thead>
656 <tbody valign="top">
657 <row><entry></entry></row>
658 <row>
659 <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant>&nbsp;</entry>
660 <entry>class</entry>
661 </row><row><entry spanname="descr">The MPEG class
662descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
663description of this control class. This description can be used as the
664caption of a Tab page in a GUI, for example.</entry>
665 </row>
666 <row><entry></entry></row>
667 <row id="v4l2-mpeg-stream-type">
668 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant>&nbsp;</entry>
669 <entry>enum&nbsp;v4l2_mpeg_stream_type</entry>
670 </row><row><entry spanname="descr">The MPEG-1, -2 or -4
671output stream type. One cannot assume anything here. Each hardware
672MPEG encoder tends to support different subsets of the available MPEG
673stream types. The currently defined stream types are:</entry>
674 </row>
675 <row>
676 <entrytbl spanname="descr" cols="2">
677 <tbody valign="top">
678 <row>
679 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant>&nbsp;</entry>
680 <entry>MPEG-2 program stream</entry>
681 </row>
682 <row>
683 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant>&nbsp;</entry>
684 <entry>MPEG-2 transport stream</entry>
685 </row>
686 <row>
687 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant>&nbsp;</entry>
688 <entry>MPEG-1 system stream</entry>
689 </row>
690 <row>
691 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant>&nbsp;</entry>
692 <entry>MPEG-2 DVD-compatible stream</entry>
693 </row>
694 <row>
695 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant>&nbsp;</entry>
696 <entry>MPEG-1 VCD-compatible stream</entry>
697 </row>
698 <row>
699 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant>&nbsp;</entry>
700 <entry>MPEG-2 SVCD-compatible stream</entry>
701 </row>
702 </tbody>
703 </entrytbl>
704 </row>
705 <row><entry></entry></row>
706 <row>
707 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant>&nbsp;</entry>
708 <entry>integer</entry>
709 </row><row><entry spanname="descr">Program Map Table
710Packet ID for the MPEG transport stream (default 16)</entry>
711 </row>
712 <row><entry></entry></row>
713 <row>
714 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant>&nbsp;</entry>
715 <entry>integer</entry>
716 </row><row><entry spanname="descr">Audio Packet ID for
717the MPEG transport stream (default 256)</entry>
718 </row>
719 <row><entry></entry></row>
720 <row>
721 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant>&nbsp;</entry>
722 <entry>integer</entry>
723 </row><row><entry spanname="descr">Video Packet ID for
724the MPEG transport stream (default 260)</entry>
725 </row>
726 <row><entry></entry></row>
727 <row>
728 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant>&nbsp;</entry>
729 <entry>integer</entry>
730 </row><row><entry spanname="descr">Packet ID for the
731MPEG transport stream carrying PCR fields (default 259)</entry>
732 </row>
733 <row><entry></entry></row>
734 <row>
735 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant>&nbsp;</entry>
736 <entry>integer</entry>
737 </row><row><entry spanname="descr">Audio ID for MPEG
738PES</entry>
739 </row>
740 <row><entry></entry></row>
741 <row>
742 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant>&nbsp;</entry>
743 <entry>integer</entry>
744 </row><row><entry spanname="descr">Video ID for MPEG
745PES</entry>
746 </row>
747 <row><entry></entry></row>
748 <row id="v4l2-mpeg-stream-vbi-fmt">
749 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant>&nbsp;</entry>
750 <entry>enum&nbsp;v4l2_mpeg_stream_vbi_fmt</entry>
751 </row><row><entry spanname="descr">Some cards can embed
752VBI data (&eg; Closed Caption, Teletext) into the MPEG stream. This
753control selects whether VBI data should be embedded, and if so, what
754embedding method should be used. The list of possible VBI formats
755depends on the driver. The currently defined VBI format types
756are:</entry>
757 </row>
758 <row>
759 <entrytbl spanname="descr" cols="2">
760 <tbody valign="top">
761 <row>
762 <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant>&nbsp;</entry>
763 <entry>No VBI in the MPEG stream</entry>
764 </row>
765 <row>
766 <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant>&nbsp;</entry>
767 <entry>VBI in private packets, IVTV format (documented
768in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry>
769 </row>
770 </tbody>
771 </entrytbl>
772 </row>
773 <row><entry></entry></row>
774 <row id="v4l2-mpeg-audio-sampling-freq">
775 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant>&nbsp;</entry>
776 <entry>enum&nbsp;v4l2_mpeg_audio_sampling_freq</entry>
777 </row><row><entry spanname="descr">MPEG Audio sampling
778frequency. Possible values are:</entry>
779 </row>
780 <row>
781 <entrytbl spanname="descr" cols="2">
782 <tbody valign="top">
783 <row>
784 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant>&nbsp;</entry>
785 <entry>44.1 kHz</entry>
786 </row>
787 <row>
788 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant>&nbsp;</entry>
789 <entry>48 kHz</entry>
790 </row>
791 <row>
792 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant>&nbsp;</entry>
793 <entry>32 kHz</entry>
794 </row>
795 </tbody>
796 </entrytbl>
797 </row>
798 <row><entry></entry></row>
799 <row id="v4l2-mpeg-audio-encoding">
800 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant>&nbsp;</entry>
801 <entry>enum&nbsp;v4l2_mpeg_audio_encoding</entry>
802 </row><row><entry spanname="descr">MPEG Audio encoding.
803Possible values are:</entry>
804 </row>
805 <row>
806 <entrytbl spanname="descr" cols="2">
807 <tbody valign="top">
808 <row>
809 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant>&nbsp;</entry>
810 <entry>MPEG-1/2 Layer I encoding</entry>
811 </row>
812 <row>
813 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant>&nbsp;</entry>
814 <entry>MPEG-1/2 Layer II encoding</entry>
815 </row>
816 <row>
817 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant>&nbsp;</entry>
818 <entry>MPEG-1/2 Layer III encoding</entry>
819 </row>
820 <row>
821 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant>&nbsp;</entry>
822 <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry>
823 </row>
824 <row>
825 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant>&nbsp;</entry>
826 <entry>AC-3 aka ATSC A/52 encoding</entry>
827 </row>
828 </tbody>
829 </entrytbl>
830 </row>
831 <row><entry></entry></row>
832 <row id="v4l2-mpeg-audio-l1-bitrate">
833 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant>&nbsp;</entry>
834 <entry>enum&nbsp;v4l2_mpeg_audio_l1_bitrate</entry>
835 </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate.
836Possible values are:</entry>
837 </row>
838 <row>
839 <entrytbl spanname="descr" cols="2">
840 <tbody valign="top">
841 <row>
842 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant>&nbsp;</entry>
843 <entry>32 kbit/s</entry></row>
844 <row>
845 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant>&nbsp;</entry>
846 <entry>64 kbit/s</entry>
847 </row>
848 <row>
849 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant>&nbsp;</entry>
850 <entry>96 kbit/s</entry>
851 </row>
852 <row>
853 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant>&nbsp;</entry>
854 <entry>128 kbit/s</entry>
855 </row>
856 <row>
857 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant>&nbsp;</entry>
858 <entry>160 kbit/s</entry>
859 </row>
860 <row>
861 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant>&nbsp;</entry>
862 <entry>192 kbit/s</entry>
863 </row>
864 <row>
865 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant>&nbsp;</entry>
866 <entry>224 kbit/s</entry>
867 </row>
868 <row>
869 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant>&nbsp;</entry>
870 <entry>256 kbit/s</entry>
871 </row>
872 <row>
873 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant>&nbsp;</entry>
874 <entry>288 kbit/s</entry>
875 </row>
876 <row>
877 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant>&nbsp;</entry>
878 <entry>320 kbit/s</entry>
879 </row>
880 <row>
881 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant>&nbsp;</entry>
882 <entry>352 kbit/s</entry>
883 </row>
884 <row>
885 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant>&nbsp;</entry>
886 <entry>384 kbit/s</entry>
887 </row>
888 <row>
889 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant>&nbsp;</entry>
890 <entry>416 kbit/s</entry>
891 </row>
892 <row>
893 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant>&nbsp;</entry>
894 <entry>448 kbit/s</entry>
895 </row>
896 </tbody>
897 </entrytbl>
898 </row>
899 <row><entry></entry></row>
900 <row id="v4l2-mpeg-audio-l2-bitrate">
901 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant>&nbsp;</entry>
902 <entry>enum&nbsp;v4l2_mpeg_audio_l2_bitrate</entry>
903 </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate.
904Possible values are:</entry>
905 </row>
906 <row>
907 <entrytbl spanname="descr" cols="2">
908 <tbody valign="top">
909 <row>
910 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant>&nbsp;</entry>
911 <entry>32 kbit/s</entry>
912 </row>
913 <row>
914 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant>&nbsp;</entry>
915 <entry>48 kbit/s</entry>
916 </row>
917 <row>
918 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant>&nbsp;</entry>
919 <entry>56 kbit/s</entry>
920 </row>
921 <row>
922 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant>&nbsp;</entry>
923 <entry>64 kbit/s</entry>
924 </row>
925 <row>
926 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant>&nbsp;</entry>
927 <entry>80 kbit/s</entry>
928 </row>
929 <row>
930 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant>&nbsp;</entry>
931 <entry>96 kbit/s</entry>
932 </row>
933 <row>
934 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant>&nbsp;</entry>
935 <entry>112 kbit/s</entry>
936 </row>
937 <row>
938 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant>&nbsp;</entry>
939 <entry>128 kbit/s</entry>
940 </row>
941 <row>
942 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant>&nbsp;</entry>
943 <entry>160 kbit/s</entry>
944 </row>
945 <row>
946 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant>&nbsp;</entry>
947 <entry>192 kbit/s</entry>
948 </row>
949 <row>
950 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant>&nbsp;</entry>
951 <entry>224 kbit/s</entry>
952 </row>
953 <row>
954 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant>&nbsp;</entry>
955 <entry>256 kbit/s</entry>
956 </row>
957 <row>
958 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant>&nbsp;</entry>
959 <entry>320 kbit/s</entry>
960 </row>
961 <row>
962 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant>&nbsp;</entry>
963 <entry>384 kbit/s</entry>
964 </row>
965 </tbody>
966 </entrytbl>
967 </row>
968 <row><entry></entry></row>
969 <row id="v4l2-mpeg-audio-l3-bitrate">
970 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant>&nbsp;</entry>
971 <entry>enum&nbsp;v4l2_mpeg_audio_l3_bitrate</entry>
972 </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate.
973Possible values are:</entry>
974 </row>
975 <row>
976 <entrytbl spanname="descr" cols="2">
977 <tbody valign="top">
978 <row>
979 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant>&nbsp;</entry>
980 <entry>32 kbit/s</entry>
981 </row>
982 <row>
983 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant>&nbsp;</entry>
984 <entry>40 kbit/s</entry>
985 </row>
986 <row>
987 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant>&nbsp;</entry>
988 <entry>48 kbit/s</entry>
989 </row>
990 <row>
991 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant>&nbsp;</entry>
992 <entry>56 kbit/s</entry>
993 </row>
994 <row>
995 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant>&nbsp;</entry>
996 <entry>64 kbit/s</entry>
997 </row>
998 <row>
999 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant>&nbsp;</entry>
1000 <entry>80 kbit/s</entry>
1001 </row>
1002 <row>
1003 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant>&nbsp;</entry>
1004 <entry>96 kbit/s</entry>
1005 </row>
1006 <row>
1007 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant>&nbsp;</entry>
1008 <entry>112 kbit/s</entry>
1009 </row>
1010 <row>
1011 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant>&nbsp;</entry>
1012 <entry>128 kbit/s</entry>
1013 </row>
1014 <row>
1015 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant>&nbsp;</entry>
1016 <entry>160 kbit/s</entry>
1017 </row>
1018 <row>
1019 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant>&nbsp;</entry>
1020 <entry>192 kbit/s</entry>
1021 </row>
1022 <row>
1023 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant>&nbsp;</entry>
1024 <entry>224 kbit/s</entry>
1025 </row>
1026 <row>
1027 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant>&nbsp;</entry>
1028 <entry>256 kbit/s</entry>
1029 </row>
1030 <row>
1031 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant>&nbsp;</entry>
1032 <entry>320 kbit/s</entry>
1033 </row>
1034 </tbody>
1035 </entrytbl>
1036 </row>
1037 <row><entry></entry></row>
1038 <row>
1039 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant>&nbsp;</entry>
1040 <entry>integer</entry>
1041 </row><row><entry spanname="descr">AAC bitrate in bits per second.</entry>
1042 </row>
1043 <row><entry></entry></row>
1044 <row id="v4l2-mpeg-audio-ac3-bitrate">
1045 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant>&nbsp;</entry>
1046 <entry>enum&nbsp;v4l2_mpeg_audio_ac3_bitrate</entry>
1047 </row><row><entry spanname="descr">AC-3 bitrate.
1048Possible values are:</entry>
1049 </row>
1050 <row>
1051 <entrytbl spanname="descr" cols="2">
1052 <tbody valign="top">
1053 <row>
1054 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant>&nbsp;</entry>
1055 <entry>32 kbit/s</entry>
1056 </row>
1057 <row>
1058 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant>&nbsp;</entry>
1059 <entry>40 kbit/s</entry>
1060 </row>
1061 <row>
1062 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant>&nbsp;</entry>
1063 <entry>48 kbit/s</entry>
1064 </row>
1065 <row>
1066 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant>&nbsp;</entry>
1067 <entry>56 kbit/s</entry>
1068 </row>
1069 <row>
1070 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant>&nbsp;</entry>
1071 <entry>64 kbit/s</entry>
1072 </row>
1073 <row>
1074 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant>&nbsp;</entry>
1075 <entry>80 kbit/s</entry>
1076 </row>
1077 <row>
1078 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant>&nbsp;</entry>
1079 <entry>96 kbit/s</entry>
1080 </row>
1081 <row>
1082 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant>&nbsp;</entry>
1083 <entry>112 kbit/s</entry>
1084 </row>
1085 <row>
1086 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant>&nbsp;</entry>
1087 <entry>128 kbit/s</entry>
1088 </row>
1089 <row>
1090 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant>&nbsp;</entry>
1091 <entry>160 kbit/s</entry>
1092 </row>
1093 <row>
1094 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant>&nbsp;</entry>
1095 <entry>192 kbit/s</entry>
1096 </row>
1097 <row>
1098 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant>&nbsp;</entry>
1099 <entry>224 kbit/s</entry>
1100 </row>
1101 <row>
1102 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant>&nbsp;</entry>
1103 <entry>256 kbit/s</entry>
1104 </row>
1105 <row>
1106 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant>&nbsp;</entry>
1107 <entry>320 kbit/s</entry>
1108 </row>
1109 <row>
1110 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant>&nbsp;</entry>
1111 <entry>384 kbit/s</entry>
1112 </row>
1113 <row>
1114 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant>&nbsp;</entry>
1115 <entry>448 kbit/s</entry>
1116 </row>
1117 <row>
1118 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant>&nbsp;</entry>
1119 <entry>512 kbit/s</entry>
1120 </row>
1121 <row>
1122 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant>&nbsp;</entry>
1123 <entry>576 kbit/s</entry>
1124 </row>
1125 <row>
1126 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant>&nbsp;</entry>
1127 <entry>640 kbit/s</entry>
1128 </row>
1129 </tbody>
1130 </entrytbl>
1131 </row>
1132 <row><entry></entry></row>
1133 <row id="v4l2-mpeg-audio-mode">
1134 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant>&nbsp;</entry>
1135 <entry>enum&nbsp;v4l2_mpeg_audio_mode</entry>
1136 </row><row><entry spanname="descr">MPEG Audio mode.
1137Possible values are:</entry>
1138 </row>
1139 <row>
1140 <entrytbl spanname="descr" cols="2">
1141 <tbody valign="top">
1142 <row>
1143 <entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant>&nbsp;</entry>
1144 <entry>Stereo</entry>
1145 </row>
1146 <row>
1147 <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant>&nbsp;</entry>
1148 <entry>Joint Stereo</entry>
1149 </row>
1150 <row>
1151 <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant>&nbsp;</entry>
1152 <entry>Bilingual</entry>
1153 </row>
1154 <row>
1155 <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant>&nbsp;</entry>
1156 <entry>Mono</entry>
1157 </row>
1158 </tbody>
1159 </entrytbl>
1160 </row>
1161 <row><entry></entry></row>
1162 <row id="v4l2-mpeg-audio-mode-extension">
1163 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant>&nbsp;</entry>
1164 <entry>enum&nbsp;v4l2_mpeg_audio_mode_extension</entry>
1165 </row><row><entry spanname="descr">Joint Stereo
1166audio mode extension. In Layer I and II they indicate which subbands
1167are in intensity stereo. All other subbands are coded in stereo. Layer
1168III is not (yet) supported. Possible values
1169are:</entry>
1170 </row>
1171 <row>
1172 <entrytbl spanname="descr" cols="2">
1173 <tbody valign="top">
1174 <row>
1175 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant>&nbsp;</entry>
1176 <entry>Subbands 4-31 in intensity stereo</entry>
1177 </row>
1178 <row>
1179 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant>&nbsp;</entry>
1180 <entry>Subbands 8-31 in intensity stereo</entry>
1181 </row>
1182 <row>
1183 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant>&nbsp;</entry>
1184 <entry>Subbands 12-31 in intensity stereo</entry>
1185 </row>
1186 <row>
1187 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant>&nbsp;</entry>
1188 <entry>Subbands 16-31 in intensity stereo</entry>
1189 </row>
1190 </tbody>
1191 </entrytbl>
1192 </row>
1193 <row><entry></entry></row>
1194 <row id="v4l2-mpeg-audio-emphasis">
1195 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant>&nbsp;</entry>
1196 <entry>enum&nbsp;v4l2_mpeg_audio_emphasis</entry>
1197 </row><row><entry spanname="descr">Audio Emphasis.
1198Possible values are:</entry>
1199 </row>
1200 <row>
1201 <entrytbl spanname="descr" cols="2">
1202 <tbody valign="top">
1203 <row>
1204 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant>&nbsp;</entry>
1205 <entry>None</entry>
1206 </row>
1207 <row>
1208 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant>&nbsp;</entry>
1209 <entry>50/15 microsecond emphasis</entry>
1210 </row>
1211 <row>
1212 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant>&nbsp;</entry>
1213 <entry>CCITT J.17</entry>
1214 </row>
1215 </tbody>
1216 </entrytbl>
1217 </row>
1218 <row><entry></entry></row>
1219 <row id="v4l2-mpeg-audio-crc">
1220 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant>&nbsp;</entry>
1221 <entry>enum&nbsp;v4l2_mpeg_audio_crc</entry>
1222 </row><row><entry spanname="descr">CRC method. Possible
1223values are:</entry>
1224 </row>
1225 <row>
1226 <entrytbl spanname="descr" cols="2">
1227 <tbody valign="top">
1228 <row>
1229 <entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant>&nbsp;</entry>
1230 <entry>None</entry>
1231 </row>
1232 <row>
1233 <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant>&nbsp;</entry>
1234 <entry>16 bit parity check</entry>
1235 </row>
1236 </tbody>
1237 </entrytbl>
1238 </row>
1239 <row><entry></entry></row>
1240 <row>
1241 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant>&nbsp;</entry>
1242 <entry>boolean</entry>
1243 </row><row><entry spanname="descr">Mutes the audio when
1244capturing. This is not done by muting audio hardware, which can still
1245produce a slight hiss, but in the encoder itself, guaranteeing a fixed
1246and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry>
1247 </row>
1248 <row><entry></entry></row>
1249 <row id="v4l2-mpeg-video-encoding">
1250 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant>&nbsp;</entry>
1251 <entry>enum&nbsp;v4l2_mpeg_video_encoding</entry>
1252 </row><row><entry spanname="descr">MPEG Video encoding
1253method. Possible values are:</entry>
1254 </row>
1255 <row>
1256 <entrytbl spanname="descr" cols="2">
1257 <tbody valign="top">
1258 <row>
1259 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant>&nbsp;</entry>
1260 <entry>MPEG-1 Video encoding</entry>
1261 </row>
1262 <row>
1263 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant>&nbsp;</entry>
1264 <entry>MPEG-2 Video encoding</entry>
1265 </row>
1266 <row>
1267 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant>&nbsp;</entry>
1268 <entry>MPEG-4 AVC (H.264) Video encoding</entry>
1269 </row>
1270 </tbody>
1271 </entrytbl>
1272 </row>
1273 <row><entry></entry></row>
1274 <row id="v4l2-mpeg-video-aspect">
1275 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant>&nbsp;</entry>
1276 <entry>enum&nbsp;v4l2_mpeg_video_aspect</entry>
1277 </row><row><entry spanname="descr">Video aspect.
1278Possible values are:</entry>
1279 </row>
1280 <row>
1281 <entrytbl spanname="descr" cols="2">
1282 <tbody valign="top">
1283 <row>
1284 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant>&nbsp;</entry>
1285 </row>
1286 <row>
1287 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant>&nbsp;</entry>
1288 </row>
1289 <row>
1290 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant>&nbsp;</entry>
1291 </row>
1292 <row>
1293 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant>&nbsp;</entry>
1294 </row>
1295 </tbody>
1296 </entrytbl>
1297 </row>
1298 <row><entry></entry></row>
1299 <row>
1300 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant>&nbsp;</entry>
1301 <entry>integer</entry>
1302 </row><row><entry spanname="descr">Number of B-Frames
1303(default 2)</entry>
1304 </row>
1305 <row><entry></entry></row>
1306 <row>
1307 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant>&nbsp;</entry>
1308 <entry>integer</entry>
1309 </row><row><entry spanname="descr">GOP size (default
131012)</entry>
1311 </row>
1312 <row><entry></entry></row>
1313 <row>
1314 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant>&nbsp;</entry>
1315 <entry>boolean</entry>
1316 </row><row><entry spanname="descr">GOP closure (default
13171)</entry>
1318 </row>
1319 <row><entry></entry></row>
1320 <row>
1321 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant>&nbsp;</entry>
1322 <entry>boolean</entry>
1323 </row><row><entry spanname="descr">Enable 3:2 pulldown
1324(default 0)</entry>
1325 </row>
1326 <row><entry></entry></row>
1327 <row id="v4l2-mpeg-video-bitrate-mode">
1328 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant>&nbsp;</entry>
1329 <entry>enum&nbsp;v4l2_mpeg_video_bitrate_mode</entry>
1330 </row><row><entry spanname="descr">Video bitrate mode.
1331Possible values are:</entry>
1332 </row>
1333 <row>
1334 <entrytbl spanname="descr" cols="2">
1335 <tbody valign="top">
1336 <row>
1337 <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant>&nbsp;</entry>
1338 <entry>Variable bitrate</entry>
1339 </row>
1340 <row>
1341 <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant>&nbsp;</entry>
1342 <entry>Constant bitrate</entry>
1343 </row>
1344 </tbody>
1345 </entrytbl>
1346 </row>
1347 <row><entry></entry></row>
1348 <row>
1349 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant>&nbsp;</entry>
1350 <entry>integer</entry>
1351 </row><row><entry spanname="descr">Video bitrate in bits
1352per second.</entry>
1353 </row>
1354 <row><entry></entry></row>
1355 <row>
1356 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant>&nbsp;</entry>
1357 <entry>integer</entry>
1358 </row><row><entry spanname="descr">Peak video bitrate in
1359bits per second. Must be larger or equal to the average video bitrate.
1360It is ignored if the video bitrate mode is set to constant
1361bitrate.</entry>
1362 </row>
1363 <row><entry></entry></row>
1364 <row>
1365 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant>&nbsp;</entry>
1366 <entry>integer</entry>
1367 </row><row><entry spanname="descr">For every captured
1368frame, skip this many subsequent frames (default 0).</entry>
1369 </row>
1370 <row><entry></entry></row>
1371 <row>
1372 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant>&nbsp;</entry>
1373 <entry>boolean</entry>
1374 </row>
1375 <row><entry spanname="descr">"Mutes" the video to a
1376fixed color when capturing. This is useful for testing, to produce a
1377fixed video bitstream. 0 = unmuted, 1 = muted.</entry>
1378 </row>
1379 <row><entry></entry></row>
1380 <row>
1381 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant>&nbsp;</entry>
1382 <entry>integer</entry>
1383 </row><row><entry spanname="descr">Sets the "mute" color
1384of the video. The supplied 32-bit integer is interpreted as follows (bit
13850 = least significant bit):</entry>
1386 </row>
1387 <row>
1388 <entrytbl spanname="descr" cols="2">
1389 <tbody valign="top">
1390 <row>
1391 <entry>Bit 0:7</entry>
1392 <entry>V chrominance information</entry>
1393 </row>
1394 <row>
1395 <entry>Bit 8:15</entry>
1396 <entry>U chrominance information</entry>
1397 </row>
1398 <row>
1399 <entry>Bit 16:23</entry>
1400 <entry>Y luminance information</entry>
1401 </row>
1402 <row>
1403 <entry>Bit 24:31</entry>
1404 <entry>Must be zero.</entry>
1405 </row>
1406 </tbody>
1407 </entrytbl>
1408 </row>
1409 </tbody>
1410 </tgroup>
1411 </table>
1412 </section>
1413
1414 <section>
1415 <title>CX2341x MPEG Controls</title>
1416
1417 <para>The following MPEG class controls deal with MPEG
1418encoding settings that are specific to the Conexant CX23415 and
1419CX23416 MPEG encoding chips.</para>
1420
1421 <table pgwide="1" frame="none" id="cx2341x-control-id">
1422 <title>CX2341x Control IDs</title>
1423 <tgroup cols="4">
1424 <colspec colname="c1" colwidth="1*" />
1425 <colspec colname="c2" colwidth="6*" />
1426 <colspec colname="c3" colwidth="2*" />
1427 <colspec colname="c4" colwidth="6*" />
1428 <spanspec namest="c1" nameend="c2" spanname="id" />
1429 <spanspec namest="c2" nameend="c4" spanname="descr" />
1430 <thead>
1431 <row>
1432 <entry spanname="id" align="left">ID</entry>
1433 <entry align="left">Type</entry>
1434 </row><row><entry spanname="descr" align="left">Description</entry>
1435 </row>
1436 </thead>
1437 <tbody valign="top">
1438 <row><entry></entry></row>
1439 <row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode">
1440 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant>&nbsp;</entry>
1441 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry>
1442 </row><row><entry spanname="descr">Sets the Spatial
1443Filter mode (default <constant>MANUAL</constant>). Possible values
1444are:</entry>
1445 </row>
1446 <row>
1447 <entrytbl spanname="descr" cols="2">
1448 <tbody valign="top">
1449 <row>
1450 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
1451 <entry>Choose the filter manually</entry>
1452 </row>
1453 <row>
1454 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
1455 <entry>Choose the filter automatically</entry>
1456 </row>
1457 </tbody>
1458 </entrytbl>
1459 </row>
1460 <row><entry></entry></row>
1461 <row>
1462 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant>&nbsp;</entry>
1463 <entry>integer&nbsp;(0-15)</entry>
1464 </row><row><entry spanname="descr">The setting for the
1465Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry>
1466 </row>
1467 <row><entry></entry></row>
1468 <row id="luma-spatial-filter-type">
1469 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
1470 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry>
1471 </row><row><entry spanname="descr">Select the algorithm
1472to use for the Luma Spatial Filter (default
1473<constant>1D_HOR</constant>). Possible values:</entry>
1474 </row>
1475 <row>
1476 <entrytbl spanname="descr" cols="2">
1477 <tbody valign="top">
1478 <row>
1479 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
1480 <entry>No filter</entry>
1481 </row>
1482 <row>
1483 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
1484 <entry>One-dimensional horizontal</entry>
1485 </row>
1486 <row>
1487 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant>&nbsp;</entry>
1488 <entry>One-dimensional vertical</entry>
1489 </row>
1490 <row>
1491 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant>&nbsp;</entry>
1492 <entry>Two-dimensional separable</entry>
1493 </row>
1494 <row>
1495 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant>&nbsp;</entry>
1496 <entry>Two-dimensional symmetrical
1497non-separable</entry>
1498 </row>
1499 </tbody>
1500 </entrytbl>
1501 </row>
1502 <row><entry></entry></row>
1503 <row id="chroma-spatial-filter-type">
1504 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
1505 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry>
1506 </row><row><entry spanname="descr">Select the algorithm
1507for the Chroma Spatial Filter (default <constant>1D_HOR</constant>).
1508Possible values are:</entry>
1509 </row>
1510 <row>
1511 <entrytbl spanname="descr" cols="2">
1512 <tbody valign="top">
1513 <row>
1514 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
1515 <entry>No filter</entry>
1516 </row>
1517 <row>
1518 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
1519 <entry>One-dimensional horizontal</entry>
1520 </row>
1521 </tbody>
1522 </entrytbl>
1523 </row>
1524 <row><entry></entry></row>
1525 <row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode">
1526 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant>&nbsp;</entry>
1527 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry>
1528 </row><row><entry spanname="descr">Sets the Temporal
1529Filter mode (default <constant>MANUAL</constant>). Possible values
1530are:</entry>
1531 </row>
1532 <row>
1533 <entrytbl spanname="descr" cols="2">
1534 <tbody valign="top">
1535 <row>
1536 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
1537 <entry>Choose the filter manually</entry>
1538 </row>
1539 <row>
1540 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
1541 <entry>Choose the filter automatically</entry>
1542 </row>
1543 </tbody>
1544 </entrytbl>
1545 </row>
1546 <row><entry></entry></row>
1547 <row>
1548 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant>&nbsp;</entry>
1549 <entry>integer&nbsp;(0-31)</entry>
1550 </row><row><entry spanname="descr">The setting for the
1551Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale
1552capturing and 0 for scaled capturing.)</entry>
1553 </row>
1554 <row><entry></entry></row>
1555 <row id="v4l2-mpeg-cx2341x-video-median-filter-type">
1556 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant>&nbsp;</entry>
1557 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_median_filter_type</entry>
1558 </row><row><entry spanname="descr">Median Filter Type
1559(default <constant>OFF</constant>). Possible values are:</entry>
1560 </row>
1561 <row>
1562 <entrytbl spanname="descr" cols="2">
1563 <tbody valign="top">
1564 <row>
1565 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant>&nbsp;</entry>
1566 <entry>No filter</entry>
1567 </row>
1568 <row>
1569 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant>&nbsp;</entry>
1570 <entry>Horizontal filter</entry>
1571 </row>
1572 <row>
1573 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant>&nbsp;</entry>
1574 <entry>Vertical filter</entry>
1575 </row>
1576 <row>
1577 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant>&nbsp;</entry>
1578 <entry>Horizontal and vertical filter</entry>
1579 </row>
1580 <row>
1581 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant>&nbsp;</entry>
1582 <entry>Diagonal filter</entry>
1583 </row>
1584 </tbody>
1585 </entrytbl>
1586 </row>
1587 <row><entry></entry></row>
1588 <row>
1589 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
1590 <entry>integer&nbsp;(0-255)</entry>
1591 </row><row><entry spanname="descr">Threshold above which
1592the luminance median filter is enabled (default 0)</entry>
1593 </row>
1594 <row><entry></entry></row>
1595 <row>
1596 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
1597 <entry>integer&nbsp;(0-255)</entry>
1598 </row><row><entry spanname="descr">Threshold below which
1599the luminance median filter is enabled (default 255)</entry>
1600 </row>
1601 <row><entry></entry></row>
1602 <row>
1603 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
1604 <entry>integer&nbsp;(0-255)</entry>
1605 </row><row><entry spanname="descr">Threshold above which
1606the chroma median filter is enabled (default 0)</entry>
1607 </row>
1608 <row><entry></entry></row>
1609 <row>
1610 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
1611 <entry>integer&nbsp;(0-255)</entry>
1612 </row><row><entry spanname="descr">Threshold below which
1613the chroma median filter is enabled (default 255)</entry>
1614 </row>
1615 <row><entry></entry></row>
1616 <row>
1617 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant>&nbsp;</entry>
1618 <entry>boolean</entry>
1619 </row>
1620 <row><entry spanname="descr">The CX2341X MPEG encoder
1621can insert one empty MPEG-2 PES packet into the stream between every
1622four video frames. The packet size is 2048 bytes, including the
1623packet_start_code_prefix and stream_id fields. The stream_id is 0xBF
1624(private stream 2). The payload consists of 0x00 bytes, to be filled
1625in by the application. 0 = do not insert, 1 = insert packets.</entry>
1626 </row>
1627 </tbody>
1628 </tgroup>
1629 </table>
1630 </section>
1631 </section>
1632
1633 <section id="camera-controls">
1634 <title>Camera Control Reference</title>
1635
1636 <para>The Camera class includes controls for mechanical (or
1637equivalent digital) features of a device such as controllable lenses
1638or sensors.</para>
1639
1640 <table pgwide="1" frame="none" id="camera-control-id">
1641 <title>Camera Control IDs</title>
1642 <tgroup cols="4">
1643 <colspec colname="c1" colwidth="1*" />
1644 <colspec colname="c2" colwidth="6*" />
1645 <colspec colname="c3" colwidth="2*" />
1646 <colspec colname="c4" colwidth="6*" />
1647 <spanspec namest="c1" nameend="c2" spanname="id" />
1648 <spanspec namest="c2" nameend="c4" spanname="descr" />
1649 <thead>
1650 <row>
1651 <entry spanname="id" align="left">ID</entry>
1652 <entry align="left">Type</entry>
1653 </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
1654 </row>
1655 </thead>
1656 <tbody valign="top">
1657 <row><entry></entry></row>
1658 <row>
1659 <entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant>&nbsp;</entry>
1660 <entry>class</entry>
1661 </row><row><entry spanname="descr">The Camera class
1662descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
1663description of this control class.</entry>
1664 </row>
1665 <row><entry></entry></row>
1666
1667 <row id="v4l2-exposure-auto-type">
1668 <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant>&nbsp;</entry>
1669 <entry>enum&nbsp;v4l2_exposure_auto_type</entry>
1670 </row><row><entry spanname="descr">Enables automatic
1671adjustments of the exposure time and/or iris aperture. The effect of
1672manual changes of the exposure time or iris aperture while these
1673features are enabled is undefined, drivers should ignore such
1674requests. Possible values are:</entry>
1675 </row>
1676 <row>
1677 <entrytbl spanname="descr" cols="2">
1678 <tbody valign="top">
1679 <row>
1680 <entry><constant>V4L2_EXPOSURE_AUTO</constant>&nbsp;</entry>
1681 <entry>Automatic exposure time, automatic iris
1682aperture.</entry>
1683 </row>
1684 <row>
1685 <entry><constant>V4L2_EXPOSURE_MANUAL</constant>&nbsp;</entry>
1686 <entry>Manual exposure time, manual iris.</entry>
1687 </row>
1688 <row>
1689 <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant>&nbsp;</entry>
1690 <entry>Manual exposure time, auto iris.</entry>
1691 </row>
1692 <row>
1693 <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant>&nbsp;</entry>
1694 <entry>Auto exposure time, manual iris.</entry>
1695 </row>
1696 </tbody>
1697 </entrytbl>
1698 </row>
1699 <row><entry></entry></row>
1700
1701 <row>
1702 <entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>&nbsp;</entry>
1703 <entry>integer</entry>
1704 </row><row><entry spanname="descr">Determines the exposure
1705time of the camera sensor. The exposure time is limited by the frame
1706interval. Drivers should interpret the values as 100 &micro;s units,
1707where the value 1 stands for 1/10000th of a second, 10000 for 1 second
1708and 100000 for 10 seconds.</entry>
1709 </row>
1710 <row><entry></entry></row>
1711
1712 <row>
1713 <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>&nbsp;</entry>
1714 <entry>boolean</entry>
1715 </row><row><entry spanname="descr">When
1716<constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to
1717<constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>,
1718this control determines if the device may dynamically vary the frame
1719rate. By default this feature is disabled (0) and the frame rate must
1720remain constant.</entry>
1721 </row>
1722 <row><entry></entry></row>
1723
1724 <row>
1725 <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant>&nbsp;</entry>
1726 <entry>integer</entry>
1727 </row><row><entry spanname="descr">This control turns the
1728camera horizontally by the specified amount. The unit is undefined. A
1729positive value moves the camera to the right (clockwise when viewed
1730from above), a negative value to the left. A value of zero does not
1731cause motion. This is a write-only control.</entry>
1732 </row>
1733 <row><entry></entry></row>
1734
1735 <row>
1736 <entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant>&nbsp;</entry>
1737 <entry>integer</entry>
1738 </row><row><entry spanname="descr">This control turns the
1739camera vertically by the specified amount. The unit is undefined. A
1740positive value moves the camera up, a negative value down. A value of
1741zero does not cause motion. This is a write-only control.</entry>
1742 </row>
1743 <row><entry></entry></row>
1744
1745 <row>
1746 <entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant>&nbsp;</entry>
1747 <entry>button</entry>
1748 </row><row><entry spanname="descr">When this control is set,
1749the camera moves horizontally to the default position.</entry>
1750 </row>
1751 <row><entry></entry></row>
1752
1753 <row>
1754 <entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant>&nbsp;</entry>
1755 <entry>button</entry>
1756 </row><row><entry spanname="descr">When this control is set,
1757the camera moves vertically to the default position.</entry>
1758 </row>
1759 <row><entry></entry></row>
1760
1761 <row>
1762 <entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant>&nbsp;</entry>
1763 <entry>integer</entry>
1764 </row><row><entry spanname="descr">This control
1765turns the camera horizontally to the specified position. Positive
1766values move the camera to the right (clockwise when viewed from above),
1767negative values to the left. Drivers should interpret the values as arc
1768seconds, with valid values between -180 * 3600 and +180 * 3600
1769inclusive.</entry>
1770 </row>
1771 <row><entry></entry></row>
1772
1773 <row>
1774 <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant>&nbsp;</entry>
1775 <entry>integer</entry>
1776 </row><row><entry spanname="descr">This control
1777turns the camera vertically to the specified position. Positive values
1778move the camera up, negative values down. Drivers should interpret the
1779values as arc seconds, with valid values between -180 * 3600 and +180
1780* 3600 inclusive.</entry>
1781 </row>
1782 <row><entry></entry></row>
1783
1784 <row>
1785 <entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant>&nbsp;</entry>
1786 <entry>integer</entry>
1787 </row><row><entry spanname="descr">This control sets the
1788focal point of the camera to the specified position. The unit is
1789undefined. Positive values set the focus closer to the camera,
1790negative values towards infinity.</entry>
1791 </row>
1792 <row><entry></entry></row>
1793
1794 <row>
1795 <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant>&nbsp;</entry>
1796 <entry>integer</entry>
1797 </row><row><entry spanname="descr">This control moves the
1798focal point of the camera by the specified amount. The unit is
1799undefined. Positive values move the focus closer to the camera,
1800negative values towards infinity. This is a write-only control.</entry>
1801 </row>
1802 <row><entry></entry></row>
1803
1804 <row>
1805 <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant>&nbsp;</entry>
1806 <entry>boolean</entry>
1807 </row><row><entry spanname="descr">Enables automatic focus
1808adjustments. The effect of manual focus adjustments while this feature
1809is enabled is undefined, drivers should ignore such requests.</entry>
1810 </row>
1811 <row><entry></entry></row>
1812
1813 <row>
1814 <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant>&nbsp;</entry>
1815 <entry>integer</entry>
1816 </row><row><entry spanname="descr">Specify the objective lens
1817focal length as an absolute value. The zoom unit is driver-specific and its
1818value should be a positive integer.</entry>
1819 </row>
1820 <row><entry></entry></row>
1821
1822 <row>
1823 <entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant>&nbsp;</entry>
1824 <entry>integer</entry>
1825 </row><row><entry spanname="descr">Specify the objective lens
1826focal length relatively to the current value. Positive values move the zoom
1827lens group towards the telephoto direction, negative values towards the
1828wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry>
1829 </row>
1830 <row><entry></entry></row>
1831
1832 <row>
1833 <entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant>&nbsp;</entry>
1834 <entry>integer</entry>
1835 </row><row><entry spanname="descr">Move the objective lens group
1836at the specified speed until it reaches physical device limits or until an
1837explicit request to stop the movement. A positive value moves the zoom lens
1838group towards the telephoto direction. A value of zero stops the zoom lens
1839group movement. A negative value moves the zoom lens group towards the
1840wide-angle direction. The zoom speed unit is driver-specific.</entry>
1841 </row>
1842 <row><entry></entry></row>
1843
1844 <row>
1845 <entry spanname="id"><constant>V4L2_CID_IRIS_ABSOLUTE</constant>&nbsp;</entry>
1846 <entry>integer</entry>
1847 </row><row><entry spanname="descr">This control sets the
1848camera's aperture to the specified value. The unit is undefined.
1849Larger values open the iris wider, smaller values close it.</entry>
1850 </row>
1851 <row><entry></entry></row>
1852
1853 <row>
1854 <entry spanname="id"><constant>V4L2_CID_IRIS_RELATIVE</constant>&nbsp;</entry>
1855 <entry>integer</entry>
1856 </row><row><entry spanname="descr">This control modifies the
1857camera's aperture by the specified amount. The unit is undefined.
1858Positive values open the iris one step further, negative values close
1859it one step further. This is a write-only control.</entry>
1860 </row>
1861 <row><entry></entry></row>
1862
1863 <row>
1864 <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant>&nbsp;</entry>
1865 <entry>boolean</entry>
1866 </row><row><entry spanname="descr">Prevent video from being acquired
1867by the camera. When this control is set to <constant>TRUE</constant> (1), no
1868image can be captured by the camera. Common means to enforce privacy are
1869mechanical obturation of the sensor and firmware image processing, but the
1870device is not restricted to these methods. Devices that implement the privacy
1871control must support read access and may support write access.</entry>
1872 </row>
1873
1874 <row>
1875 <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant>&nbsp;</entry>
1876 <entry>integer</entry>
1877 </row><row><entry spanname="descr">Switch the band-stop filter of a
1878camera sensor on or off, or specify its strength. Such band-stop filters can
1879be used, for example, to filter out the fluorescent light component.</entry>
1880 </row>
1881 <row><entry></entry></row>
1882 </tbody>
1883 </tgroup>
1884 </table>
1885 </section>
1886
1887 <section id="fm-tx-controls">
1888 <title>FM Transmitter Control Reference</title>
1889
1890 <para>The FM Transmitter (FM_TX) class includes controls for common features of
1891FM transmissions capable devices. Currently this class includes parameters for audio
1892compression, pilot tone generation, audio deviation limiter, RDS transmission and
1893tuning power features.</para>
1894
1895 <table pgwide="1" frame="none" id="fm-tx-control-id">
1896 <title>FM_TX Control IDs</title>
1897
1898 <tgroup cols="4">
1899 <colspec colname="c1" colwidth="1*" />
1900 <colspec colname="c2" colwidth="6*" />
1901 <colspec colname="c3" colwidth="2*" />
1902 <colspec colname="c4" colwidth="6*" />
1903 <spanspec namest="c1" nameend="c2" spanname="id" />
1904 <spanspec namest="c2" nameend="c4" spanname="descr" />
1905 <thead>
1906 <row>
1907 <entry spanname="id" align="left">ID</entry>
1908 <entry align="left">Type</entry>
1909 </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
1910 </row>
1911 </thead>
1912 <tbody valign="top">
1913 <row><entry></entry></row>
1914 <row>
1915 <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant>&nbsp;</entry>
1916 <entry>class</entry>
1917 </row><row><entry spanname="descr">The FM_TX class
1918descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
1919description of this control class.</entry>
1920 </row>
1921 <row>
1922 <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant>&nbsp;</entry>
1923 <entry>integer</entry>
1924 </row>
1925 <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz.
1926The range and step are driver-specific.</entry>
1927 </row>
1928 <row>
1929 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant>&nbsp;</entry>
1930 <entry>integer</entry>
1931 </row>
1932 <row><entry spanname="descr">Sets the RDS Programme Identification field
1933for transmission.</entry>
1934 </row>
1935 <row>
1936 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant>&nbsp;</entry>
1937 <entry>integer</entry>
1938 </row>
1939 <row><entry spanname="descr">Sets the RDS Programme Type field for transmission.
1940This encodes up to 31 pre-defined programme types.</entry>
1941 </row>
1942 <row>
1943 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant>&nbsp;</entry>
1944 <entry>string</entry>
1945 </row>
1946 <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission.
1947It is intended for static display on a receiver. It is the primary aid to listeners in programme service
1948identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification,
1949there is a full description of the correct character encoding for Programme Service name strings.
1950Also from RDS specification, PS is usually a single eight character text. However, it is also possible
1951to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
1952with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
1953 </row>
1954 <row>
1955 <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant>&nbsp;</entry>
1956 <entry>string</entry>
1957 </row>
1958 <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of
1959what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
1960programme-related information or any other text. In these cases, RadioText should be used in addition to
1961<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
1962in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being
1963used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
1964to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
1965with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
1966 </row>
1967 <row>
1968 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant>&nbsp;</entry>
1969 <entry>boolean</entry>
1970 </row>
1971 <row><entry spanname="descr">Enables or disables the audio deviation limiter feature.
1972The limiter is useful when trying to maximize the audio volume, minimize receiver-generated
1973distortion and prevent overmodulation.
1974</entry>
1975 </row>
1976 <row>
1977 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant>&nbsp;</entry>
1978 <entry>integer</entry>
1979 </row>
1980 <row><entry spanname="descr">Sets the audio deviation limiter feature release time.
1981Unit is in useconds. Step and range are driver-specific.</entry>
1982 </row>
1983 <row>
1984 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant>&nbsp;</entry>
1985 <entry>integer</entry>
1986 </row>
1987 <row><entry spanname="descr">Configures audio frequency deviation level in Hz.
1988The range and step are driver-specific.</entry>
1989 </row>
1990 <row>
1991 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant>&nbsp;</entry>
1992 <entry>boolean</entry>
1993 </row>
1994 <row><entry spanname="descr">Enables or disables the audio compression feature.
1995This feature amplifies signals below the threshold by a fixed gain and compresses audio
1996signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry>
1997 </row>
1998 <row>
1999 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant>&nbsp;</entry>
2000 <entry>integer</entry>
2001 </row>
2002 <row><entry spanname="descr">Sets the gain for audio compression feature. It is
2003a dB value. The range and step are driver-specific.</entry>
2004 </row>
2005 <row>
2006 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant>&nbsp;</entry>
2007 <entry>integer</entry>
2008 </row>
2009 <row><entry spanname="descr">Sets the threshold level for audio compression freature.
2010It is a dB value. The range and step are driver-specific.</entry>
2011 </row>
2012 <row>
2013 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant>&nbsp;</entry>
2014 <entry>integer</entry>
2015 </row>
2016 <row><entry spanname="descr">Sets the attack time for audio compression feature.
2017It is a useconds value. The range and step are driver-specific.</entry>
2018 </row>
2019 <row>
2020 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant>&nbsp;</entry>
2021 <entry>integer</entry>
2022 </row>
2023 <row><entry spanname="descr">Sets the release time for audio compression feature.
2024It is a useconds value. The range and step are driver-specific.</entry>
2025 </row>
2026 <row>
2027 <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant>&nbsp;</entry>
2028 <entry>boolean</entry>
2029 </row>
2030 <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry>
2031 </row>
2032 <row>
2033 <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant>&nbsp;</entry>
2034 <entry>integer</entry>
2035 </row>
2036 <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is
2037in Hz. The range and step are driver-specific.</entry>
2038 </row>
2039 <row>
2040 <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant>&nbsp;</entry>
2041 <entry>integer</entry>
2042 </row>
2043 <row><entry spanname="descr">Configures pilot tone frequency value. Unit is
2044in Hz. The range and step are driver-specific.</entry>
2045 </row>
2046 <row>
2047 <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant>&nbsp;</entry>
2048 <entry>integer</entry>
2049 </row>
2050 <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting.
2051A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.
2052Depending on the region, a time constant of either 50 or 75 useconds is used. The enum&nbsp;v4l2_preemphasis
2053defines possible values for pre-emphasis. Here they are:</entry>
2054 </row><row>
2055 <entrytbl spanname="descr" cols="2">
2056 <tbody valign="top">
2057 <row>
2058 <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant>&nbsp;</entry>
2059 <entry>No pre-emphasis is applied.</entry>
2060 </row>
2061 <row>
2062 <entry><constant>V4L2_PREEMPHASIS_50_uS</constant>&nbsp;</entry>
2063 <entry>A pre-emphasis of 50 uS is used.</entry>
2064 </row>
2065 <row>
2066 <entry><constant>V4L2_PREEMPHASIS_75_uS</constant>&nbsp;</entry>
2067 <entry>A pre-emphasis of 75 uS is used.</entry>
2068 </row>
2069 </tbody>
2070 </entrytbl>
2071
2072 </row>
2073 <row>
2074 <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant>&nbsp;</entry>
2075 <entry>integer</entry>
2076 </row>
2077 <row><entry spanname="descr">Sets the output power level for signal transmission.
2078Unit is in dBuV. Range and step are driver-specific.</entry>
2079 </row>
2080 <row>
2081 <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant>&nbsp;</entry>
2082 <entry>integer</entry>
2083 </row>
2084 <row><entry spanname="descr">This selects the value of antenna tuning capacitor
2085manually or automatically if set to zero. Unit, range and step are driver-specific.</entry>
2086 </row>
2087 <row><entry></entry></row>
2088 </tbody>
2089 </tgroup>
2090 </table>
2091
2092<para>For more details about RDS specification, refer to
2093<xref linkend="en50067" /> document, from CENELEC.</para>
2094 </section>
2095</section>
2096
2097 <!--
2098Local Variables:
2099mode: sgml
2100sgml-parent-document: "common.sgml"
2101indent-tabs-mode: nil
2102End:
2103 -->
diff --git a/Documentation/DocBook/media/v4l/crop.gif b/Documentation/DocBook/media/v4l/crop.gif
new file mode 100644
index 000000000000..3b9e7d836d4b
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/crop.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/crop.pdf b/Documentation/DocBook/media/v4l/crop.pdf
new file mode 100644
index 000000000000..c9fb81cd32f3
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/crop.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/dev-capture.xml b/Documentation/DocBook/media/v4l/dev-capture.xml
new file mode 100644
index 000000000000..2237c661f26a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-capture.xml
@@ -0,0 +1,118 @@
1 <title>Video Capture Interface</title>
2
3 <para>Video capture devices sample an analog video signal and store
4the digitized images in memory. Today nearly all devices can capture
5at full 25 or 30 frames/second. With this interface applications can
6control the capture process and move images from the driver into user
7space.</para>
8
9 <para>Conventionally V4L2 video capture devices are accessed through
10character device special files named <filename>/dev/video</filename>
11and <filename>/dev/video0</filename> to
12<filename>/dev/video63</filename> with major number 81 and minor
13numbers 0 to 63. <filename>/dev/video</filename> is typically a
14symbolic link to the preferred video device. Note the same device
15files are used for video output devices.</para>
16
17 <section>
18 <title>Querying Capabilities</title>
19
20 <para>Devices supporting the video capture interface set the
21<constant>V4L2_CAP_VIDEO_CAPTURE</constant> or
22<constant>V4L2_CAP_VIDEO_CAPTURE_MPLANE</constant> flag in the
23<structfield>capabilities</structfield> field of &v4l2-capability;
24returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
25they may also support the <link linkend="overlay">video overlay</link>
26(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
27linkend="raw-vbi">raw VBI capture</link>
28(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
29the read/write or streaming I/O methods must be supported. Tuners and
30audio inputs are optional.</para>
31 </section>
32
33 <section>
34 <title>Supplemental Functions</title>
35
36 <para>Video capture devices shall support <link
37linkend="audio">audio input</link>, <link
38linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
39<link linkend="crop">cropping and scaling</link> and <link
40linkend="streaming-par">streaming parameter</link> ioctls as needed.
41The <link linkend="video">video input</link> and <link
42linkend="standard">video standard</link> ioctls must be supported by
43all video capture devices.</para>
44 </section>
45
46 <section>
47 <title>Image Format Negotiation</title>
48
49 <para>The result of a capture operation is determined by
50cropping and image format parameters. The former select an area of the
51video picture to capture, the latter how images are stored in memory,
52&ie; in RGB or YUV format, the number of bits per pixel or width and
53height. Together they also define how images are scaled in the
54process.</para>
55
56 <para>As usual these parameters are <emphasis>not</emphasis> reset
57at &func-open; time to permit Unix tool chains, programming a device
58and then reading from it as if it was a plain file. Well written V4L2
59applications ensure they really get what they want, including cropping
60and scaling.</para>
61
62 <para>Cropping initialization at minimum requires to reset the
63parameters to defaults. An example is given in <xref
64linkend="crop" />.</para>
65
66 <para>To query the current image format applications set the
67<structfield>type</structfield> field of a &v4l2-format; to
68<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
69<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant> and call the
70&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
71the &v4l2-pix-format; <structfield>pix</structfield> or the
72&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
73<structfield>fmt</structfield> union.</para>
74
75 <para>To request different parameters applications set the
76<structfield>type</structfield> field of a &v4l2-format; as above and
77initialize all fields of the &v4l2-pix-format;
78<structfield>vbi</structfield> member of the
79<structfield>fmt</structfield> union, or better just modify the
80results of <constant>VIDIOC_G_FMT</constant>, and call the
81&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
82adjust the parameters and finally return the actual parameters as
83<constant>VIDIOC_G_FMT</constant> does.</para>
84
85 <para>Like <constant>VIDIOC_S_FMT</constant> the
86&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
87without disabling I/O or possibly time consuming hardware
88preparations.</para>
89
90 <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
91are discussed in <xref linkend="pixfmt" />. See also the specification of the
92<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
93and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
94capture devices must implement both the
95<constant>VIDIOC_G_FMT</constant> and
96<constant>VIDIOC_S_FMT</constant> ioctl, even if
97<constant>VIDIOC_S_FMT</constant> ignores all requests and always
98returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
99<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
100 </section>
101
102 <section>
103 <title>Reading Images</title>
104
105 <para>A video capture device may support the <link
106linkend="rw">read() function</link> and/or streaming (<link
107linkend="mmap">memory mapping</link> or <link
108linkend="userp">user pointer</link>) I/O. See <xref
109linkend="io" /> for details.</para>
110 </section>
111
112 <!--
113Local Variables:
114mode: sgml
115sgml-parent-document: "v4l2.sgml"
116indent-tabs-mode: nil
117End:
118 -->
diff --git a/Documentation/DocBook/media/v4l/dev-codec.xml b/Documentation/DocBook/media/v4l/dev-codec.xml
new file mode 100644
index 000000000000..6e156dc45b94
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-codec.xml
@@ -0,0 +1,26 @@
1 <title>Codec Interface</title>
2
3 <note>
4 <title>Suspended</title>
5
6 <para>This interface has been be suspended from the V4L2 API
7implemented in Linux 2.6 until we have more experience with codec
8device interfaces.</para>
9 </note>
10
11 <para>A V4L2 codec can compress, decompress, transform, or otherwise
12convert video data from one format into another format, in memory.
13Applications send data to be converted to the driver through a
14&func-write; call, and receive the converted data through a
15&func-read; call. For efficiency a driver may also support streaming
16I/O.</para>
17
18 <para>[to do]</para>
19
20 <!--
21Local Variables:
22mode: sgml
23sgml-parent-document: "v4l2.sgml"
24indent-tabs-mode: nil
25End:
26 -->
diff --git a/Documentation/DocBook/media/v4l/dev-effect.xml b/Documentation/DocBook/media/v4l/dev-effect.xml
new file mode 100644
index 000000000000..9c243beba0e6
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-effect.xml
@@ -0,0 +1,25 @@
1 <title>Effect Devices Interface</title>
2
3 <note>
4 <title>Suspended</title>
5
6 <para>This interface has been be suspended from the V4L2 API
7implemented in Linux 2.6 until we have more experience with effect
8device interfaces.</para>
9 </note>
10
11 <para>A V4L2 video effect device can do image effects, filtering, or
12combine two or more images or image streams. For example video
13transitions or wipes. Applications send data to be processed and
14receive the result data either with &func-read; and &func-write;
15functions, or through the streaming I/O mechanism.</para>
16
17 <para>[to do]</para>
18
19 <!--
20Local Variables:
21mode: sgml
22sgml-parent-document: "v4l2.sgml"
23indent-tabs-mode: nil
24End:
25 -->
diff --git a/Documentation/DocBook/media/v4l/dev-event.xml b/Documentation/DocBook/media/v4l/dev-event.xml
new file mode 100644
index 000000000000..be5a98fb4fab
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-event.xml
@@ -0,0 +1,31 @@
1 <title>Event Interface</title>
2
3 <para>The V4L2 event interface provides means for user to get
4 immediately notified on certain conditions taking place on a device.
5 This might include start of frame or loss of signal events, for
6 example.
7 </para>
8
9 <para>To receive events, the events the user is interested in first must
10 be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an event is
11 subscribed, the events of subscribed types are dequeueable using the
12 &VIDIOC-DQEVENT; ioctl. Events may be unsubscribed using
13 VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event type V4L2_EVENT_ALL may
14 be used to unsubscribe all the events the driver supports.</para>
15
16 <para>The event subscriptions and event queues are specific to file
17 handles. Subscribing an event on one file handle does not affect
18 other file handles.
19 </para>
20
21 <para>The information on dequeueable events is obtained by using select or
22 poll system calls on video devices. The V4L2 events use POLLPRI events on
23 poll system call and exceptions on select system call. </para>
24
25 <!--
26Local Variables:
27mode: sgml
28sgml-parent-document: "v4l2.sgml"
29indent-tabs-mode: nil
30End:
31 -->
diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml
new file mode 100644
index 000000000000..c9a68a2ccd33
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-osd.xml
@@ -0,0 +1,164 @@
1 <title>Video Output Overlay Interface</title>
2 <subtitle>Also known as On-Screen Display (OSD)</subtitle>
3
4 <note>
5 <title>Experimental</title>
6
7 <para>This is an <link linkend="experimental">experimental</link>
8interface and may change in the future.</para>
9 </note>
10
11 <para>Some video output devices can overlay a framebuffer image onto
12the outgoing video signal. Applications can set up such an overlay
13using this interface, which borrows structures and ioctls of the <link
14linkend="overlay">Video Overlay</link> interface.</para>
15
16 <para>The OSD function is accessible through the same character
17special file as the <link linkend="capture">Video Output</link> function.
18Note the default function of such a <filename>/dev/video</filename> device
19is video capturing or output. The OSD function is only available after
20calling the &VIDIOC-S-FMT; ioctl.</para>
21
22 <section>
23 <title>Querying Capabilities</title>
24
25 <para>Devices supporting the <wordasword>Video Output
26Overlay</wordasword> interface set the
27<constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant> flag in the
28<structfield>capabilities</structfield> field of &v4l2-capability;
29returned by the &VIDIOC-QUERYCAP; ioctl.</para>
30 </section>
31
32 <section>
33 <title>Framebuffer</title>
34
35 <para>Contrary to the <wordasword>Video Overlay</wordasword>
36interface the framebuffer is normally implemented on the TV card and
37not the graphics card. On Linux it is accessible as a framebuffer
38device (<filename>/dev/fbN</filename>). Given a V4L2 device,
39applications can find the corresponding framebuffer device by calling
40the &VIDIOC-G-FBUF; ioctl. It returns, amongst other information, the
41physical address of the framebuffer in the
42<structfield>base</structfield> field of &v4l2-framebuffer;. The
43framebuffer device ioctl <constant>FBIOGET_FSCREENINFO</constant>
44returns the same address in the <structfield>smem_start</structfield>
45field of struct <structname>fb_fix_screeninfo</structname>. The
46<constant>FBIOGET_FSCREENINFO</constant> ioctl and struct
47<structname>fb_fix_screeninfo</structname> are defined in the
48<filename>linux/fb.h</filename> header file.</para>
49
50 <para>The width and height of the framebuffer depends on the
51current video standard. A V4L2 driver may reject attempts to change
52the video standard (or any other ioctl which would imply a framebuffer
53size change) with an &EBUSY; until all applications closed the
54framebuffer device.</para>
55
56 <example>
57 <title>Finding a framebuffer device for OSD</title>
58
59 <programlisting>
60#include &lt;linux/fb.h&gt;
61
62&v4l2-framebuffer; fbuf;
63unsigned int i;
64int fb_fd;
65
66if (-1 == ioctl (fd, VIDIOC_G_FBUF, &amp;fbuf)) {
67 perror ("VIDIOC_G_FBUF");
68 exit (EXIT_FAILURE);
69}
70
71for (i = 0; i &gt; 30; ++i) {
72 char dev_name[16];
73 struct fb_fix_screeninfo si;
74
75 snprintf (dev_name, sizeof (dev_name), "/dev/fb%u", i);
76
77 fb_fd = open (dev_name, O_RDWR);
78 if (-1 == fb_fd) {
79 switch (errno) {
80 case ENOENT: /* no such file */
81 case ENXIO: /* no driver */
82 continue;
83
84 default:
85 perror ("open");
86 exit (EXIT_FAILURE);
87 }
88 }
89
90 if (0 == ioctl (fb_fd, FBIOGET_FSCREENINFO, &amp;si)) {
91 if (si.smem_start == (unsigned long) fbuf.base)
92 break;
93 } else {
94 /* Apparently not a framebuffer device. */
95 }
96
97 close (fb_fd);
98 fb_fd = -1;
99}
100
101/* fb_fd is the file descriptor of the framebuffer device
102 for the video output overlay, or -1 if no device was found. */
103</programlisting>
104 </example>
105 </section>
106
107 <section>
108 <title>Overlay Window and Scaling</title>
109
110 <para>The overlay is controlled by source and target rectangles.
111The source rectangle selects a subsection of the framebuffer image to
112be overlaid, the target rectangle an area in the outgoing video signal
113where the image will appear. Drivers may or may not support scaling,
114and arbitrary sizes and positions of these rectangles. Further drivers
115may support any (or none) of the clipping/blending methods defined for
116the <link linkend="overlay">Video Overlay</link> interface.</para>
117
118 <para>A &v4l2-window; defines the size of the source rectangle,
119its position in the framebuffer and the clipping/blending method to be
120used for the overlay. To get the current parameters applications set
121the <structfield>type</structfield> field of a &v4l2-format; to
122<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant> and call the
123&VIDIOC-G-FMT; ioctl. The driver fills the
124<structname>v4l2_window</structname> substructure named
125<structfield>win</structfield>. It is not possible to retrieve a
126previously programmed clipping list or bitmap.</para>
127
128 <para>To program the source rectangle applications set the
129<structfield>type</structfield> field of a &v4l2-format; to
130<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, initialize
131the <structfield>win</structfield> substructure and call the
132&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
133hardware limits and returns the actual parameters as
134<constant>VIDIOC_G_FMT</constant> does. Like
135<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
136used to learn about driver capabilities without actually changing
137driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
138after the overlay has been enabled.</para>
139
140 <para>A &v4l2-crop; defines the size and position of the target
141rectangle. The scaling factor of the overlay is implied by the width
142and height given in &v4l2-window; and &v4l2-crop;. The cropping API
143applies to <wordasword>Video Output</wordasword> and <wordasword>Video
144Output Overlay</wordasword> devices in the same way as to
145<wordasword>Video Capture</wordasword> and <wordasword>Video
146Overlay</wordasword> devices, merely reversing the direction of the
147data flow. For more information see <xref linkend="crop" />.</para>
148 </section>
149
150 <section>
151 <title>Enabling Overlay</title>
152
153 <para>There is no V4L2 ioctl to enable or disable the overlay,
154however the framebuffer interface of the driver may support the
155<constant>FBIOBLANK</constant> ioctl.</para>
156 </section>
157
158 <!--
159Local Variables:
160mode: sgml
161sgml-parent-document: "v4l2.sgml"
162indent-tabs-mode: nil
163End:
164 -->
diff --git a/Documentation/DocBook/media/v4l/dev-output.xml b/Documentation/DocBook/media/v4l/dev-output.xml
new file mode 100644
index 000000000000..919e22c53854
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-output.xml
@@ -0,0 +1,114 @@
1 <title>Video Output Interface</title>
2
3 <para>Video output devices encode stills or image sequences as
4analog video signal. With this interface applications can
5control the encoding process and move images from user space to
6the driver.</para>
7
8 <para>Conventionally V4L2 video output devices are accessed through
9character device special files named <filename>/dev/video</filename>
10and <filename>/dev/video0</filename> to
11<filename>/dev/video63</filename> with major number 81 and minor
12numbers 0 to 63. <filename>/dev/video</filename> is typically a
13symbolic link to the preferred video device. Note the same device
14files are used for video capture devices.</para>
15
16 <section>
17 <title>Querying Capabilities</title>
18
19 <para>Devices supporting the video output interface set the
20<constant>V4L2_CAP_VIDEO_OUTPUT</constant> or
21<constant>V4L2_CAP_VIDEO_OUTPUT_MPLANE</constant> flag in the
22<structfield>capabilities</structfield> field of &v4l2-capability;
23returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
24they may also support the <link linkend="raw-vbi">raw VBI
25output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
26least one of the read/write or streaming I/O methods must be
27supported. Modulators and audio outputs are optional.</para>
28 </section>
29
30 <section>
31 <title>Supplemental Functions</title>
32
33 <para>Video output devices shall support <link
34linkend="audio">audio output</link>, <link
35linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
36<link linkend="crop">cropping and scaling</link> and <link
37linkend="streaming-par">streaming parameter</link> ioctls as needed.
38The <link linkend="video">video output</link> and <link
39linkend="standard">video standard</link> ioctls must be supported by
40all video output devices.</para>
41 </section>
42
43 <section>
44 <title>Image Format Negotiation</title>
45
46 <para>The output is determined by cropping and image format
47parameters. The former select an area of the video picture where the
48image will appear, the latter how images are stored in memory, &ie; in
49RGB or YUV format, the number of bits per pixel or width and height.
50Together they also define how images are scaled in the process.</para>
51
52 <para>As usual these parameters are <emphasis>not</emphasis> reset
53at &func-open; time to permit Unix tool chains, programming a device
54and then writing to it as if it was a plain file. Well written V4L2
55applications ensure they really get what they want, including cropping
56and scaling.</para>
57
58 <para>Cropping initialization at minimum requires to reset the
59parameters to defaults. An example is given in <xref
60linkend="crop" />.</para>
61
62 <para>To query the current image format applications set the
63<structfield>type</structfield> field of a &v4l2-format; to
64<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
65<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and call the
66&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
67the &v4l2-pix-format; <structfield>pix</structfield> or the
68&v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member of the
69<structfield>fmt</structfield> union.</para>
70
71 <para>To request different parameters applications set the
72<structfield>type</structfield> field of a &v4l2-format; as above and
73initialize all fields of the &v4l2-pix-format;
74<structfield>vbi</structfield> member of the
75<structfield>fmt</structfield> union, or better just modify the
76results of <constant>VIDIOC_G_FMT</constant>, and call the
77&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
78adjust the parameters and finally return the actual parameters as
79<constant>VIDIOC_G_FMT</constant> does.</para>
80
81 <para>Like <constant>VIDIOC_S_FMT</constant> the
82&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
83without disabling I/O or possibly time consuming hardware
84preparations.</para>
85
86 <para>The contents of &v4l2-pix-format; and &v4l2-pix-format-mplane;
87are discussed in <xref linkend="pixfmt" />. See also the specification of the
88<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
89and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
90output devices must implement both the
91<constant>VIDIOC_G_FMT</constant> and
92<constant>VIDIOC_S_FMT</constant> ioctl, even if
93<constant>VIDIOC_S_FMT</constant> ignores all requests and always
94returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
95<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
96 </section>
97
98 <section>
99 <title>Writing Images</title>
100
101 <para>A video output device may support the <link
102linkend="rw">write() function</link> and/or streaming (<link
103linkend="mmap">memory mapping</link> or <link
104linkend="userp">user pointer</link>) I/O. See <xref
105linkend="io" /> for details.</para>
106 </section>
107
108 <!--
109Local Variables:
110mode: sgml
111sgml-parent-document: "v4l2.sgml"
112indent-tabs-mode: nil
113End:
114 -->
diff --git a/Documentation/DocBook/media/v4l/dev-overlay.xml b/Documentation/DocBook/media/v4l/dev-overlay.xml
new file mode 100644
index 000000000000..92513cf79150
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-overlay.xml
@@ -0,0 +1,379 @@
1 <title>Video Overlay Interface</title>
2 <subtitle>Also known as Framebuffer Overlay or Previewing</subtitle>
3
4 <para>Video overlay devices have the ability to genlock (TV-)video
5into the (VGA-)video signal of a graphics card, or to store captured
6images directly in video memory of a graphics card, typically with
7clipping. This can be considerable more efficient than capturing
8images and displaying them by other means. In the old days when only
9nuclear power plants needed cooling towers this used to be the only
10way to put live video into a window.</para>
11
12 <para>Video overlay devices are accessed through the same character
13special files as <link linkend="capture">video capture</link> devices.
14Note the default function of a <filename>/dev/video</filename> device
15is video capturing. The overlay function is only available after
16calling the &VIDIOC-S-FMT; ioctl.</para>
17
18 <para>The driver may support simultaneous overlay and capturing
19using the read/write and streaming I/O methods. If so, operation at
20the nominal frame rate of the video standard is not guaranteed. Frames
21may be directed away from overlay to capture, or one field may be used
22for overlay and the other for capture if the capture parameters permit
23this.</para>
24
25 <para>Applications should use different file descriptors for
26capturing and overlay. This must be supported by all drivers capable
27of simultaneous capturing and overlay. Optionally these drivers may
28also permit capturing and overlay with a single file descriptor for
29compatibility with V4L and earlier versions of V4L2.<footnote>
30 <para>A common application of two file descriptors is the
31XFree86 <link linkend="xvideo">Xv/V4L</link> interface driver and
32a V4L2 application. While the X server controls video overlay, the
33application can take advantage of memory mapping and DMA.</para>
34 <para>In the opinion of the designers of this API, no driver
35writer taking the efforts to support simultaneous capturing and
36overlay will restrict this ability by requiring a single file
37descriptor, as in V4L and earlier versions of V4L2. Making this
38optional means applications depending on two file descriptors need
39backup routines to be compatible with all drivers, which is
40considerable more work than using two fds in applications which do
41not. Also two fd's fit the general concept of one file descriptor for
42each logical stream. Hence as a complexity trade-off drivers
43<emphasis>must</emphasis> support two file descriptors and
44<emphasis>may</emphasis> support single fd operation.</para>
45 </footnote></para>
46
47 <section>
48 <title>Querying Capabilities</title>
49
50 <para>Devices supporting the video overlay interface set the
51<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag in the
52<structfield>capabilities</structfield> field of &v4l2-capability;
53returned by the &VIDIOC-QUERYCAP; ioctl. The overlay I/O method specified
54below must be supported. Tuners and audio inputs are optional.</para>
55 </section>
56
57 <section>
58 <title>Supplemental Functions</title>
59
60 <para>Video overlay devices shall support <link
61linkend="audio">audio input</link>, <link
62linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
63<link linkend="crop">cropping and scaling</link> and <link
64linkend="streaming-par">streaming parameter</link> ioctls as needed.
65The <link linkend="video">video input</link> and <link
66linkend="standard">video standard</link> ioctls must be supported by
67all video overlay devices.</para>
68 </section>
69
70 <section>
71 <title>Setup</title>
72
73 <para>Before overlay can commence applications must program the
74driver with frame buffer parameters, namely the address and size of
75the frame buffer and the image format, for example RGB 5:6:5. The
76&VIDIOC-G-FBUF; and &VIDIOC-S-FBUF; ioctls are available to get
77and set these parameters, respectively. The
78<constant>VIDIOC_S_FBUF</constant> ioctl is privileged because it
79allows to set up DMA into physical memory, bypassing the memory
80protection mechanisms of the kernel. Only the superuser can change the
81frame buffer address and size. Users are not supposed to run TV
82applications as root or with SUID bit set. A small helper application
83with suitable privileges should query the graphics system and program
84the V4L2 driver at the appropriate time.</para>
85
86 <para>Some devices add the video overlay to the output signal
87of the graphics card. In this case the frame buffer is not modified by
88the video device, and the frame buffer address and pixel format are
89not needed by the driver. The <constant>VIDIOC_S_FBUF</constant> ioctl
90is not privileged. An application can check for this type of device by
91calling the <constant>VIDIOC_G_FBUF</constant> ioctl.</para>
92
93 <para>A driver may support any (or none) of five clipping/blending
94methods:<orderedlist>
95 <listitem>
96 <para>Chroma-keying displays the overlaid image only where
97pixels in the primary graphics surface assume a certain color.</para>
98 </listitem>
99 <listitem>
100 <para>A bitmap can be specified where each bit corresponds
101to a pixel in the overlaid image. When the bit is set, the
102corresponding video pixel is displayed, otherwise a pixel of the
103graphics surface.</para>
104 </listitem>
105 <listitem>
106 <para>A list of clipping rectangles can be specified. In
107these regions <emphasis>no</emphasis> video is displayed, so the
108graphics surface can be seen here.</para>
109 </listitem>
110 <listitem>
111 <para>The framebuffer has an alpha channel that can be used
112to clip or blend the framebuffer with the video.</para>
113 </listitem>
114 <listitem>
115 <para>A global alpha value can be specified to blend the
116framebuffer contents with video images.</para>
117 </listitem>
118 </orderedlist></para>
119
120 <para>When simultaneous capturing and overlay is supported and
121the hardware prohibits different image and frame buffer formats, the
122format requested first takes precedence. The attempt to capture
123(&VIDIOC-S-FMT;) or overlay (&VIDIOC-S-FBUF;) may fail with an
124&EBUSY; or return accordingly modified parameters..</para>
125 </section>
126
127 <section>
128 <title>Overlay Window</title>
129
130 <para>The overlaid image is determined by cropping and overlay
131window parameters. The former select an area of the video picture to
132capture, the latter how images are overlaid and clipped. Cropping
133initialization at minimum requires to reset the parameters to
134defaults. An example is given in <xref linkend="crop" />.</para>
135
136 <para>The overlay window is described by a &v4l2-window;. It
137defines the size of the image, its position over the graphics surface
138and the clipping to be applied. To get the current parameters
139applications set the <structfield>type</structfield> field of a
140&v4l2-format; to <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant> and
141call the &VIDIOC-G-FMT; ioctl. The driver fills the
142<structname>v4l2_window</structname> substructure named
143<structfield>win</structfield>. It is not possible to retrieve a
144previously programmed clipping list or bitmap.</para>
145
146 <para>To program the overlay window applications set the
147<structfield>type</structfield> field of a &v4l2-format; to
148<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, initialize the
149<structfield>win</structfield> substructure and call the
150&VIDIOC-S-FMT; ioctl. The driver adjusts the parameters against
151hardware limits and returns the actual parameters as
152<constant>VIDIOC_G_FMT</constant> does. Like
153<constant>VIDIOC_S_FMT</constant>, the &VIDIOC-TRY-FMT; ioctl can be
154used to learn about driver capabilities without actually changing
155driver state. Unlike <constant>VIDIOC_S_FMT</constant> this also works
156after the overlay has been enabled.</para>
157
158 <para>The scaling factor of the overlaid image is implied by the
159width and height given in &v4l2-window; and the size of the cropping
160rectangle. For more information see <xref linkend="crop" />.</para>
161
162 <para>When simultaneous capturing and overlay is supported and
163the hardware prohibits different image and window sizes, the size
164requested first takes precedence. The attempt to capture or overlay as
165well (&VIDIOC-S-FMT;) may fail with an &EBUSY; or return accordingly
166modified parameters.</para>
167
168 <table pgwide="1" frame="none" id="v4l2-window">
169 <title>struct <structname>v4l2_window</structname></title>
170 <tgroup cols="3">
171 &cs-str;
172 <tbody valign="top">
173 <row>
174 <entry>&v4l2-rect;</entry>
175 <entry><structfield>w</structfield></entry>
176 <entry>Size and position of the window relative to the
177top, left corner of the frame buffer defined with &VIDIOC-S-FBUF;. The
178window can extend the frame buffer width and height, the
179<structfield>x</structfield> and <structfield>y</structfield>
180coordinates can be negative, and it can lie completely outside the
181frame buffer. The driver clips the window accordingly, or if that is
182not possible, modifies its size and/or position.</entry>
183 </row>
184 <row>
185 <entry>&v4l2-field;</entry>
186 <entry><structfield>field</structfield></entry>
187 <entry>Applications set this field to determine which
188video field shall be overlaid, typically one of
189<constant>V4L2_FIELD_ANY</constant> (0),
190<constant>V4L2_FIELD_TOP</constant>,
191<constant>V4L2_FIELD_BOTTOM</constant> or
192<constant>V4L2_FIELD_INTERLACED</constant>. Drivers may have to choose
193a different field order and return the actual setting here.</entry>
194 </row>
195 <row>
196 <entry>__u32</entry>
197 <entry><structfield>chromakey</structfield></entry>
198 <entry>When chroma-keying has been negotiated with
199&VIDIOC-S-FBUF; applications set this field to the desired pixel value
200for the chroma key. The format is the same as the pixel format of the
201framebuffer (&v4l2-framebuffer;
202<structfield>fmt.pixelformat</structfield> field), with bytes in host
203order. E.&nbsp;g. for <link
204linkend="V4L2-PIX-FMT-BGR32"><constant>V4L2_PIX_FMT_BGR24</constant></link>
205the value should be 0xRRGGBB on a little endian, 0xBBGGRR on a big
206endian host.</entry>
207 </row>
208 <row>
209 <entry>&v4l2-clip; *</entry>
210 <entry><structfield>clips</structfield></entry>
211 <entry>When chroma-keying has <emphasis>not</emphasis>
212been negotiated and &VIDIOC-G-FBUF; indicated this capability,
213applications can set this field to point to an array of
214clipping rectangles.</entry>
215 </row>
216 <row>
217 <entry></entry>
218 <entry></entry>
219 <entry>Like the window coordinates
220<structfield>w</structfield>, clipping rectangles are defined relative
221to the top, left corner of the frame buffer. However clipping
222rectangles must not extend the frame buffer width and height, and they
223must not overlap. If possible applications should merge adjacent
224rectangles. Whether this must create x-y or y-x bands, or the order of
225rectangles, is not defined. When clip lists are not supported the
226driver ignores this field. Its contents after calling &VIDIOC-S-FMT;
227are undefined.</entry>
228 </row>
229 <row>
230 <entry>__u32</entry>
231 <entry><structfield>clipcount</structfield></entry>
232 <entry>When the application set the
233<structfield>clips</structfield> field, this field must contain the
234number of clipping rectangles in the list. When clip lists are not
235supported the driver ignores this field, its contents after calling
236<constant>VIDIOC_S_FMT</constant> are undefined. When clip lists are
237supported but no clipping is desired this field must be set to
238zero.</entry>
239 </row>
240 <row>
241 <entry>void *</entry>
242 <entry><structfield>bitmap</structfield></entry>
243 <entry>When chroma-keying has
244<emphasis>not</emphasis> been negotiated and &VIDIOC-G-FBUF; indicated
245this capability, applications can set this field to point to a
246clipping bit mask.</entry>
247 </row>
248 <row>
249 <entry spanname="hspan"><para>It must be of the same size
250as the window, <structfield>w.width</structfield> and
251<structfield>w.height</structfield>. Each bit corresponds to a pixel
252in the overlaid image, which is displayed only when the bit is
253<emphasis>set</emphasis>. Pixel coordinates translate to bits like:
254<programlisting>
255((__u8 *) <structfield>bitmap</structfield>)[<structfield>w.width</structfield> * y + x / 8] &amp; (1 &lt;&lt; (x &amp; 7))</programlisting></para><para>where <structfield>0</structfield> &le; x &lt;
256<structfield>w.width</structfield> and <structfield>0</structfield> &le;
257y &lt;<structfield>w.height</structfield>.<footnote>
258 <para>Should we require
259 <structfield>w.width</structfield> to be a multiple of
260 eight?</para>
261 </footnote></para><para>When a clipping
262bit mask is not supported the driver ignores this field, its contents
263after calling &VIDIOC-S-FMT; are undefined. When a bit mask is supported
264but no clipping is desired this field must be set to
265<constant>NULL</constant>.</para><para>Applications need not create a
266clip list or bit mask. When they pass both, or despite negotiating
267chroma-keying, the results are undefined. Regardless of the chosen
268method, the clipping abilities of the hardware may be limited in
269quantity or quality. The results when these limits are exceeded are
270undefined.<footnote>
271 <para>When the image is written into frame buffer
272memory it will be undesirable if the driver clips out less pixels
273than expected, because the application and graphics system are not
274aware these regions need to be refreshed. The driver should clip out
275more pixels or not write the image at all.</para>
276 </footnote></para></entry>
277 </row>
278 <row>
279 <entry>__u8</entry>
280 <entry><structfield>global_alpha</structfield></entry>
281 <entry>The global alpha value used to blend the
282framebuffer with video images, if global alpha blending has been
283negotiated (<constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant>, see
284&VIDIOC-S-FBUF;, <xref linkend="framebuffer-flags" />).</entry>
285 </row>
286 <row>
287 <entry></entry>
288 <entry></entry>
289 <entry>Note this field was added in Linux 2.6.23, extending the structure. However
290the <link linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls,
291which take a pointer to a <link
292linkend="v4l2-format">v4l2_format</link> parent structure with padding
293bytes at the end, are not affected.</entry>
294 </row>
295 </tbody>
296 </tgroup>
297 </table>
298
299 <table pgwide="1" frame="none" id="v4l2-clip">
300 <title>struct <structname>v4l2_clip</structname><footnote>
301 <para>The X Window system defines "regions" which are
302vectors of struct BoxRec { short x1, y1, x2, y2; } with width = x2 -
303x1 and height = y2 - y1, so one cannot pass X11 clip lists
304directly.</para>
305 </footnote></title>
306 <tgroup cols="3">
307 &cs-str;
308 <tbody valign="top">
309 <row>
310 <entry>&v4l2-rect;</entry>
311 <entry><structfield>c</structfield></entry>
312 <entry>Coordinates of the clipping rectangle, relative to
313the top, left corner of the frame buffer. Only window pixels
314<emphasis>outside</emphasis> all clipping rectangles are
315displayed.</entry>
316 </row>
317 <row>
318 <entry>&v4l2-clip; *</entry>
319 <entry><structfield>next</structfield></entry>
320 <entry>Pointer to the next clipping rectangle, NULL when
321this is the last rectangle. Drivers ignore this field, it cannot be
322used to pass a linked list of clipping rectangles.</entry>
323 </row>
324 </tbody>
325 </tgroup>
326 </table>
327
328 <!-- NB for easier reading this table is duplicated
329 in the vidioc-cropcap chapter.-->
330
331 <table pgwide="1" frame="none" id="v4l2-rect">
332 <title>struct <structname>v4l2_rect</structname></title>
333 <tgroup cols="3">
334 &cs-str;
335 <tbody valign="top">
336 <row>
337 <entry>__s32</entry>
338 <entry><structfield>left</structfield></entry>
339 <entry>Horizontal offset of the top, left corner of the
340rectangle, in pixels.</entry>
341 </row>
342 <row>
343 <entry>__s32</entry>
344 <entry><structfield>top</structfield></entry>
345 <entry>Vertical offset of the top, left corner of the
346rectangle, in pixels. Offsets increase to the right and down.</entry>
347 </row>
348 <row>
349 <entry>__s32</entry>
350 <entry><structfield>width</structfield></entry>
351 <entry>Width of the rectangle, in pixels.</entry>
352 </row>
353 <row>
354 <entry>__s32</entry>
355 <entry><structfield>height</structfield></entry>
356 <entry>Height of the rectangle, in pixels. Width and
357height cannot be negative, the fields are signed for hysterical
358reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject
359"Re:[V4L][patches!] Re:v4l2/kernel-2.5" --></entry>
360 </row>
361 </tbody>
362 </tgroup>
363 </table>
364 </section>
365
366 <section>
367 <title>Enabling Overlay</title>
368
369 <para>To start or stop the frame buffer overlay applications call
370the &VIDIOC-OVERLAY; ioctl.</para>
371 </section>
372
373 <!--
374Local Variables:
375mode: sgml
376sgml-parent-document: "v4l2.sgml"
377indent-tabs-mode: nil
378End:
379 -->
diff --git a/Documentation/DocBook/media/v4l/dev-radio.xml b/Documentation/DocBook/media/v4l/dev-radio.xml
new file mode 100644
index 000000000000..73aa90b45b34
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-radio.xml
@@ -0,0 +1,57 @@
1 <title>Radio Interface</title>
2
3 <para>This interface is intended for AM and FM (analog) radio
4receivers and transmitters.</para>
5
6 <para>Conventionally V4L2 radio devices are accessed through
7character device special files named <filename>/dev/radio</filename>
8and <filename>/dev/radio0</filename> to
9<filename>/dev/radio63</filename> with major number 81 and minor
10numbers 64 to 127.</para>
11
12 <section>
13 <title>Querying Capabilities</title>
14
15 <para>Devices supporting the radio interface set the
16<constant>V4L2_CAP_RADIO</constant> and
17<constant>V4L2_CAP_TUNER</constant> or
18<constant>V4L2_CAP_MODULATOR</constant> flag in the
19<structfield>capabilities</structfield> field of &v4l2-capability;
20returned by the &VIDIOC-QUERYCAP; ioctl. Other combinations of
21capability flags are reserved for future extensions.</para>
22 </section>
23
24 <section>
25 <title>Supplemental Functions</title>
26
27 <para>Radio devices can support <link
28linkend="control">controls</link>, and must support the <link
29linkend="tuner">tuner or modulator</link> ioctls.</para>
30
31 <para>They do not support the video input or output, audio input
32or output, video standard, cropping and scaling, compression and
33streaming parameter, or overlay ioctls. All other ioctls and I/O
34methods are reserved for future extensions.</para>
35 </section>
36
37 <section>
38 <title>Programming</title>
39
40 <para>Radio devices may have a couple audio controls (as discussed
41in <xref linkend="control" />) such as a volume control, possibly custom
42controls. Further all radio devices have one tuner or modulator (these are
43discussed in <xref linkend="tuner" />) with index number zero to select
44the radio frequency and to determine if a monaural or FM stereo
45program is received/emitted. Drivers switch automatically between AM and FM
46depending on the selected frequency. The &VIDIOC-G-TUNER; or
47&VIDIOC-G-MODULATOR; ioctl
48reports the supported frequency range.</para>
49 </section>
50
51<!--
52Local Variables:
53mode: sgml
54sgml-parent-document: "v4l2.sgml"
55indent-tabs-mode: nil
56End:
57 -->
diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
new file mode 100644
index 000000000000..c5a70bdfaf27
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml
@@ -0,0 +1,347 @@
1 <title>Raw VBI Data Interface</title>
2
3 <para>VBI is an abbreviation of Vertical Blanking Interval, a gap
4in the sequence of lines of an analog video signal. During VBI
5no picture information is transmitted, allowing some time while the
6electron beam of a cathode ray tube TV returns to the top of the
7screen. Using an oscilloscope you will find here the vertical
8synchronization pulses and short data packages ASK
9modulated<footnote><para>ASK: Amplitude-Shift Keying. A high signal
10level represents a '1' bit, a low level a '0' bit.</para></footnote>
11onto the video signal. These are transmissions of services such as
12Teletext or Closed Caption.</para>
13
14 <para>Subject of this interface type is raw VBI data, as sampled off
15a video signal, or to be added to a signal for output.
16The data format is similar to uncompressed video images, a number of
17lines times a number of samples per line, we call this a VBI image.</para>
18
19 <para>Conventionally V4L2 VBI devices are accessed through character
20device special files named <filename>/dev/vbi</filename> and
21<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> with
22major number 81 and minor numbers 224 to 255.
23<filename>/dev/vbi</filename> is typically a symbolic link to the
24preferred VBI device. This convention applies to both input and output
25devices.</para>
26
27 <para>To address the problems of finding related video and VBI
28devices VBI capturing and output is also available as device function
29under <filename>/dev/video</filename>. To capture or output raw VBI
30data with these devices applications must call the &VIDIOC-S-FMT;
31ioctl. Accessed as <filename>/dev/vbi</filename>, raw VBI capturing
32or output is the default device function.</para>
33
34 <section>
35 <title>Querying Capabilities</title>
36
37 <para>Devices supporting the raw VBI capturing or output API set
38the <constant>V4L2_CAP_VBI_CAPTURE</constant> or
39<constant>V4L2_CAP_VBI_OUTPUT</constant> flags, respectively, in the
40<structfield>capabilities</structfield> field of &v4l2-capability;
41returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
42read/write, streaming or asynchronous I/O methods must be
43supported. VBI devices may or may not have a tuner or modulator.</para>
44 </section>
45
46 <section>
47 <title>Supplemental Functions</title>
48
49 <para>VBI devices shall support <link linkend="video">video
50input or output</link>, <link linkend="tuner">tuner or
51modulator</link>, and <link linkend="control">controls</link> ioctls
52as needed. The <link linkend="standard">video standard</link> ioctls provide
53information vital to program a VBI device, therefore must be
54supported.</para>
55 </section>
56
57 <section>
58 <title>Raw VBI Format Negotiation</title>
59
60 <para>Raw VBI sampling abilities can vary, in particular the
61sampling frequency. To properly interpret the data V4L2 specifies an
62ioctl to query the sampling parameters. Moreover, to allow for some
63flexibility applications can also suggest different parameters.</para>
64
65 <para>As usual these parameters are <emphasis>not</emphasis>
66reset at &func-open; time to permit Unix tool chains, programming a
67device and then reading from it as if it was a plain file. Well
68written V4L2 applications should always ensure they really get what
69they want, requesting reasonable parameters and then checking if the
70actual parameters are suitable.</para>
71
72 <para>To query the current raw VBI capture parameters
73applications set the <structfield>type</structfield> field of a
74&v4l2-format; to <constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant> or
75<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>, and call the
76&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
77the &v4l2-vbi-format; <structfield>vbi</structfield> member of the
78<structfield>fmt</structfield> union.</para>
79
80 <para>To request different parameters applications set the
81<structfield>type</structfield> field of a &v4l2-format; as above and
82initialize all fields of the &v4l2-vbi-format;
83<structfield>vbi</structfield> member of the
84<structfield>fmt</structfield> union, or better just modify the
85results of <constant>VIDIOC_G_FMT</constant>, and call the
86&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers return
87an &EINVAL; only when the given parameters are ambiguous, otherwise
88they modify the parameters according to the hardware capabilites and
89return the actual parameters. When the driver allocates resources at
90this point, it may return an &EBUSY; to indicate the returned
91parameters are valid but the required resources are currently not
92available. That may happen for instance when the video and VBI areas
93to capture would overlap, or when the driver supports multiple opens
94and another process already requested VBI capturing or output. Anyway,
95applications must expect other resource allocation points which may
96return <errorcode>EBUSY</errorcode>, at the &VIDIOC-STREAMON; ioctl
97and the first read(), write() and select() call.</para>
98
99 <para>VBI devices must implement both the
100<constant>VIDIOC_G_FMT</constant> and
101<constant>VIDIOC_S_FMT</constant> ioctl, even if
102<constant>VIDIOC_S_FMT</constant> ignores all requests and always
103returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
104<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
105
106 <table pgwide="1" frame="none" id="v4l2-vbi-format">
107 <title>struct <structname>v4l2_vbi_format</structname></title>
108 <tgroup cols="3">
109 &cs-str;
110 <tbody valign="top">
111 <row>
112 <entry>__u32</entry>
113 <entry><structfield>sampling_rate</structfield></entry>
114 <entry>Samples per second, i.&nbsp;e. unit 1 Hz.</entry>
115 </row>
116 <row>
117 <entry>__u32</entry>
118 <entry><structfield>offset</structfield></entry>
119 <entry><para>Horizontal offset of the VBI image,
120relative to the leading edge of the line synchronization pulse and
121counted in samples: The first sample in the VBI image will be located
122<structfield>offset</structfield> /
123<structfield>sampling_rate</structfield> seconds following the leading
124edge. See also <xref linkend="vbi-hsync" />.</para></entry>
125 </row>
126 <row>
127 <entry>__u32</entry>
128 <entry><structfield>samples_per_line</structfield></entry>
129 <entry></entry>
130 </row>
131 <row>
132 <entry>__u32</entry>
133 <entry><structfield>sample_format</structfield></entry>
134 <entry><para>Defines the sample format as in <xref
135linkend="pixfmt" />, a four-character-code.<footnote>
136 <para>A few devices may be unable to
137sample VBI data at all but can extend the video capture window to the
138VBI region.</para>
139 </footnote> Usually this is
140<constant>V4L2_PIX_FMT_GREY</constant>, i.&nbsp;e. each sample
141consists of 8 bits with lower values oriented towards the black level.
142Do not assume any other correlation of values with the signal level.
143For example, the MSB does not necessarily indicate if the signal is
144'high' or 'low' because 128 may not be the mean value of the
145signal. Drivers shall not convert the sample format by software.</para></entry>
146 </row>
147 <row>
148 <entry>__u32</entry>
149 <entry><structfield>start</structfield>[2]</entry>
150 <entry>This is the scanning system line number
151associated with the first line of the VBI image, of the first and the
152second field respectively. See <xref linkend="vbi-525" /> and
153<xref linkend="vbi-625" /> for valid values. VBI input drivers can
154return start values 0 if the hardware cannot reliable identify
155scanning lines, VBI acquisition may not require this
156information.</entry>
157 </row>
158 <row>
159 <entry>__u32</entry>
160 <entry><structfield>count</structfield>[2]</entry>
161 <entry>The number of lines in the first and second
162field image, respectively.</entry>
163 </row>
164 <row>
165 <entry spanname="hspan"><para>Drivers should be as
166flexibility as possible. For example, it may be possible to extend or
167move the VBI capture window down to the picture area, implementing a
168'full field mode' to capture data service transmissions embedded in
169the picture.</para><para>An application can set the first or second
170<structfield>count</structfield> value to zero if no data is required
171from the respective field; <structfield>count</structfield>[1] if the
172scanning system is progressive, &ie; not interlaced. The
173corresponding start value shall be ignored by the application and
174driver. Anyway, drivers may not support single field capturing and
175return both count values non-zero.</para><para>Both
176<structfield>count</structfield> values set to zero, or line numbers
177outside the bounds depicted in <xref linkend="vbi-525" /> and <xref
178 linkend="vbi-625" />, or a field image covering
179lines of two fields, are invalid and shall not be returned by the
180driver.</para><para>To initialize the <structfield>start</structfield>
181and <structfield>count</structfield> fields, applications must first
182determine the current video standard selection. The &v4l2-std-id; or
183the <structfield>framelines</structfield> field of &v4l2-standard; can
184be evaluated for this purpose.</para></entry>
185 </row>
186 <row>
187 <entry>__u32</entry>
188 <entry><structfield>flags</structfield></entry>
189 <entry>See <xref linkend="vbifmt-flags" /> below. Currently
190only drivers set flags, applications must set this field to
191zero.</entry>
192 </row>
193 <row>
194 <entry>__u32</entry>
195 <entry><structfield>reserved</structfield>[2]</entry>
196 <entry>This array is reserved for future extensions.
197Drivers and applications must set it to zero.</entry>
198 </row>
199 </tbody>
200 </tgroup>
201 </table>
202
203 <table pgwide="1" frame="none" id="vbifmt-flags">
204 <title>Raw VBI Format Flags</title>
205 <tgroup cols="3">
206 &cs-def;
207 <tbody valign="top">
208 <row>
209 <entry><constant>V4L2_VBI_UNSYNC</constant></entry>
210 <entry>0x0001</entry>
211 <entry><para>This flag indicates hardware which does not
212properly distinguish between fields. Normally the VBI image stores the
213first field (lower scanning line numbers) first in memory. This may be
214a top or bottom field depending on the video standard. When this flag
215is set the first or second field may be stored first, however the
216fields are still in correct temporal order with the older field first
217in memory.<footnote>
218 <para>Most VBI services transmit on both fields, but
219some have different semantics depending on the field number. These
220cannot be reliable decoded or encoded when
221<constant>V4L2_VBI_UNSYNC</constant> is set.</para>
222 </footnote></para></entry>
223 </row>
224 <row>
225 <entry><constant>V4L2_VBI_INTERLACED</constant></entry>
226 <entry>0x0002</entry>
227 <entry>By default the two field images will be passed
228sequentially; all lines of the first field followed by all lines of
229the second field (compare <xref linkend="field-order" />
230<constant>V4L2_FIELD_SEQ_TB</constant> and
231<constant>V4L2_FIELD_SEQ_BT</constant>, whether the top or bottom
232field is first in memory depends on the video standard). When this
233flag is set, the two fields are interlaced (cf.
234<constant>V4L2_FIELD_INTERLACED</constant>). The first line of the
235first field followed by the first line of the second field, then the
236two second lines, and so on. Such a layout may be necessary when the
237hardware has been programmed to capture or output interlaced video
238images and is unable to separate the fields for VBI capturing at
239the same time. For simplicity setting this flag implies that both
240<structfield>count</structfield> values are equal and non-zero.</entry>
241 </row>
242 </tbody>
243 </tgroup>
244 </table>
245
246 <figure id="vbi-hsync">
247 <title>Line synchronization</title>
248 <mediaobject>
249 <imageobject>
250 <imagedata fileref="vbi_hsync.pdf" format="PS" />
251 </imageobject>
252 <imageobject>
253 <imagedata fileref="vbi_hsync.gif" format="GIF" />
254 </imageobject>
255 <textobject>
256 <phrase>Line synchronization diagram</phrase>
257 </textobject>
258 </mediaobject>
259 </figure>
260
261 <figure id="vbi-525">
262 <title>ITU-R 525 line numbering (M/NTSC and M/PAL)</title>
263 <mediaobject>
264 <imageobject>
265 <imagedata fileref="vbi_525.pdf" format="PS" />
266 </imageobject>
267 <imageobject>
268 <imagedata fileref="vbi_525.gif" format="GIF" />
269 </imageobject>
270 <textobject>
271 <phrase>NTSC field synchronization diagram</phrase>
272 </textobject>
273 <caption>
274 <para>(1) For the purpose of this specification field 2
275starts in line 264 and not 263.5 because half line capturing is not
276supported.</para>
277 </caption>
278 </mediaobject>
279 </figure>
280
281 <figure id="vbi-625">
282 <title>ITU-R 625 line numbering</title>
283 <mediaobject>
284 <imageobject>
285 <imagedata fileref="vbi_625.pdf" format="PS" />
286 </imageobject>
287 <imageobject>
288 <imagedata fileref="vbi_625.gif" format="GIF" />
289 </imageobject>
290 <textobject>
291 <phrase>PAL/SECAM field synchronization diagram</phrase>
292 </textobject>
293 <caption>
294 <para>(1) For the purpose of this specification field 2
295starts in line 314 and not 313.5 because half line capturing is not
296supported.</para>
297 </caption>
298 </mediaobject>
299 </figure>
300
301 <para>Remember the VBI image format depends on the selected
302video standard, therefore the application must choose a new standard or
303query the current standard first. Attempts to read or write data ahead
304of format negotiation, or after switching the video standard which may
305invalidate the negotiated VBI parameters, should be refused by the
306driver. A format change during active I/O is not permitted.</para>
307 </section>
308
309 <section>
310 <title>Reading and writing VBI images</title>
311
312 <para>To assure synchronization with the field number and easier
313implementation, the smallest unit of data passed at a time is one
314frame, consisting of two fields of VBI images immediately following in
315memory.</para>
316
317 <para>The total size of a frame computes as follows:</para>
318
319 <programlisting>
320(<structfield>count</structfield>[0] + <structfield>count</structfield>[1]) *
321<structfield>samples_per_line</structfield> * sample size in bytes</programlisting>
322
323 <para>The sample size is most likely always one byte,
324applications must check the <structfield>sample_format</structfield>
325field though, to function properly with other drivers.</para>
326
327 <para>A VBI device may support <link
328 linkend="rw">read/write</link> and/or streaming (<link
329 linkend="mmap">memory mapping</link> or <link
330 linkend="userp">user pointer</link>) I/O. The latter bears the
331possibility of synchronizing video and
332VBI data by using buffer timestamps.</para>
333
334 <para>Remember the &VIDIOC-STREAMON; ioctl and the first read(),
335write() and select() call can be resource allocation points returning
336an &EBUSY; if the required hardware resources are temporarily
337unavailable, for example the device is already in use by another
338process.</para>
339 </section>
340
341 <!--
342Local Variables:
343mode: sgml
344sgml-parent-document: "v4l2.sgml"
345indent-tabs-mode: nil
346End:
347 -->
diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml
new file mode 100644
index 000000000000..2427f54397e7
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-rds.xml
@@ -0,0 +1,204 @@
1 <title>RDS Interface</title>
2
3 <para>The Radio Data System transmits supplementary
4information in binary format, for example the station name or travel
5information, on an inaudible audio subcarrier of a radio program. This
6interface is aimed at devices capable of receiving and/or transmitting RDS
7information.</para>
8
9 <para>For more information see the core RDS standard <xref linkend="en50067" />
10and the RBDS standard <xref linkend="nrsc4" />.</para>
11
12 <para>Note that the RBDS standard as is used in the USA is almost identical
13to the RDS standard. Any RDS decoder/encoder can also handle RBDS. Only some of the
14fields have slightly different meanings. See the RBDS standard for more
15information.</para>
16
17 <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
18This is a proprietary format which seems to be discontinued. The RDS interface does not
19support this format. Should support for MMBS (or the so-called 'E blocks' in general)
20be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
21
22 <section>
23 <title>Querying Capabilities</title>
24
25 <para>Devices supporting the RDS capturing API set
26the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
27the <structfield>capabilities</structfield> field of &v4l2-capability;
28returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS
29will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in
30the <structfield>capability</structfield> field of &v4l2-tuner;. If
31the driver only passes RDS blocks without interpreting the data
32the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be
33set, see <link linkend="reading-rds-data">Reading RDS data</link>.
34For future use the
35flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> has also been
36defined. However, a driver for a radio tuner with this capability does
37not yet exist, so if you are planning to write such a driver you
38should discuss this on the linux-media mailing list: &v4l-ml;.</para>
39
40 <para> Whether an RDS signal is present can be detected by looking
41at the <structfield>rxsubchans</structfield> field of &v4l2-tuner;:
42the <constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data
43was detected.</para>
44
45 <para>Devices supporting the RDS output API
46set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
47the <structfield>capabilities</structfield> field of &v4l2-capability;
48returned by the &VIDIOC-QUERYCAP; ioctl.
49Any modulator that supports RDS will set the
50<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
51field of &v4l2-modulator;.
52In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
53bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.
54If the driver only passes RDS blocks without interpreting the data
55the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be set. If the
56tuner is capable of handling RDS entities like program identification codes and radio
57text, the flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> should be set,
58see <link linkend="writing-rds-data">Writing RDS data</link> and
59<link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para>
60 </section>
61
62 <section id="reading-rds-data">
63 <title>Reading RDS data</title>
64
65 <para>RDS data can be read from the radio device
66with the &func-read; function. The data is packed in groups of three bytes.</para>
67 </section>
68
69 <section id="writing-rds-data">
70 <title>Writing RDS data</title>
71
72 <para>RDS data can be written to the radio device
73with the &func-write; function. The data is packed in groups of three bytes,
74as follows:</para>
75 </section>
76
77 <section>
78 <title>RDS datastructures</title>
79 <table frame="none" pgwide="1" id="v4l2-rds-data">
80 <title>struct
81<structname>v4l2_rds_data</structname></title>
82 <tgroup cols="3">
83 <colspec colname="c1" colwidth="1*" />
84 <colspec colname="c2" colwidth="1*" />
85 <colspec colname="c3" colwidth="5*" />
86 <tbody valign="top">
87 <row>
88 <entry>__u8</entry>
89 <entry><structfield>lsb</structfield></entry>
90 <entry>Least Significant Byte of RDS Block</entry>
91 </row>
92 <row>
93 <entry>__u8</entry>
94 <entry><structfield>msb</structfield></entry>
95 <entry>Most Significant Byte of RDS Block</entry>
96 </row>
97 <row>
98 <entry>__u8</entry>
99 <entry><structfield>block</structfield></entry>
100 <entry>Block description</entry>
101 </row>
102 </tbody>
103 </tgroup>
104 </table>
105 <table frame="none" pgwide="1" id="v4l2-rds-block">
106 <title>Block description</title>
107 <tgroup cols="2">
108 <colspec colname="c1" colwidth="1*" />
109 <colspec colname="c2" colwidth="5*" />
110 <tbody valign="top">
111 <row>
112 <entry>Bits 0-2</entry>
113 <entry>Block (aka offset) of the received data.</entry>
114 </row>
115 <row>
116 <entry>Bits 3-5</entry>
117 <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
118 </row>
119 <row>
120 <entry>Bit 6</entry>
121 <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
122 </row>
123 <row>
124 <entry>Bit 7</entry>
125 <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
126 </row>
127 </tbody>
128 </tgroup>
129 </table>
130
131 <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
132 <title>Block defines</title>
133 <tgroup cols="4">
134 <colspec colname="c1" colwidth="1*" />
135 <colspec colname="c2" colwidth="1*" />
136 <colspec colname="c3" colwidth="1*" />
137 <colspec colname="c4" colwidth="5*" />
138 <tbody valign="top">
139 <row>
140 <entry>V4L2_RDS_BLOCK_MSK</entry>
141 <entry> </entry>
142 <entry>7</entry>
143 <entry>Mask for bits 0-2 to get the block ID.</entry>
144 </row>
145 <row>
146 <entry>V4L2_RDS_BLOCK_A</entry>
147 <entry> </entry>
148 <entry>0</entry>
149 <entry>Block A.</entry>
150 </row>
151 <row>
152 <entry>V4L2_RDS_BLOCK_B</entry>
153 <entry> </entry>
154 <entry>1</entry>
155 <entry>Block B.</entry>
156 </row>
157 <row>
158 <entry>V4L2_RDS_BLOCK_C</entry>
159 <entry> </entry>
160 <entry>2</entry>
161 <entry>Block C.</entry>
162 </row>
163 <row>
164 <entry>V4L2_RDS_BLOCK_D</entry>
165 <entry> </entry>
166 <entry>3</entry>
167 <entry>Block D.</entry>
168 </row>
169 <row>
170 <entry>V4L2_RDS_BLOCK_C_ALT</entry>
171 <entry> </entry>
172 <entry>4</entry>
173 <entry>Block C'.</entry>
174 </row>
175 <row>
176 <entry>V4L2_RDS_BLOCK_INVALID</entry>
177 <entry>read-only</entry>
178 <entry>7</entry>
179 <entry>An invalid block.</entry>
180 </row>
181 <row>
182 <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
183 <entry>read-only</entry>
184 <entry>0x40</entry>
185 <entry>A bit error was detected but corrected.</entry>
186 </row>
187 <row>
188 <entry>V4L2_RDS_BLOCK_ERROR</entry>
189 <entry>read-only</entry>
190 <entry>0x80</entry>
191 <entry>An uncorrectable error occurred.</entry>
192 </row>
193 </tbody>
194 </tgroup>
195 </table>
196 </section>
197
198<!--
199Local Variables:
200mode: sgml
201sgml-parent-document: "v4l2.sgml"
202indent-tabs-mode: nil
203End:
204 -->
diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
new file mode 100644
index 000000000000..69e789fa7f7b
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
@@ -0,0 +1,708 @@
1 <title>Sliced VBI Data Interface</title>
2
3 <para>VBI stands for Vertical Blanking Interval, a gap in the
4sequence of lines of an analog video signal. During VBI no picture
5information is transmitted, allowing some time while the electron beam
6of a cathode ray tube TV returns to the top of the screen.</para>
7
8 <para>Sliced VBI devices use hardware to demodulate data transmitted
9in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by
10software, see also the <link linkend="raw-vbi">raw VBI
11interface</link>. The data is passed as short packets of fixed size,
12covering one scan line each. The number of packets per video frame is
13variable.</para>
14
15 <para>Sliced VBI capture and output devices are accessed through the
16same character special files as raw VBI devices. When a driver
17supports both interfaces, the default function of a
18<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI
19capturing or output, and the sliced VBI function is only available
20after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a
21<filename>/dev/video</filename> device may support the sliced VBI API,
22however the default function here is video capturing or output.
23Different file descriptors must be used to pass raw and sliced VBI
24data simultaneously, if this is supported by the driver.</para>
25
26 <section>
27 <title>Querying Capabilities</title>
28
29 <para>Devices supporting the sliced VBI capturing or output API
30set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or
31<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in
32the <structfield>capabilities</structfield> field of &v4l2-capability;
33returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
34read/write, streaming or asynchronous <link linkend="io">I/O
35methods</link> must be supported. Sliced VBI devices may have a tuner
36or modulator.</para>
37 </section>
38
39 <section>
40 <title>Supplemental Functions</title>
41
42 <para>Sliced VBI devices shall support <link linkend="video">video
43input or output</link> and <link linkend="tuner">tuner or
44modulator</link> ioctls if they have these capabilities, and they may
45support <link linkend="control">control</link> ioctls. The <link
46linkend="standard">video standard</link> ioctls provide information
47vital to program a sliced VBI device, therefore must be
48supported.</para>
49 </section>
50
51 <section id="sliced-vbi-format-negotitation">
52 <title>Sliced VBI Format Negotiation</title>
53
54 <para>To find out which data services are supported by the
55hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl.
56All drivers implementing the sliced VBI interface must support this
57ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl
58when the number of VBI lines the hardware can capture or output per
59frame, or the number of services it can identify on a given line are
60limited. For example on PAL line 16 the hardware may be able to look
61for a VPS or Teletext signal, but not both at the same time.</para>
62
63 <para>To determine the currently selected services applications
64set the <structfield>type </structfield> field of &v4l2-format; to
65<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant>
66V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT;
67ioctl fills the <structfield>fmt.sliced</structfield> member, a
68&v4l2-sliced-vbi-format;.</para>
69
70 <para>Applications can request different parameters by
71initializing or modifying the <structfield>fmt.sliced</structfield>
72member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the
73<structname>v4l2_format</structname> structure.</para>
74
75 <para>The sliced VBI API is more complicated than the raw VBI API
76because the hardware must be told which VBI service to expect on each
77scan line. Not all services may be supported by the hardware on all
78lines (this is especially true for VBI output where Teletext is often
79unsupported and other services can only be inserted in one specific
80line). In many cases, however, it is sufficient to just set the
81<structfield>service_set</structfield> field to the required services
82and let the driver fill the <structfield>service_lines</structfield>
83array according to hardware capabilities. Only if more precise control
84is needed should the programmer set the
85<structfield>service_lines</structfield> array explicitly.</para>
86
87 <para>The &VIDIOC-S-FMT; ioctl modifies the parameters
88according to hardware capabilities. When the driver allocates
89resources at this point, it may return an &EBUSY; if the required
90resources are temporarily unavailable. Other resource allocation
91points which may return <errorcode>EBUSY</errorcode> can be the
92&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and
93&func-select; call.</para>
94
95 <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format">
96 <title>struct
97<structname>v4l2_sliced_vbi_format</structname></title>
98 <tgroup cols="5">
99 <colspec colname="c1" colwidth="3*" />
100 <colspec colname="c2" colwidth="3*" />
101 <colspec colname="c3" colwidth="2*" />
102 <colspec colname="c4" colwidth="2*" />
103 <colspec colname="c5" colwidth="2*" />
104 <spanspec namest="c3" nameend="c5" spanname="hspan" />
105 <tbody valign="top">
106 <row>
107 <entry>__u32</entry>
108 <entry><structfield>service_set</structfield></entry>
109 <entry spanname="hspan"><para>If
110<structfield>service_set</structfield> is non-zero when passed with
111&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the
112<structfield>service_lines</structfield> array will be filled by the
113driver according to the services specified in this field. For example,
114if <structfield>service_set</structfield> is initialized with
115<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a
116driver for the cx25840 video decoder sets lines 7-22 of both
117fields<footnote><para>According to <link
118linkend="ets300706">ETS&nbsp;300&nbsp;706</link> lines 6-22 of the
119first field and lines 5-22 of the second field may carry Teletext
120data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant>
121and line 23 of the first field to
122<constant>V4L2_SLICED_WSS_625</constant>. If
123<structfield>service_set</structfield> is set to zero, then the values
124of <structfield>service_lines</structfield> will be used instead.
125</para><para>On return the driver sets this field to the union of all
126elements of the returned <structfield>service_lines</structfield>
127array. It may contain less services than requested, perhaps just one,
128if the hardware cannot handle more services simultaneously. It may be
129empty (zero) if none of the requested services are supported by the
130hardware.</para></entry>
131 </row>
132 <row>
133 <entry>__u16</entry>
134 <entry><structfield>service_lines</structfield>[2][24]</entry>
135 <entry spanname="hspan"><para>Applications initialize this
136array with sets of data services the driver shall look for or insert
137on the respective scan line. Subject to hardware capabilities drivers
138return the requested set, a subset, which may be just a single
139service, or an empty set. When the hardware cannot handle multiple
140services on the same line the driver shall choose one. No assumptions
141can be made on which service the driver chooses.</para><para>Data
142services are defined in <xref linkend="vbi-services2" />. Array indices
143map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref
144 linkend="vbi-625" />) as follows: <!-- No nested
145tables, sigh. --></para></entry>
146 </row>
147 <row>
148 <entry></entry>
149 <entry></entry>
150 <entry>Element</entry>
151 <entry>525 line systems</entry>
152 <entry>625 line systems</entry>
153 </row>
154 <row>
155 <entry></entry>
156 <entry></entry>
157 <entry><structfield>service_lines</structfield>[0][1]</entry>
158 <entry align="center">1</entry>
159 <entry align="center">1</entry>
160 </row>
161 <row>
162 <entry></entry>
163 <entry></entry>
164 <entry><structfield>service_lines</structfield>[0][23]</entry>
165 <entry align="center">23</entry>
166 <entry align="center">23</entry>
167 </row>
168 <row>
169 <entry></entry>
170 <entry></entry>
171 <entry><structfield>service_lines</structfield>[1][1]</entry>
172 <entry align="center">264</entry>
173 <entry align="center">314</entry>
174 </row>
175 <row>
176 <entry></entry>
177 <entry></entry>
178 <entry><structfield>service_lines</structfield>[1][23]</entry>
179 <entry align="center">286</entry>
180 <entry align="center">336</entry>
181 </row>
182 <!-- End of line numbers table. -->
183 <row>
184 <entry></entry>
185 <entry></entry>
186 <entry spanname="hspan">Drivers must set
187<structfield>service_lines</structfield>[0][0] and
188<structfield>service_lines</structfield>[1][0] to zero.</entry>
189 </row>
190 <row>
191 <entry>__u32</entry>
192 <entry><structfield>io_size</structfield></entry>
193 <entry spanname="hspan">Maximum number of bytes passed by
194one &func-read; or &func-write; call, and the buffer size in bytes for
195the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
196the size of &v4l2-sliced-vbi-data; times the number of non-zero
197elements in the returned <structfield>service_lines</structfield>
198array (that is the number of lines potentially carrying data).</entry>
199 </row>
200 <row>
201 <entry>__u32</entry>
202 <entry><structfield>reserved</structfield>[2]</entry>
203 <entry spanname="hspan">This array is reserved for future
204extensions. Applications and drivers must set it to zero.</entry>
205 </row>
206 </tbody>
207 </tgroup>
208 </table>
209
210 <!-- See also vidioc-g-sliced-vbi-cap.sgml -->
211 <table frame="none" pgwide="1" id="vbi-services2">
212 <title>Sliced VBI services</title>
213 <tgroup cols="5">
214 <colspec colname="c1" colwidth="2*" />
215 <colspec colname="c2" colwidth="1*" />
216 <colspec colname="c3" colwidth="1*" />
217 <colspec colname="c4" colwidth="2*" />
218 <colspec colname="c5" colwidth="2*" />
219 <spanspec namest="c3" nameend="c5" spanname="rlp" />
220 <thead>
221 <row>
222 <entry>Symbol</entry>
223 <entry>Value</entry>
224 <entry>Reference</entry>
225 <entry>Lines, usually</entry>
226 <entry>Payload</entry>
227 </row>
228 </thead>
229 <tbody valign="top">
230 <row>
231 <entry><constant>V4L2_SLICED_TELETEXT_B</constant>
232(Teletext System B)</entry>
233 <entry>0x0001</entry>
234 <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
235 <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
236 <entry>Last 42 of the 45 byte Teletext packet, that is
237without clock run-in and framing code, lsb first transmitted.</entry>
238 </row>
239 <row>
240 <entry><constant>V4L2_SLICED_VPS</constant></entry>
241 <entry>0x0400</entry>
242 <entry><xref linkend="ets300231" /></entry>
243 <entry>PAL line 16</entry>
244 <entry>Byte number 3 to 15 according to Figure 9 of
245ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
246 </row>
247 <row>
248 <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
249 <entry>0x1000</entry>
250 <entry><xref linkend="eia608" /></entry>
251 <entry>NTSC line 21, 284 (second field 21)</entry>
252 <entry>Two bytes in transmission order, including parity
253bit, lsb first transmitted.</entry>
254 </row>
255 <row>
256 <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
257 <entry>0x4000</entry>
258 <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry>
259 <entry>PAL/SECAM line 23</entry>
260 <entry><screen>
261Byte 0 1
262 msb lsb msb lsb
263 Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
264</screen></entry>
265 </row>
266 <row>
267 <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
268 <entry>0x1000</entry>
269 <entry spanname="rlp">Set of services applicable to 525
270line systems.</entry>
271 </row>
272 <row>
273 <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
274 <entry>0x4401</entry>
275 <entry spanname="rlp">Set of services applicable to 625
276line systems.</entry>
277 </row>
278 </tbody>
279 </tgroup>
280 </table>
281
282 <para>Drivers may return an &EINVAL; when applications attempt to
283read or write data without prior format negotiation, after switching
284the video standard (which may invalidate the negotiated VBI
285parameters) and after switching the video input (which may change the
286video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
287an &EBUSY; when applications attempt to change the format while i/o is
288in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
289and after the first &func-read; or &func-write; call).</para>
290 </section>
291
292 <section>
293 <title>Reading and writing sliced VBI data</title>
294
295 <para>A single &func-read; or &func-write; call must pass all data
296belonging to one video frame. That is an array of
297<structname>v4l2_sliced_vbi_data</structname> structures with one or
298more elements and a total size not exceeding
299<structfield>io_size</structfield> bytes. Likewise in streaming I/O
300mode one buffer of <structfield>io_size</structfield> bytes must
301contain data of one video frame. The <structfield>id</structfield> of
302unused <structname>v4l2_sliced_vbi_data</structname> elements must be
303zero.</para>
304
305 <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data">
306 <title>struct
307<structname>v4l2_sliced_vbi_data</structname></title>
308 <tgroup cols="3">
309 &cs-def;
310 <tbody valign="top">
311 <row>
312 <entry>__u32</entry>
313 <entry><structfield>id</structfield></entry>
314 <entry>A flag from <xref linkend="vbi-services" />
315identifying the type of data in this packet. Only a single bit must be
316set. When the <structfield>id</structfield> of a captured packet is
317zero, the packet is empty and the contents of other fields are
318undefined. Applications shall ignore empty packets. When the
319<structfield>id</structfield> of a packet for output is zero the
320contents of the <structfield>data</structfield> field are undefined
321and the driver must no longer insert data on the requested
322<structfield>field</structfield> and
323<structfield>line</structfield>.</entry>
324 </row>
325 <row>
326 <entry>__u32</entry>
327 <entry><structfield>field</structfield></entry>
328 <entry>The video field number this data has been captured
329from, or shall be inserted at. <constant>0</constant> for the first
330field, <constant>1</constant> for the second field.</entry>
331 </row>
332 <row>
333 <entry>__u32</entry>
334 <entry><structfield>line</structfield></entry>
335 <entry>The field (as opposed to frame) line number this
336data has been captured from, or shall be inserted at. See <xref
337 linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid
338values. Sliced VBI capture devices can set the line number of all
339packets to <constant>0</constant> if the hardware cannot reliably
340identify scan lines. The field number must always be valid.</entry>
341 </row>
342 <row>
343 <entry>__u32</entry>
344 <entry><structfield>reserved</structfield></entry>
345 <entry>This field is reserved for future extensions.
346Applications and drivers must set it to zero.</entry>
347 </row>
348 <row>
349 <entry>__u8</entry>
350 <entry><structfield>data</structfield>[48]</entry>
351 <entry>The packet payload. See <xref
352 linkend="vbi-services" /> for the contents and number of
353bytes passed for each data type. The contents of padding bytes at the
354end of this array are undefined, drivers and applications shall ignore
355them.</entry>
356 </row>
357 </tbody>
358 </tgroup>
359 </table>
360
361 <para>Packets are always passed in ascending line number order,
362without duplicate line numbers. The &func-write; function and the
363&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
364this rule. They must also return an &EINVAL; when applications pass an
365incorrect field or line number, or a combination of
366<structfield>field</structfield>, <structfield>line</structfield> and
367<structfield>id</structfield> which has not been negotiated with the
368&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
369unknown the driver must pass the packets in transmitted order. The
370driver can insert empty packets with <structfield>id</structfield> set
371to zero anywhere in the packet array.</para>
372
373 <para>To assure synchronization and to distinguish from frame
374dropping, when a captured frame does not carry any of the requested
375data services drivers must pass one or more empty packets. When an
376application fails to pass VBI data in time for output, the driver
377must output the last VPS and WSS packet again, and disable the output
378of Closed Caption and Teletext data, or output data which is ignored
379by Closed Caption and Teletext decoders.</para>
380
381 <para>A sliced VBI device may support <link
382linkend="rw">read/write</link> and/or streaming (<link
383linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
384pointer</link>) I/O. The latter bears the possibility of synchronizing
385video and VBI data by using buffer timestamps.</para>
386
387 </section>
388
389 <section>
390 <title>Sliced VBI Data in MPEG Streams</title>
391
392 <para>If a device can produce an MPEG output stream, it may be
393capable of providing <link
394linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
395services</link> as data embedded in the MPEG stream. Users or
396applications control this sliced VBI data insertion with the <link
397linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
398control.</para>
399
400 <para>If the driver does not provide the <link
401linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
402control, or only allows that control to be set to <link
403linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
404V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
405cannot embed sliced VBI data in the MPEG stream.</para>
406
407 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
408V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
409the device driver to capture nor cease capturing sliced VBI data. The
410control only indicates to embed sliced VBI data in the MPEG stream, if
411an application has negotiated sliced VBI service be captured.</para>
412
413 <para>It may also be the case that a device can embed sliced VBI
414data in only certain types of MPEG streams: for example in an MPEG-2
415PS but not an MPEG-2 TS. In this situation, if sliced VBI data
416insertion is requested, the sliced VBI data will be embedded in MPEG
417stream types when supported, and silently omitted from MPEG stream
418types where sliced VBI data insertion is not supported by the device.
419</para>
420
421 <para>The following subsections specify the format of the
422embedded sliced VBI data.</para>
423
424 <section>
425 <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title>
426 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
427V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
428format shall be interpreted by drivers as a control to cease
429embedding sliced VBI data in MPEG streams. Neither the device nor
430driver shall insert "empty" embedded sliced VBI data packets in the
431MPEG stream when this format is set. No MPEG stream data structures
432are specified for this format.</para>
433 </section>
434
435 <section>
436 <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title>
437 <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
438V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
439format, when supported, indicates to the driver to embed up to 36
440lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
441Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
442Program Pack</emphasis> in the MPEG stream.</para>
443
444 <para><emphasis>Historical context</emphasis>: This format
445specification originates from a custom, embedded, sliced VBI data
446format used by the <filename>ivtv</filename> driver. This format
447has already been informally specified in the kernel sources in the
448file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
449. The maximum size of the payload and other aspects of this format
450are driven by the CX23415 MPEG decoder's capabilities and limitations
451with respect to extracting, decoding, and displaying sliced VBI data
452embedded within an MPEG stream.</para>
453
454 <para>This format's use is <emphasis>not</emphasis> exclusive to
455the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
456exclusive to CX2341x devices, as the sliced VBI data packet insertion
457into the MPEG stream is implemented in driver software. At least the
458<filename>cx18</filename> driver provides sliced VBI data insertion
459into an MPEG-2 PS in this format as well.</para>
460
461 <para>The following definitions specify the payload of the
462MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
463sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt">
464<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set.
465(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header
466and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
467not detailed here. Please refer to the MPEG-2 specifications for
468details on those packet headers.)</para>
469
470 <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES
471</emphasis> packets that contain sliced VBI data is specified by
472&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable
473length, depending on the actual number of lines of sliced VBI data
474present in a video frame. The payload may be padded at the end with
475unspecified fill bytes to align the end of the payload to a 4-byte
476boundary. The payload shall never exceed 1552 bytes (2 fields with
47718 lines/field with 43 bytes of data/line and a 4 byte magic number).
478</para>
479
480 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv">
481 <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
482 </title>
483 <tgroup cols="4">
484 &cs-ustr;
485 <tbody valign="top">
486 <row>
487 <entry>__u8</entry>
488 <entry><structfield>magic</structfield>[4]</entry>
489 <entry></entry>
490 <entry>A "magic" constant from <xref
491 linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates
492this is a valid sliced VBI data payload and also indicates which
493member of the anonymous union, <structfield>itv0</structfield> or
494<structfield>ITV0</structfield>, to use for the payload data.</entry>
495 </row>
496 <row>
497 <entry>union</entry>
498 <entry>(anonymous)</entry>
499 </row>
500 <row>
501 <entry></entry>
502 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0">
503 <structname>v4l2_mpeg_vbi_itv0</structname></link>
504 </entry>
505 <entry><structfield>itv0</structfield></entry>
506 <entry>The primary form of the sliced VBI data payload
507that contains anywhere from 1 to 35 lines of sliced VBI data.
508Line masks are provided in this form of the payload indicating
509which VBI lines are provided.</entry>
510 </row>
511 <row>
512 <entry></entry>
513 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1">
514 <structname>v4l2_mpeg_vbi_ITV0</structname></link>
515 </entry>
516 <entry><structfield>ITV0</structfield></entry>
517 <entry>An alternate form of the sliced VBI data payload
518used when 36 lines of sliced VBI data are present. No line masks are
519provided in this form of the payload; all valid line mask bits are
520implcitly set.</entry>
521 </row>
522 </tbody>
523 </tgroup>
524 </table>
525
526 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic">
527 <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
528 <structfield>magic</structfield> field</title>
529 <tgroup cols="3">
530 &cs-def;
531 <thead>
532 <row>
533 <entry align="left">Defined Symbol</entry>
534 <entry align="left">Value</entry>
535 <entry align="left">Description</entry>
536 </row>
537 </thead>
538 <tbody valign="top">
539 <row>
540 <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant>
541 </entry>
542 <entry>"itv0"</entry>
543 <entry>Indicates the <structfield>itv0</structfield>
544member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry>
545 </row>
546 <row>
547 <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant>
548 </entry>
549 <entry>"ITV0"</entry>
550 <entry>Indicates the <structfield>ITV0</structfield>
551member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
552that 36 lines of sliced VBI data are present.</entry>
553 </row>
554 </tbody>
555 </tgroup>
556 </table>
557
558 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0">
559 <title>struct <structname>v4l2_mpeg_vbi_itv0</structname>
560 </title>
561 <tgroup cols="3">
562 &cs-str;
563 <tbody valign="top">
564 <row>
565 <entry>__le32</entry>
566 <entry><structfield>linemask</structfield>[2]</entry>
567 <entry><para>Bitmasks indicating the VBI service lines
568present. These <structfield>linemask</structfield> values are stored
569in little endian byte order in the MPEG stream. Some reference
570<structfield>linemask</structfield> bit positions with their
571corresponding VBI line number and video field are given below.
572b<subscript>0</subscript> indicates the least significant bit of a
573<structfield>linemask</structfield> value:<screen>
574<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field
575<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field
576<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field
577<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field
578<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field
579<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field
580<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry>
581 </row>
582 <row>
583 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
584 <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
585 </entry>
586 <entry><structfield>line</structfield>[35]</entry>
587 <entry>This is a variable length array that holds from 1
588to 35 lines of sliced VBI data. The sliced VBI data lines present
589correspond to the bits set in the <structfield>linemask</structfield>
590array, starting from b<subscript>0</subscript> of <structfield>
591linemask</structfield>[0] up through b<subscript>31</subscript> of
592<structfield>linemask</structfield>[0], and from b<subscript>0
593</subscript> of <structfield>linemask</structfield>[1] up through b
594<subscript>3</subscript> of <structfield>linemask</structfield>[1].
595<structfield>line</structfield>[0] corresponds to the first bit
596found set in the <structfield>linemask</structfield> array,
597<structfield>line</structfield>[1] corresponds to the second bit
598found set in the <structfield>linemask</structfield> array, etc.
599If no <structfield>linemask</structfield> array bits are set, then
600<structfield>line</structfield>[0] may contain one line of
601unspecified data that should be ignored by applications.</entry>
602 </row>
603 </tbody>
604 </tgroup>
605 </table>
606
607 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1">
608 <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname>
609 </title>
610 <tgroup cols="3">
611 &cs-str;
612 <tbody valign="top">
613 <row>
614 <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
615 <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
616 </entry>
617 <entry><structfield>line</structfield>[36]</entry>
618 <entry>A fixed length array of 36 lines of sliced VBI
619data. <structfield>line</structfield>[0] through <structfield>line
620</structfield>[17] correspond to lines 6 through 23 of the
621first field. <structfield>line</structfield>[18] through
622<structfield>line</structfield>[35] corresponds to lines 6
623through 23 of the second field.</entry>
624 </row>
625 </tbody>
626 </tgroup>
627 </table>
628
629 <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line">
630 <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
631 </title>
632 <tgroup cols="3">
633 &cs-str;
634 <tbody valign="top">
635 <row>
636 <entry>__u8</entry>
637 <entry><structfield>id</structfield></entry>
638 <entry>A line identifier value from
639<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates
640the type of sliced VBI data stored on this line.</entry>
641 </row>
642 <row>
643 <entry>__u8</entry>
644 <entry><structfield>data</structfield>[42]</entry>
645 <entry>The sliced VBI data for the line.</entry>
646 </row>
647 </tbody>
648 </tgroup>
649 </table>
650
651 <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants">
652 <title>Line Identifiers for struct <link
653 linkend="v4l2-mpeg-vbi-itv0-line"><structname>
654v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
655</structfield> field</title>
656 <tgroup cols="3">
657 &cs-def;
658 <thead>
659 <row>
660 <entry align="left">Defined Symbol</entry>
661 <entry align="left">Value</entry>
662 <entry align="left">Description</entry>
663 </row>
664 </thead>
665 <tbody valign="top">
666 <row>
667 <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant>
668 </entry>
669 <entry>1</entry>
670 <entry>Refer to <link linkend="vbi-services2">
671Sliced VBI services</link> for a description of the line payload.</entry>
672 </row>
673 <row>
674 <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant>
675 </entry>
676 <entry>4</entry>
677 <entry>Refer to <link linkend="vbi-services2">
678Sliced VBI services</link> for a description of the line payload.</entry>
679 </row>
680 <row>
681 <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant>
682 </entry>
683 <entry>5</entry>
684 <entry>Refer to <link linkend="vbi-services2">
685Sliced VBI services</link> for a description of the line payload.</entry>
686 </row>
687 <row>
688 <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant>
689 </entry>
690 <entry>7</entry>
691 <entry>Refer to <link linkend="vbi-services2">
692Sliced VBI services</link> for a description of the line payload.</entry>
693 </row>
694 </tbody>
695 </tgroup>
696 </table>
697
698 </section>
699 </section>
700
701
702<!--
703Local Variables:
704mode: sgml
705sgml-parent-document: "v4l2.sgml"
706indent-tabs-mode: nil
707End:
708 -->
diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml
new file mode 100644
index 000000000000..05c8fefcbcbe
--- /dev/null
+++ b/Documentation/DocBook/media/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 Negotiation 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/media/v4l/dev-teletext.xml b/Documentation/DocBook/media/v4l/dev-teletext.xml
new file mode 100644
index 000000000000..414b1cfff9f4
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/dev-teletext.xml
@@ -0,0 +1,37 @@
1 <title>Teletext Interface</title>
2
3 <para>This interface was aimed at devices receiving and demodulating
4Teletext data [<xref linkend="ets300706" />, <xref linkend="itu653" />], evaluating the
5Teletext packages and storing formatted pages in cache memory. Such
6devices are usually implemented as microcontrollers with serial
7interface (I<superscript>2</superscript>C) and could be found on old
8TV cards, dedicated Teletext decoding cards and home-brew devices
9connected to the PC parallel port.</para>
10
11 <para>The Teletext API was designed by Martin Buck. It was defined in
12the kernel header file <filename>linux/videotext.h</filename>, the
13specification is available from <ulink url="ftp://ftp.gwdg.de/pub/linux/misc/videotext/">
14ftp://ftp.gwdg.de/pub/linux/misc/videotext/</ulink>. (Videotext is the name of
15the German public television Teletext service.)</para>
16
17 <para>Eventually the Teletext API was integrated into the V4L API
18with character device file names <filename>/dev/vtx0</filename> to
19<filename>/dev/vtx31</filename>, device major number 81, minor numbers
20192 to 223.</para>
21
22 <para>However, teletext decoders were quickly replaced by more
23generic VBI demodulators and those dedicated teletext decoders no longer exist.
24For many years the vtx devices were still around, even though nobody used
25them. So the decision was made to finally remove support for the Teletext API in
26kernel 2.6.37.</para>
27
28 <para>Modern devices all use the <link linkend="raw-vbi">raw</link> or
29<link linkend="sliced">sliced</link> VBI API.</para>
30
31 <!--
32Local Variables:
33mode: sgml
34sgml-parent-document: "v4l2.sgml"
35indent-tabs-mode: nil
36End:
37 -->
diff --git a/Documentation/DocBook/media/v4l/driver.xml b/Documentation/DocBook/media/v4l/driver.xml
new file mode 100644
index 000000000000..1f7eea5c4ec3
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/driver.xml
@@ -0,0 +1,208 @@
1 <title>V4L2 Driver Programming</title>
2
3 <!-- This part defines the interface between the "videodev"
4 module and individual drivers. -->
5
6 <para>to do</para>
7<!--
8 <para>V4L2 is a two-layer driver system. The top layer is the "videodev"
9kernel module. When videodev initializes it registers as character device
10with major number 81, and it registers a set of file operations. All V4L2
11drivers are really clients of videodev, which calls V4L2 drivers through
12driver method functions. V4L2 drivers are also written as kernel modules.
13After probing the hardware they register one or more devices with
14videodev.</para>
15
16 <section id="driver-modules">
17 <title>Driver Modules</title>
18
19 <para>V4L2 driver modules must have an initialization function which is
20called after the module was loaded into kernel, an exit function whis is
21called before the module is removed. When the driver is compiled into the
22kernel these functions called at system boot and shutdown time.</para>
23
24 <informalexample>
25 <programlisting>
26#include &lt;linux/module.h&gt;
27
28/* Export information about this module. For details and other useful
29 macros see <filename>linux/module.h</filename>. */
30MODULE_DESCRIPTION("my - driver for my hardware");
31MODULE_AUTHOR("Your name here");
32MODULE_LICENSE("GPL");
33
34static void
35my_module_exit (void)
36{
37 /* Free all resources allocated by my_module_init(). */
38}
39
40static int
41my_module_init (void)
42{
43 /* Bind the driver to the supported hardware, see
44 <link linkend="driver-pci"> and
45 <link linkend="driver-usb"> for examples. */
46
47 return 0; /* a negative value on error, 0 on success. */
48}
49
50/* Export module functions. */
51module_init (my_module_init);
52module_exit (my_module_exit);
53</programlisting>
54 </informalexample>
55
56 <para>Users can add parameters when kernel modules are inserted:</para>
57
58 <informalexample>
59 <programlisting>
60include &lt;linux/moduleparam.h&gt;
61
62static int my_option = 123;
63static int my_option_array[47];
64
65/* Export the symbol, an int, with access permissions 0664.
66 See <filename>linux/moduleparam.h</filename> for other types. */
67module_param (my_option, int, 0644);
68module_param_array (my_option_array, int, NULL, 0644);
69
70MODULE_PARM_DESC (my_option, "Does magic things, default 123");
71</programlisting>
72 </informalexample>
73
74 <para>One parameter should be supported by all V4L2 drivers, the minor
75number of the device it will register. Purpose is to predictably link V4L2
76drivers to device nodes if more than one video device is installed. Use the
77name of the device node followed by a "_nr" suffix, for example "video_nr"
78for <filename>/dev/video</filename>.</para>
79
80 <informalexample>
81 <programlisting>
82/* Minor number of the device, -1 to allocate the first unused. */
83static int video_nr = -1;
84
85module_param (video_nr, int, 0444);
86</programlisting>
87 </informalexample>
88 </section>
89
90 <section id="driver-pci">
91 <title>PCI Devices</title>
92
93 <para>PCI devices are initialized like this:</para>
94
95 <informalexample>
96 <programlisting>
97typedef struct {
98 /* State of one physical device. */
99} my_device;
100
101static int
102my_resume (struct pci_dev * pci_dev)
103{
104 /* Restore the suspended device to working state. */
105}
106
107static int
108my_suspend (struct pci_dev * pci_dev,
109 pm_message_t state)
110{
111 /* This function is called before the system goes to sleep.
112 Stop all DMAs and disable interrupts, then put the device
113 into a low power state. For details see the kernel
114 sources under <filename>Documentation/power</filename>. */
115
116 return 0; /* a negative value on error, 0 on success. */
117}
118
119static void __devexit
120my_remove (struct pci_dev * pci_dev)
121{
122 my_device *my = pci_get_drvdata (pci_dev);
123
124 /* Describe me. */
125}
126
127static int __devinit
128my_probe (struct pci_dev * pci_dev,
129 const struct pci_device_id * pci_id)
130{
131 my_device *my;
132
133 /* Describe me. */
134
135 /* You can allocate per-device data here and store a pointer
136 to it in the pci_dev structure. */
137 my = ...;
138 pci_set_drvdata (pci_dev, my);
139
140 return 0; /* a negative value on error, 0 on success. */
141}
142
143/* A list of supported PCI devices. */
144static struct pci_device_id
145my_pci_device_ids [] = {
146 { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
147 PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0 },
148 { 0 } /* end of list */
149};
150
151/* Load our module if supported PCI devices are installed. */
152MODULE_DEVICE_TABLE (pci, my_pci_device_ids);
153
154static struct pci_driver
155my_pci_driver = {
156 .name = "my",
157 .id_table = my_pci_device_ids,
158
159 .probe = my_probe,
160 .remove = __devexit_p (my_remove),
161
162 /* Power management functions. */
163 .suspend = my_suspend,
164 .resume = my_resume,
165};
166
167static void
168my_module_exit (void)
169{
170 pci_unregister_driver (&my_pci_driver);
171}
172
173static int
174my_module_init (void)
175{
176 return pci_register_driver (&my_pci_driver);
177}
178</programlisting>
179 </informalexample>
180 </section>
181
182 <section id="driver-usb">
183 <title>USB Devices</title>
184 <para>to do</para>
185 </section>
186 <section id="driver-registering">
187 <title>Registering V4L2 Drivers</title>
188
189 <para>After a V4L2 driver probed the hardware it registers one or more
190devices with the videodev module.</para>
191 </section>
192 <section id="driver-file-ops">
193 <title>File Operations</title>
194 <para>to do</para>
195 </section>
196 <section id="driver-internal-api">
197 <title>Internal API</title>
198 <para>to do</para>
199 </section>
200-->
201
202<!--
203Local Variables:
204mode: sgml
205sgml-parent-document: "v4l2.sgml"
206indent-tabs-mode: nil
207End:
208-->
diff --git a/Documentation/DocBook/media/v4l/fdl-appendix.xml b/Documentation/DocBook/media/v4l/fdl-appendix.xml
new file mode 100644
index 000000000000..ae22394ba997
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/fdl-appendix.xml
@@ -0,0 +1,671 @@
1<!--
2 The GNU Free Documentation License 1.1 in DocBook
3 Markup by Eric Baudais <baudais@okstate.edu>
4 Maintained by the GNOME Documentation Project
5 http://live.gnome.org/DocumentationProject
6 Version: 1.0.1
7 Last Modified: Nov 16, 2000
8-->
9
10<appendix id="fdl">
11 <appendixinfo>
12 <releaseinfo>
13 Version 1.1, March 2000
14 </releaseinfo>
15 <copyright>
16 <year>2000</year><holder>Free Software Foundation, Inc.</holder>
17 </copyright>
18 <legalnotice id="fdl-legalnotice">
19 <para>
20 <address>Free Software Foundation, Inc. <street>59 Temple Place,
21 Suite 330</street>, <city>Boston</city>, <state>MA</state>
22 <postcode>02111-1307</postcode> <country>USA</country></address>
23 Everyone is permitted to copy and distribute verbatim copies of this
24 license document, but changing it is not allowed.
25 </para>
26 </legalnotice>
27 </appendixinfo>
28 <title>GNU Free Documentation License</title>
29
30 <sect1 id="fdl-preamble">
31 <title>0. PREAMBLE</title>
32 <para>
33 The purpose of this License is to make a manual, textbook, or
34 other written document <quote>free</quote> in the sense of
35 freedom: to assure everyone the effective freedom to copy and
36 redistribute it, with or without modifying it, either
37 commercially or noncommercially. Secondarily, this License
38 preserves for the author and publisher a way to get credit for
39 their work, while not being considered responsible for
40 modifications made by others.
41 </para>
42
43 <para>
44 This License is a kind of <quote>copyleft</quote>, which means
45 that derivative works of the document must themselves be free in
46 the same sense. It complements the GNU General Public License,
47 which is a copyleft license designed for free software.
48 </para>
49
50 <para>
51 We have designed this License in order to use it for manuals for
52 free software, because free software needs free documentation: a
53 free program should come with manuals providing the same
54 freedoms that the software does. But this License is not limited
55 to software manuals; it can be used for any textual work,
56 regardless of subject matter or whether it is published as a
57 printed book. We recommend this License principally for works
58 whose purpose is instruction or reference.
59 </para>
60 </sect1>
61 <sect1 id="fdl-section1">
62 <title>1. APPLICABILITY AND DEFINITIONS</title>
63 <para id="fdl-document">
64 This License applies to any manual or other work that contains a
65 notice placed by the copyright holder saying it can be
66 distributed under the terms of this License. The
67 <quote>Document</quote>, below, refers to any such manual or
68 work. Any member of the public is a licensee, and is addressed
69 as <quote>you</quote>.
70 </para>
71
72 <para id="fdl-modified">
73 A <quote>Modified Version</quote> of the Document means any work
74 containing the Document or a portion of it, either copied
75 verbatim, or with modifications and/or translated into another
76 language.
77 </para>
78
79 <para id="fdl-secondary">
80 A <quote>Secondary Section</quote> is a named appendix or a
81 front-matter section of the <link
82 linkend="fdl-document">Document</link> that deals exclusively
83 with the relationship of the publishers or authors of the
84 Document to the Document's overall subject (or to related
85 matters) and contains nothing that could fall directly within
86 that overall subject. (For example, if the Document is in part a
87 textbook of mathematics, a Secondary Section may not explain any
88 mathematics.) The relationship could be a matter of historical
89 connection with the subject or with related matters, or of
90 legal, commercial, philosophical, ethical or political position
91 regarding them.
92 </para>
93
94 <para id="fdl-invariant">
95 The <quote>Invariant Sections</quote> are certain <link
96 linkend="fdl-secondary"> Secondary Sections</link> whose titles
97 are designated, as being those of Invariant Sections, in the
98 notice that says that the <link
99 linkend="fdl-document">Document</link> is released under this
100 License.
101 </para>
102
103 <para id="fdl-cover-texts">
104 The <quote>Cover Texts</quote> are certain short passages of
105 text that are listed, as Front-Cover Texts or Back-Cover Texts,
106 in the notice that says that the <link
107 linkend="fdl-document">Document</link> is released under this
108 License.
109 </para>
110
111 <para id="fdl-transparent">
112 A <quote>Transparent</quote> copy of the <link
113 linkend="fdl-document"> Document</link> means a machine-readable
114 copy, represented in a format whose specification is available
115 to the general public, whose contents can be viewed and edited
116 directly and straightforwardly with generic text editors or (for
117 images composed of pixels) generic paint programs or (for
118 drawings) some widely available drawing editor, and that is
119 suitable for input to text formatters or for automatic
120 translation to a variety of formats suitable for input to text
121 formatters. A copy made in an otherwise Transparent file format
122 whose markup has been designed to thwart or discourage
123 subsequent modification by readers is not Transparent. A copy
124 that is not <quote>Transparent</quote> is called
125 <quote>Opaque</quote>.
126 </para>
127
128 <para>
129 Examples of suitable formats for Transparent copies include
130 plain ASCII without markup, Texinfo input format, LaTeX input
131 format, SGML or XML using a publicly available DTD, and
132 standard-conforming simple HTML designed for human
133 modification. Opaque formats include PostScript, PDF,
134 proprietary formats that can be read and edited only by
135 proprietary word processors, SGML or XML for which the DTD
136 and/or processing tools are not generally available, and the
137 machine-generated HTML produced by some word processors for
138 output purposes only.
139 </para>
140
141 <para id="fdl-title-page">
142 The <quote>Title Page</quote> means, for a printed book, the
143 title page itself, plus such following pages as are needed to
144 hold, legibly, the material this License requires to appear in
145 the title page. For works in formats which do not have any title
146 page as such, <quote>Title Page</quote> means the text near the
147 most prominent appearance of the work's title, preceding the
148 beginning of the body of the text.
149 </para>
150 </sect1>
151
152 <sect1 id="fdl-section2">
153 <title>2. VERBATIM COPYING</title>
154 <para>
155 You may copy and distribute the <link
156 linkend="fdl-document">Document</link> in any medium, either
157 commercially or noncommercially, provided that this License, the
158 copyright notices, and the license notice saying this License
159 applies to the Document are reproduced in all copies, and that
160 you add no other conditions whatsoever to those of this
161 License. You may not use technical measures to obstruct or
162 control the reading or further copying of the copies you make or
163 distribute. However, you may accept compensation in exchange for
164 copies. If you distribute a large enough number of copies you
165 must also follow the conditions in <link
166 linkend="fdl-section3">section 3</link>.
167 </para>
168
169 <para>
170 You may also lend copies, under the same conditions stated
171 above, and you may publicly display copies.
172 </para>
173 </sect1>
174
175 <sect1 id="fdl-section3">
176 <title>3. COPYING IN QUANTITY</title>
177 <para>
178 If you publish printed copies of the <link
179 linkend="fdl-document">Document</link> numbering more than 100,
180 and the Document's license notice requires <link
181 linkend="fdl-cover-texts">Cover Texts</link>, you must enclose
182 the copies in covers that carry, clearly and legibly, all these
183 Cover Texts: Front-Cover Texts on the front cover, and
184 Back-Cover Texts on the back cover. Both covers must also
185 clearly and legibly identify you as the publisher of these
186 copies. The front cover must present the full title with all
187 words of the title equally prominent and visible. You may add
188 other material on the covers in addition. Copying with changes
189 limited to the covers, as long as they preserve the title of the
190 <link linkend="fdl-document">Document</link> and satisfy these
191 conditions, can be treated as verbatim copying in other
192 respects.
193 </para>
194
195 <para>
196 If the required texts for either cover are too voluminous to fit
197 legibly, you should put the first ones listed (as many as fit
198 reasonably) on the actual cover, and continue the rest onto
199 adjacent pages.
200 </para>
201
202 <para>
203 If you publish or distribute <link
204 linkend="fdl-transparent">Opaque</link> copies of the <link
205 linkend="fdl-document">Document</link> numbering more than 100,
206 you must either include a machine-readable <link
207 linkend="fdl-transparent">Transparent</link> copy along with
208 each Opaque copy, or state in or with each Opaque copy a
209 publicly-accessible computer-network location containing a
210 complete Transparent copy of the Document, free of added
211 material, which the general network-using public has access to
212 download anonymously at no charge using public-standard network
213 protocols. If you use the latter option, you must take
214 reasonably prudent steps, when you begin distribution of Opaque
215 copies in quantity, to ensure that this Transparent copy will
216 remain thus accessible at the stated location until at least one
217 year after the last time you distribute an Opaque copy (directly
218 or through your agents or retailers) of that edition to the
219 public.
220 </para>
221
222 <para>
223 It is requested, but not required, that you contact the authors
224 of the <link linkend="fdl-document">Document</link> well before
225 redistributing any large number of copies, to give them a chance
226 to provide you with an updated version of the Document.
227 </para>
228 </sect1>
229
230 <sect1 id="fdl-section4">
231 <title>4. MODIFICATIONS</title>
232 <para>
233 You may copy and distribute a <link
234 linkend="fdl-modified">Modified Version</link> of the <link
235 linkend="fdl-document">Document</link> under the conditions of
236 sections <link linkend="fdl-section2">2</link> and <link
237 linkend="fdl-section3">3</link> above, provided that you release
238 the Modified Version under precisely this License, with the
239 Modified Version filling the role of the Document, thus
240 licensing distribution and modification of the Modified Version
241 to whoever possesses a copy of it. In addition, you must do
242 these things in the Modified Version:
243 </para>
244
245 <itemizedlist mark="opencircle">
246 <listitem>
247 <formalpara>
248 <title>A</title>
249 <para>
250 Use in the <link linkend="fdl-title-page">Title
251 Page</link> (and on the covers, if any) a title distinct
252 from that of the <link
253 linkend="fdl-document">Document</link>, and from those of
254 previous versions (which should, if there were any, be
255 listed in the History section of the Document). You may
256 use the same title as a previous version if the original
257 publisher of that version gives permission.
258 </para>
259 </formalpara>
260 </listitem>
261
262 <listitem>
263 <formalpara>
264 <title>B</title>
265 <para>
266 List on the <link linkend="fdl-title-page">Title
267 Page</link>, as authors, one or more persons or entities
268 responsible for authorship of the modifications in the
269 <link linkend="fdl-modified">Modified Version</link>,
270 together with at least five of the principal authors of
271 the <link linkend="fdl-document">Document</link> (all of
272 its principal authors, if it has less than five).
273 </para>
274 </formalpara>
275 </listitem>
276
277 <listitem>
278 <formalpara>
279 <title>C</title>
280 <para>
281 State on the <link linkend="fdl-title-page">Title
282 Page</link> the name of the publisher of the <link
283 linkend="fdl-modified">Modified Version</link>, as the
284 publisher.
285 </para>
286 </formalpara>
287 </listitem>
288
289 <listitem>
290 <formalpara>
291 <title>D</title>
292 <para>
293 Preserve all the copyright notices of the <link
294 linkend="fdl-document">Document</link>.
295 </para>
296 </formalpara>
297 </listitem>
298
299 <listitem>
300 <formalpara>
301 <title>E</title>
302 <para>
303 Add an appropriate copyright notice for your modifications
304 adjacent to the other copyright notices.
305 </para>
306 </formalpara>
307 </listitem>
308
309 <listitem>
310 <formalpara>
311 <title>F</title>
312 <para>
313 Include, immediately after the copyright notices, a
314 license notice giving the public permission to use the
315 <link linkend="fdl-modified">Modified Version</link> under
316 the terms of this License, in the form shown in the
317 Addendum below.
318 </para>
319 </formalpara>
320 </listitem>
321
322 <listitem>
323 <formalpara>
324 <title>G</title>
325 <para>
326 Preserve in that license notice the full lists of <link
327 linkend="fdl-invariant"> Invariant Sections</link> and
328 required <link linkend="fdl-cover-texts">Cover
329 Texts</link> given in the <link
330 linkend="fdl-document">Document's</link> license notice.
331 </para>
332 </formalpara>
333 </listitem>
334
335 <listitem>
336 <formalpara>
337 <title>H</title>
338 <para>
339 Include an unaltered copy of this License.
340 </para>
341 </formalpara>
342 </listitem>
343
344 <listitem>
345 <formalpara>
346 <title>I</title>
347 <para>
348 Preserve the section entitled <quote>History</quote>, and
349 its title, and add to it an item stating at least the
350 title, year, new authors, and publisher of the <link
351 linkend="fdl-modified">Modified Version </link>as given on
352 the <link linkend="fdl-title-page">Title Page</link>. If
353 there is no section entitled <quote>History</quote> in the
354 <link linkend="fdl-document">Document</link>, create one
355 stating the title, year, authors, and publisher of the
356 Document as given on its Title Page, then add an item
357 describing the Modified Version as stated in the previous
358 sentence.
359 </para>
360 </formalpara>
361 </listitem>
362
363 <listitem>
364 <formalpara>
365 <title>J</title>
366 <para>
367 Preserve the network location, if any, given in the <link
368 linkend="fdl-document">Document</link> for public access
369 to a <link linkend="fdl-transparent">Transparent</link>
370 copy of the Document, and likewise the network locations
371 given in the Document for previous versions it was based
372 on. These may be placed in the <quote>History</quote>
373 section. You may omit a network location for a work that
374 was published at least four years before the Document
375 itself, or if the original publisher of the version it
376 refers to gives permission.
377 </para>
378 </formalpara>
379 </listitem>
380
381 <listitem>
382 <formalpara>
383 <title>K</title>
384 <para>
385 In any section entitled <quote>Acknowledgements</quote> or
386 <quote>Dedications</quote>, preserve the section's title,
387 and preserve in the section all the substance and tone of
388 each of the contributor acknowledgements and/or
389 dedications given therein.
390 </para>
391 </formalpara>
392 </listitem>
393
394 <listitem>
395 <formalpara>
396 <title>L</title>
397 <para>
398 Preserve all the <link linkend="fdl-invariant">Invariant
399 Sections</link> of the <link
400 linkend="fdl-document">Document</link>, unaltered in their
401 text and in their titles. Section numbers or the
402 equivalent are not considered part of the section titles.
403 </para>
404 </formalpara>
405 </listitem>
406
407 <listitem>
408 <formalpara>
409 <title>M</title>
410 <para>
411 Delete any section entitled
412 <quote>Endorsements</quote>. Such a section may not be
413 included in the <link linkend="fdl-modified">Modified
414 Version</link>.
415 </para>
416 </formalpara>
417 </listitem>
418
419 <listitem>
420 <formalpara>
421 <title>N</title>
422 <para>
423 Do not retitle any existing section as
424 <quote>Endorsements</quote> or to conflict in title with
425 any <link linkend="fdl-invariant">Invariant
426 Section</link>.
427 </para>
428 </formalpara>
429 </listitem>
430 </itemizedlist>
431
432 <para>
433 If the <link linkend="fdl-modified">Modified Version</link>
434 includes new front-matter sections or appendices that qualify as
435 <link linkend="fdl-secondary">Secondary Sections</link> and
436 contain no material copied from the Document, you may at your
437 option designate some or all of these sections as invariant. To
438 do this, add their titles to the list of <link
439 linkend="fdl-invariant">Invariant Sections</link> in the
440 Modified Version's license notice. These titles must be
441 distinct from any other section titles.
442 </para>
443
444 <para>
445 You may add a section entitled <quote>Endorsements</quote>,
446 provided it contains nothing but endorsements of your <link
447 linkend="fdl-modified">Modified Version</link> by various
448 parties--for example, statements of peer review or that the text
449 has been approved by an organization as the authoritative
450 definition of a standard.
451 </para>
452
453 <para>
454 You may add a passage of up to five words as a <link
455 linkend="fdl-cover-texts">Front-Cover Text</link>, and a passage
456 of up to 25 words as a <link
457 linkend="fdl-cover-texts">Back-Cover Text</link>, to the end of
458 the list of <link linkend="fdl-cover-texts">Cover Texts</link>
459 in the <link linkend="fdl-modified">Modified Version</link>.
460 Only one passage of Front-Cover Text and one of Back-Cover Text
461 may be added by (or through arrangements made by) any one
462 entity. If the <link linkend="fdl-document">Document</link>
463 already includes a cover text for the same cover, previously
464 added by you or by arrangement made by the same entity you are
465 acting on behalf of, you may not add another; but you may
466 replace the old one, on explicit permission from the previous
467 publisher that added the old one.
468 </para>
469
470 <para>
471 The author(s) and publisher(s) of the <link
472 linkend="fdl-document">Document</link> do not by this License
473 give permission to use their names for publicity for or to
474 assert or imply endorsement of any <link
475 linkend="fdl-modified">Modified Version </link>.
476 </para>
477 </sect1>
478
479 <sect1 id="fdl-section5">
480 <title>5. COMBINING DOCUMENTS</title>
481 <para>
482 You may combine the <link linkend="fdl-document">Document</link>
483 with other documents released under this License, under the
484 terms defined in <link linkend="fdl-section4">section 4</link>
485 above for modified versions, provided that you include in the
486 combination all of the <link linkend="fdl-invariant">Invariant
487 Sections</link> of all of the original documents, unmodified,
488 and list them all as Invariant Sections of your combined work in
489 its license notice.
490 </para>
491
492 <para>
493 The combined work need only contain one copy of this License,
494 and multiple identical <link linkend="fdl-invariant">Invariant
495 Sections</link> may be replaced with a single copy. If there are
496 multiple Invariant Sections with the same name but different
497 contents, make the title of each such section unique by adding
498 at the end of it, in parentheses, the name of the original
499 author or publisher of that section if known, or else a unique
500 number. Make the same adjustment to the section titles in the
501 list of Invariant Sections in the license notice of the combined
502 work.
503 </para>
504
505 <para>
506 In the combination, you must combine any sections entitled
507 <quote>History</quote> in the various original documents,
508 forming one section entitled <quote>History</quote>; likewise
509 combine any sections entitled <quote>Acknowledgements</quote>,
510 and any sections entitled <quote>Dedications</quote>. You must
511 delete all sections entitled <quote>Endorsements.</quote>
512 </para>
513 </sect1>
514
515 <sect1 id="fdl-section6">
516 <title>6. COLLECTIONS OF DOCUMENTS</title>
517 <para>
518 You may make a collection consisting of the <link
519 linkend="fdl-document">Document</link> and other documents
520 released under this License, and replace the individual copies
521 of this License in the various documents with a single copy that
522 is included in the collection, provided that you follow the
523 rules of this License for verbatim copying of each of the
524 documents in all other respects.
525 </para>
526
527 <para>
528 You may extract a single document from such a collection, and
529 dispbibute it individually under this License, provided you
530 insert a copy of this License into the extracted document, and
531 follow this License in all other respects regarding verbatim
532 copying of that document.
533 </para>
534 </sect1>
535
536 <sect1 id="fdl-section7">
537 <title>7. AGGREGATION WITH INDEPENDENT WORKS</title>
538 <para>
539 A compilation of the <link
540 linkend="fdl-document">Document</link> or its derivatives with
541 other separate and independent documents or works, in or on a
542 volume of a storage or distribution medium, does not as a whole
543 count as a <link linkend="fdl-modified">Modified Version</link>
544 of the Document, provided no compilation copyright is claimed
545 for the compilation. Such a compilation is called an
546 <quote>aggregate</quote>, and this License does not apply to the
547 other self-contained works thus compiled with the Document , on
548 account of their being thus compiled, if they are not themselves
549 derivative works of the Document. If the <link
550 linkend="fdl-cover-texts">Cover Text</link> requirement of <link
551 linkend="fdl-section3">section 3</link> is applicable to these
552 copies of the Document, then if the Document is less than one
553 quarter of the entire aggregate, the Document's Cover Texts may
554 be placed on covers that surround only the Document within the
555 aggregate. Otherwise they must appear on covers around the whole
556 aggregate.
557 </para>
558 </sect1>
559
560 <sect1 id="fdl-section8">
561 <title>8. TRANSLATION</title>
562 <para>
563 Translation is considered a kind of modification, so you may
564 distribute translations of the <link
565 linkend="fdl-document">Document</link> under the terms of <link
566 linkend="fdl-section4">section 4</link>. Replacing <link
567 linkend="fdl-invariant"> Invariant Sections</link> with
568 translations requires special permission from their copyright
569 holders, but you may include translations of some or all
570 Invariant Sections in addition to the original versions of these
571 Invariant Sections. You may include a translation of this
572 License provided that you also include the original English
573 version of this License. In case of a disagreement between the
574 translation and the original English version of this License,
575 the original English version will prevail.
576 </para>
577 </sect1>
578
579 <sect1 id="fdl-section9">
580 <title>9. TERMINATION</title>
581 <para>
582 You may not copy, modify, sublicense, or distribute the <link
583 linkend="fdl-document">Document</link> except as expressly
584 provided for under this License. Any other attempt to copy,
585 modify, sublicense or distribute the Document is void, and will
586 automatically terminate your rights under this License. However,
587 parties who have received copies, or rights, from you under this
588 License will not have their licenses terminated so long as such
589 parties remain in full compliance.
590 </para>
591 </sect1>
592
593 <sect1 id="fdl-section10">
594 <title>10. FUTURE REVISIONS OF THIS LICENSE</title>
595 <para>
596 The <ulink type="http"
597 url="http://www.gnu.org/fsf/fsf.html">Free Software
598 Foundation</ulink> may publish new, revised versions of the GNU
599 Free Documentation License from time to time. Such new versions
600 will be similar in spirit to the present version, but may differ
601 in detail to address new problems or concerns. See <ulink
602 type="http"
603 url="http://www.gnu.org/copyleft">http://www.gnu.org/copyleft/</ulink>.
604 </para>
605
606 <para>
607 Each version of the License is given a distinguishing version
608 number. If the <link linkend="fdl-document">Document</link>
609 specifies that a particular numbered version of this License
610 <quote>or any later version</quote> applies to it, you have the
611 option of following the terms and conditions either of that
612 specified version or of any later version that has been
613 published (not as a draft) by the Free Software Foundation. If
614 the Document does not specify a version number of this License,
615 you may choose any version ever published (not as a draft) by
616 the Free Software Foundation.
617 </para>
618 </sect1>
619
620 <sect1 id="fdl-using">
621 <title>Addendum</title>
622 <para>
623 To use this License in a document you have written, include a copy of
624 the License in the document and put the following copyright and
625 license notices just after the title page:
626 </para>
627
628 <blockquote>
629 <para>
630 Copyright &copy; YEAR YOUR NAME.
631 </para>
632 <para>
633 Permission is granted to copy, distribute and/or modify this
634 document under the terms of the GNU Free Documentation
635 License, Version 1.1 or any later version published by the
636 Free Software Foundation; with the <link
637 linkend="fdl-invariant">Invariant Sections</link> being LIST
638 THEIR TITLES, with the <link
639 linkend="fdl-cover-texts">Front-Cover Texts</link> being LIST,
640 and with the <link linkend="fdl-cover-texts">Back-Cover
641 Texts</link> being LIST. A copy of the license is included in
642 the section entitled <quote>GNU Free Documentation
643 License</quote>.
644 </para>
645 </blockquote>
646
647 <para>
648 If you have no <link linkend="fdl-invariant">Invariant
649 Sections</link>, write <quote>with no Invariant Sections</quote>
650 instead of saying which ones are invariant. If you have no
651 <link linkend="fdl-cover-texts">Front-Cover Texts</link>, write
652 <quote>no Front-Cover Texts</quote> instead of
653 <quote>Front-Cover Texts being LIST</quote>; likewise for <link
654 linkend="fdl-cover-texts">Back-Cover Texts</link>.
655 </para>
656
657 <para>
658 If your document contains nontrivial examples of program code,
659 we recommend releasing these examples in parallel under your
660 choice of free software license, such as the <ulink type="http"
661 url="http://www.gnu.org/copyleft/gpl.html"> GNU General Public
662 License</ulink>, to permit their use in free software.
663 </para>
664 </sect1>
665</appendix>
666
667
668
669
670
671
diff --git a/Documentation/DocBook/media/v4l/fieldseq_bt.gif b/Documentation/DocBook/media/v4l/fieldseq_bt.gif
new file mode 100644
index 000000000000..60e8569a76c9
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/fieldseq_bt.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/fieldseq_bt.pdf b/Documentation/DocBook/media/v4l/fieldseq_bt.pdf
new file mode 100644
index 000000000000..26598b23f80d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/fieldseq_bt.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/fieldseq_tb.gif b/Documentation/DocBook/media/v4l/fieldseq_tb.gif
new file mode 100644
index 000000000000..718492f1cfc7
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/fieldseq_tb.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/fieldseq_tb.pdf b/Documentation/DocBook/media/v4l/fieldseq_tb.pdf
new file mode 100644
index 000000000000..4965b22ddb3a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/fieldseq_tb.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/func-close.xml b/Documentation/DocBook/media/v4l/func-close.xml
new file mode 100644
index 000000000000..dfb41cbbbec3
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-close.xml
@@ -0,0 +1,70 @@
1<refentry id="func-close">
2 <refmeta>
3 <refentrytitle>V4L2 close()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-close</refname>
9 <refpurpose>Close a V4L2 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 device. Any I/O in progress is terminated and
39resources associated with the file descriptor are freed. However data
40format parameters, current input or output, control values or other
41properties remain unchanged.</para>
42 </refsect1>
43
44 <refsect1>
45 <title>Return Value</title>
46
47 <para>The function returns <returnvalue>0</returnvalue> on
48success, <returnvalue>-1</returnvalue> on failure and the
49<varname>errno</varname> is set appropriately. Possible error
50codes:</para>
51
52 <variablelist>
53 <varlistentry>
54 <term><errorcode>EBADF</errorcode></term>
55 <listitem>
56 <para><parameter>fd</parameter> is not a valid open file
57descriptor.</para>
58 </listitem>
59 </varlistentry>
60 </variablelist>
61 </refsect1>
62</refentry>
63
64<!--
65Local Variables:
66mode: sgml
67sgml-parent-document: "v4l2.sgml"
68indent-tabs-mode: nil
69End:
70-->
diff --git a/Documentation/DocBook/media/v4l/func-ioctl.xml b/Documentation/DocBook/media/v4l/func-ioctl.xml
new file mode 100644
index 000000000000..b60fd37a6295
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-ioctl.xml
@@ -0,0 +1,145 @@
1<refentry id="func-ioctl">
2 <refmeta>
3 <refentrytitle>V4L2 ioctl()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-ioctl</refname>
9 <refpurpose>Program a V4L2 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>V4L2 ioctl request code as defined in the <filename>videodev2.h</filename> header file, for example
38VIDIOC_QUERYCAP.</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para>Pointer to a function parameter, usually a structure.</para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <para>The <function>ioctl()</function> function is used to program
54V4L2 devices. The argument <parameter>fd</parameter> must be an open
55file descriptor. An ioctl <parameter>request</parameter> has encoded
56in it whether the argument is an input, output or read/write
57parameter, and the size of the argument <parameter>argp</parameter> in
58bytes. Macros and defines specifying V4L2 ioctl requests are located
59in the <filename>videodev2.h</filename> header file.
60Applications should use their own copy, not include the version in the
61kernel sources on the system they compile on. All V4L2 ioctl requests,
62their respective function and parameters are specified in <xref
63 linkend="user-func" />.</para>
64 </refsect1>
65
66 <refsect1>
67 <title>Return Value</title>
68
69 <para>On success the <function>ioctl()</function> function returns
70<returnvalue>0</returnvalue> and does not reset the
71<varname>errno</varname> variable. On failure
72<returnvalue>-1</returnvalue> is returned, when the ioctl takes an
73output or read/write parameter it remains unmodified, and the
74<varname>errno</varname> variable is set appropriately. See below for
75possible error codes. Generic errors like <errorcode>EBADF</errorcode>
76or <errorcode>EFAULT</errorcode> are not listed in the sections
77discussing individual ioctl requests.</para>
78 <para>Note ioctls may return undefined error codes. Since errors
79may have side effects such as a driver reset applications should
80abort on unexpected errors.</para>
81
82 <variablelist>
83 <varlistentry>
84 <term><errorcode>EBADF</errorcode></term>
85 <listitem>
86 <para><parameter>fd</parameter> is not a valid open file
87descriptor.</para>
88 </listitem>
89 </varlistentry>
90 <varlistentry>
91 <term><errorcode>EBUSY</errorcode></term>
92 <listitem>
93 <para>The property cannot be changed right now. Typically
94this error code is returned when I/O is in progress or the driver
95supports multiple opens and another process locked the property.</para>
96 </listitem>
97 </varlistentry>
98 <varlistentry>
99 <term><errorcode>EFAULT</errorcode></term>
100 <listitem>
101 <para><parameter>argp</parameter> references an inaccessible
102memory area.</para>
103 </listitem>
104 </varlistentry>
105 <varlistentry>
106 <term><errorcode>ENOTTY</errorcode></term>
107 <listitem>
108 <para><parameter>fd</parameter> is not associated with a
109character special device.</para>
110 </listitem>
111 </varlistentry>
112 <varlistentry>
113 <term><errorcode>EINVAL</errorcode></term>
114 <listitem>
115 <para>The <parameter>request</parameter> or the data pointed
116to by <parameter>argp</parameter> is not valid. This is a very common
117error code, see the individual ioctl requests listed in <xref
118 linkend="user-func" /> for actual causes.</para>
119 </listitem>
120 </varlistentry>
121 <varlistentry>
122 <term><errorcode>ENOMEM</errorcode></term>
123 <listitem>
124 <para>Not enough physical or virtual memory was available to
125complete the request.</para>
126 </listitem>
127 </varlistentry>
128 <varlistentry>
129 <term><errorcode>ERANGE</errorcode></term>
130 <listitem>
131 <para>The application attempted to set a control with the
132&VIDIOC-S-CTRL; ioctl to a value which is out of bounds.</para>
133 </listitem>
134 </varlistentry>
135 </variablelist>
136 </refsect1>
137</refentry>
138
139<!--
140Local Variables:
141mode: sgml
142sgml-parent-document: "v4l2.sgml"
143indent-tabs-mode: nil
144End:
145-->
diff --git a/Documentation/DocBook/media/v4l/func-mmap.xml b/Documentation/DocBook/media/v4l/func-mmap.xml
new file mode 100644
index 000000000000..786732b64bbd
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-mmap.xml
@@ -0,0 +1,191 @@
1<refentry id="func-mmap">
2 <refmeta>
3 <refentrytitle>V4L2 mmap()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-mmap</refname>
9 <refpurpose>Map device memory into application address space</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>
15#include &lt;unistd.h&gt;
16#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
17 <funcprototype>
18 <funcdef>void *<function>mmap</function></funcdef>
19 <paramdef>void *<parameter>start</parameter></paramdef>
20 <paramdef>size_t <parameter>length</parameter></paramdef>
21 <paramdef>int <parameter>prot</parameter></paramdef>
22 <paramdef>int <parameter>flags</parameter></paramdef>
23 <paramdef>int <parameter>fd</parameter></paramdef>
24 <paramdef>off_t <parameter>offset</parameter></paramdef>
25 </funcprototype>
26 </funcsynopsis>
27 </refsynopsisdiv>
28
29 <refsect1>
30 <title>Arguments</title>
31 <variablelist>
32 <varlistentry>
33 <term><parameter>start</parameter></term>
34 <listitem>
35 <para>Map the buffer to this address in the
36application's address space. When the <constant>MAP_FIXED</constant>
37flag is specified, <parameter>start</parameter> must be a multiple of the
38pagesize and mmap will fail when the specified address
39cannot be used. Use of this option is discouraged; applications should
40just specify a <constant>NULL</constant> pointer here.</para>
41 </listitem>
42 </varlistentry>
43 <varlistentry>
44 <term><parameter>length</parameter></term>
45 <listitem>
46 <para>Length of the memory area to map. This must be the
47same value as returned by the driver in the &v4l2-buffer;
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>
52 </listitem>
53 </varlistentry>
54 <varlistentry>
55 <term><parameter>prot</parameter></term>
56 <listitem>
57 <para>The <parameter>prot</parameter> argument describes the
58desired memory protection. Regardless of the device type and the
59direction of data exchange it should be set to
60<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>,
61permitting read and write access to image buffers. Drivers should
62support at least this combination of flags. Note the Linux
63<filename>video-buf</filename> kernel module, which is used by the
64bttv, saa7134, saa7146, cx88 and vivi driver supports only
65<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When
66the driver does not support the desired protection the
67<function>mmap()</function> function fails.</para>
68 <para>Note device memory accesses (&eg; the memory on a
69graphics card with video capturing hardware) may incur a performance
70penalty compared to main memory accesses, or reads may be
71significantly slower than writes or vice versa. Other I/O methods may
72be more efficient in this case.</para>
73 </listitem>
74 </varlistentry>
75 <varlistentry>
76 <term><parameter>flags</parameter></term>
77 <listitem>
78 <para>The <parameter>flags</parameter> parameter
79specifies the type of the mapped object, mapping options and whether
80modifications made to the mapped copy of the page are private to the
81process or are to be shared with other references.</para>
82 <para><constant>MAP_FIXED</constant> requests that the
83driver selects no other address than the one specified. If the
84specified address cannot be used, <function>mmap()</function> will fail. If
85<constant>MAP_FIXED</constant> is specified,
86<parameter>start</parameter> must be a multiple of the pagesize. Use
87of this option is discouraged.</para>
88 <para>One of the <constant>MAP_SHARED</constant> or
89<constant>MAP_PRIVATE</constant> flags must be set.
90<constant>MAP_SHARED</constant> allows applications to share the
91mapped memory with other (&eg; child-) processes. Note the Linux
92<filename>video-buf</filename> module which is used by the bttv,
93saa7134, saa7146, cx88 and vivi driver supports only
94<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant>
95requests copy-on-write semantics. V4L2 applications should not set the
96<constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>,
97<constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant>
98flag.</para>
99 </listitem>
100 </varlistentry>
101 <varlistentry>
102 <term><parameter>fd</parameter></term>
103 <listitem>
104 <para>&fd;</para>
105 </listitem>
106 </varlistentry>
107 <varlistentry>
108 <term><parameter>offset</parameter></term>
109 <listitem>
110 <para>Offset of the buffer in device memory. This must be the
111same value as returned by the driver in the &v4l2-buffer;
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>
116 </listitem>
117 </varlistentry>
118 </variablelist>
119 </refsect1>
120
121 <refsect1>
122 <title>Description</title>
123
124 <para>The <function>mmap()</function> function asks to map
125<parameter>length</parameter> bytes starting at
126<parameter>offset</parameter> in the memory of the device specified by
127<parameter>fd</parameter> into the application address space,
128preferably at address <parameter>start</parameter>. This latter
129address is a hint only, and is usually specified as 0.</para>
130
131 <para>Suitable length and offset parameters are queried with the
132&VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the
133&VIDIOC-REQBUFS; ioctl before they can be queried.</para>
134
135 <para>To unmap buffers the &func-munmap; function is used.</para>
136 </refsect1>
137
138 <refsect1>
139 <title>Return Value</title>
140
141 <para>On success <function>mmap()</function> returns a pointer to
142the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is
143returned, and the <varname>errno</varname> variable is set
144appropriately. Possible error codes are:</para>
145
146 <variablelist>
147 <varlistentry>
148 <term><errorcode>EBADF</errorcode></term>
149 <listitem>
150 <para><parameter>fd</parameter> is not a valid file
151descriptor.</para>
152 </listitem>
153 </varlistentry>
154 <varlistentry>
155 <term><errorcode>EACCES</errorcode></term>
156 <listitem>
157 <para><parameter>fd</parameter> is
158not open for reading and writing.</para>
159 </listitem>
160 </varlistentry>
161 <varlistentry>
162 <term><errorcode>EINVAL</errorcode></term>
163 <listitem>
164 <para>The <parameter>start</parameter> or
165<parameter>length</parameter> or <parameter>offset</parameter> are not
166suitable. (E.&nbsp;g. they are too large, or not aligned on a
167<constant>PAGESIZE</constant> boundary.)</para>
168 <para>The <parameter>flags</parameter> or
169<parameter>prot</parameter> value is not supported.</para>
170 <para>No buffers have been allocated with the
171&VIDIOC-REQBUFS; ioctl.</para>
172 </listitem>
173 </varlistentry>
174 <varlistentry>
175 <term><errorcode>ENOMEM</errorcode></term>
176 <listitem>
177 <para>Not enough physical or virtual memory was available to
178complete the request.</para>
179 </listitem>
180 </varlistentry>
181 </variablelist>
182 </refsect1>
183</refentry>
184
185<!--
186Local Variables:
187mode: sgml
188sgml-parent-document: "v4l2.sgml"
189indent-tabs-mode: nil
190End:
191-->
diff --git a/Documentation/DocBook/media/v4l/func-munmap.xml b/Documentation/DocBook/media/v4l/func-munmap.xml
new file mode 100644
index 000000000000..e2c4190f9bb6
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-munmap.xml
@@ -0,0 +1,84 @@
1<refentry id="func-munmap">
2 <refmeta>
3 <refentrytitle>V4L2 munmap()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-munmap</refname>
9 <refpurpose>Unmap device memory</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>
15#include &lt;unistd.h&gt;
16#include &lt;sys/mman.h&gt;</funcsynopsisinfo>
17 <funcprototype>
18 <funcdef>int <function>munmap</function></funcdef>
19 <paramdef>void *<parameter>start</parameter></paramdef>
20 <paramdef>size_t <parameter>length</parameter></paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 </refsynopsisdiv>
24 <refsect1>
25 <title>Arguments</title>
26 <variablelist>
27 <varlistentry>
28 <term><parameter>start</parameter></term>
29 <listitem>
30 <para>Address of the mapped buffer as returned by the
31&func-mmap; function.</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>length</parameter></term>
36 <listitem>
37 <para>Length of the mapped buffer. This must be the same
38value as given to <function>mmap()</function> and returned by the
39driver in the &v4l2-buffer; <structfield>length</structfield>
40field for the single-planar API and in the &v4l2-plane;
41<structfield>length</structfield> field for the multi-planar API.</para>
42 </listitem>
43 </varlistentry>
44 </variablelist>
45 </refsect1>
46
47 <refsect1>
48 <title>Description</title>
49
50 <para>Unmaps a previously with the &func-mmap; function mapped
51buffer and frees it, if possible. <!-- ? This function (not freeing)
52has no impact on I/O in progress, specifically it does not imply
53&VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be
54enqueued, dequeued or queried, they are just not accessible by the
55application.--></para>
56 </refsect1>
57
58 <refsect1>
59 <title>Return Value</title>
60
61 <para>On success <function>munmap()</function> returns 0, on
62failure -1 and the <varname>errno</varname> variable is set
63appropriately:</para>
64
65 <variablelist>
66 <varlistentry>
67 <term><errorcode>EINVAL</errorcode></term>
68 <listitem>
69 <para>The <parameter>start</parameter> or
70<parameter>length</parameter> is incorrect, or no buffers have been
71mapped yet.</para>
72 </listitem>
73 </varlistentry>
74 </variablelist>
75 </refsect1>
76</refentry>
77
78<!--
79Local Variables:
80mode: sgml
81sgml-parent-document: "v4l2.sgml"
82indent-tabs-mode: nil
83End:
84-->
diff --git a/Documentation/DocBook/media/v4l/func-open.xml b/Documentation/DocBook/media/v4l/func-open.xml
new file mode 100644
index 000000000000..7595d07a8c72
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-open.xml
@@ -0,0 +1,121 @@
1<refentry id="func-open">
2 <refmeta>
3 <refentrytitle>V4L2 open()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-open</refname>
9 <refpurpose>Open a V4L2 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
37<constant>O_RDWR</constant>. This is just a technicality, input devices
38still support only reading and output devices only writing.</para>
39 <para>When the <constant>O_NONBLOCK</constant> flag is
40given, the read() function and the &VIDIOC-DQBUF; ioctl will return
41the &EAGAIN; when no data is available or no buffer is in the driver
42outgoing queue, otherwise these functions block until data becomes
43available. All V4L2 drivers exchanging data with applications must
44support the <constant>O_NONBLOCK</constant> flag.</para>
45 <para>Other flags have no effect.</para>
46 </listitem>
47 </varlistentry>
48 </variablelist>
49 </refsect1>
50 <refsect1>
51 <title>Description</title>
52
53 <para>To open a V4L2 device applications call
54<function>open()</function> with the desired device name. This
55function has no side effects; all data format parameters, current
56input or output, control values or other properties remain unchanged.
57At the first <function>open()</function> call after loading the driver
58they will be reset to default values, drivers are never in an
59undefined state.</para>
60 </refsect1>
61 <refsect1>
62 <title>Return Value</title>
63
64 <para>On success <function>open</function> returns the new file
65descriptor. On error -1 is returned, and the <varname>errno</varname>
66variable is set appropriately. Possible error codes are:</para>
67
68 <variablelist>
69 <varlistentry>
70 <term><errorcode>EACCES</errorcode></term>
71 <listitem>
72 <para>The caller has no permission to access the
73device.</para>
74 </listitem>
75 </varlistentry>
76 <varlistentry>
77 <term><errorcode>EBUSY</errorcode></term>
78 <listitem>
79 <para>The driver does not support multiple opens and the
80device is already in use.</para>
81 </listitem>
82 </varlistentry>
83 <varlistentry>
84 <term><errorcode>ENXIO</errorcode></term>
85 <listitem>
86 <para>No device corresponding to this device special file
87exists.</para>
88 </listitem>
89 </varlistentry>
90 <varlistentry>
91 <term><errorcode>ENOMEM</errorcode></term>
92 <listitem>
93 <para>Not enough kernel memory was available to complete the
94request.</para>
95 </listitem>
96 </varlistentry>
97 <varlistentry>
98 <term><errorcode>EMFILE</errorcode></term>
99 <listitem>
100 <para>The process already has the maximum number of
101files open.</para>
102 </listitem>
103 </varlistentry>
104 <varlistentry>
105 <term><errorcode>ENFILE</errorcode></term>
106 <listitem>
107 <para>The limit on the total number of files open on the
108system has been reached.</para>
109 </listitem>
110 </varlistentry>
111 </variablelist>
112 </refsect1>
113</refentry>
114
115<!--
116Local Variables:
117mode: sgml
118sgml-parent-document: "v4l2.sgml"
119indent-tabs-mode: nil
120End:
121-->
diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml
new file mode 100644
index 000000000000..ec3c718f5963
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-poll.xml
@@ -0,0 +1,127 @@
1<refentry id="func-poll">
2 <refmeta>
3 <refentrytitle>V4L2 poll()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-poll</refname>
9 <refpurpose>Wait for some event on a file descriptor</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;sys/poll.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>poll</function></funcdef>
17 <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
18 <paramdef>unsigned int <parameter>nfds</parameter></paramdef>
19 <paramdef>int <parameter>timeout</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Description</title>
26
27 <para>With the <function>poll()</function> function applications
28can suspend execution until the driver has captured data or is ready
29to accept data for output.</para>
30
31 <para>When streaming I/O has been negotiated this function waits
32until a buffer has been filled or displayed and can be dequeued with
33the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
34queue of the driver the function returns immediately.</para>
35
36 <para>On success <function>poll()</function> returns the number of
37file descriptors that have been selected (that is, file descriptors
38for which the <structfield>revents</structfield> field of the
39respective <structname>pollfd</structname> structure is non-zero).
40Capture devices set the <constant>POLLIN</constant> and
41<constant>POLLRDNORM</constant> flags in the
42<structfield>revents</structfield> field, output devices the
43<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
44flags. When the function timed out it returns a value of zero, on
45failure it returns <returnvalue>-1</returnvalue> and the
46<varname>errno</varname> variable is set appropriately. When the
47application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
48<function>poll()</function> function succeeds, but sets the
49<constant>POLLERR</constant> flag in the
50<structfield>revents</structfield> field.</para>
51
52 <para>When use of the <function>read()</function> function has
53been negotiated and the driver does not capture yet, the
54<function>poll</function> function starts capturing. When that fails
55it returns a <constant>POLLERR</constant> as above. Otherwise it waits
56until data has been captured and can be read. When the driver captures
57continuously (as opposed to, for example, still images) the function
58may return immediately.</para>
59
60 <para>When use of the <function>write()</function> function has
61been negotiated the <function>poll</function> function just waits
62until the driver is ready for a non-blocking
63<function>write()</function> call.</para>
64
65 <para>All drivers implementing the <function>read()</function> or
66<function>write()</function> function or streaming I/O must also
67support the <function>poll()</function> function.</para>
68
69 <para>For more details see the
70<function>poll()</function> manual page.</para>
71 </refsect1>
72
73 <refsect1>
74 <title>Return Value</title>
75
76 <para>On success, <function>poll()</function> returns the number
77structures which have non-zero <structfield>revents</structfield>
78fields, or zero if the call timed out. On error
79<returnvalue>-1</returnvalue> is returned, and the
80<varname>errno</varname> variable is set appropriately:</para>
81
82 <variablelist>
83 <varlistentry>
84 <term><errorcode>EBADF</errorcode></term>
85 <listitem>
86 <para>One or more of the <parameter>ufds</parameter> members
87specify an invalid file descriptor.</para>
88 </listitem>
89 </varlistentry>
90 <varlistentry>
91 <term><errorcode>EBUSY</errorcode></term>
92 <listitem>
93 <para>The driver does not support multiple read or write
94streams and the device is already in use.</para>
95 </listitem>
96 </varlistentry>
97 <varlistentry>
98 <term><errorcode>EFAULT</errorcode></term>
99 <listitem>
100 <para><parameter>ufds</parameter> references an inaccessible
101memory area.</para>
102 </listitem>
103 </varlistentry>
104 <varlistentry>
105 <term><errorcode>EINTR</errorcode></term>
106 <listitem>
107 <para>The call was interrupted by a signal.</para>
108 </listitem>
109 </varlistentry>
110 <varlistentry>
111 <term><errorcode>EINVAL</errorcode></term>
112 <listitem>
113 <para>The <parameter>nfds</parameter> argument is greater
114than <constant>OPEN_MAX</constant>.</para>
115 </listitem>
116 </varlistentry>
117 </variablelist>
118 </refsect1>
119</refentry>
120
121<!--
122Local Variables:
123mode: sgml
124sgml-parent-document: "v4l2.sgml"
125indent-tabs-mode: nil
126End:
127-->
diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml
new file mode 100644
index 000000000000..a5089bf8873d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-read.xml
@@ -0,0 +1,189 @@
1<refentry id="func-read">
2 <refmeta>
3 <refentrytitle>V4L2 read()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-read</refname>
9 <refpurpose>Read from a V4L2 device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>ssize_t <function>read</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>void *<parameter>buf</parameter></paramdef>
19 <paramdef>size_t <parameter>count</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>buf</parameter></term>
36 <listitem>
37 <para></para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>count</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><function>read()</function> attempts to read up to
53<parameter>count</parameter> bytes from file descriptor
54<parameter>fd</parameter> into the buffer starting at
55<parameter>buf</parameter>. The layout of the data in the buffer is
56discussed in the respective device interface section, see ##. If <parameter>count</parameter> is zero,
57<function>read()</function> returns zero and has no other results. If
58<parameter>count</parameter> is greater than
59<constant>SSIZE_MAX</constant>, the result is unspecified. Regardless
60of the <parameter>count</parameter> value each
61<function>read()</function> call will provide at most one frame (two
62fields) worth of data.</para>
63
64 <para>By default <function>read()</function> blocks until data
65becomes available. When the <constant>O_NONBLOCK</constant> flag was
66given to the &func-open; function it
67returns immediately with an &EAGAIN; when no data is available. The
68&func-select; or &func-poll; functions
69can always be used to suspend execution until data becomes available. All
70drivers supporting the <function>read()</function> function must also
71support <function>select()</function> and
72<function>poll()</function>.</para>
73
74 <para>Drivers can implement read functionality in different
75ways, using a single or multiple buffers and discarding the oldest or
76newest frames once the internal buffers are filled.</para>
77
78 <para><function>read()</function> never returns a "snapshot" of a
79buffer being filled. Using a single buffer the driver will stop
80capturing when the application starts reading the buffer until the
81read is finished. Thus only the period of the vertical blanking
82interval is available for reading, or the capture rate must fall below
83the nominal frame rate of the video standard.</para>
84
85<para>The behavior of
86<function>read()</function> when called during the active picture
87period or the vertical blanking separating the top and bottom field
88depends on the discarding policy. A driver discarding the oldest
89frames keeps capturing into an internal buffer, continuously
90overwriting the previously, not read frame, and returns the frame
91being received at the time of the <function>read()</function> call as
92soon as it is complete.</para>
93
94 <para>A driver discarding the newest frames stops capturing until
95the next <function>read()</function> call. The frame being received at
96<function>read()</function> time is discarded, returning the following
97frame instead. Again this implies a reduction of the capture rate to
98one half or less of the nominal frame rate. An example of this model
99is the video read mode of the bttv driver, initiating a DMA to user
100memory when <function>read()</function> is called and returning when
101the DMA finished.</para>
102
103 <para>In the multiple buffer model drivers maintain a ring of
104internal buffers, automatically advancing to the next free buffer.
105This allows continuous capturing when the application can empty the
106buffers fast enough. Again, the behavior when the driver runs out of
107free buffers depends on the discarding policy.</para>
108
109 <para>Applications can get and set the number of buffers used
110internally by the driver with the &VIDIOC-G-PARM; and &VIDIOC-S-PARM;
111ioctls. They are optional, however. The discarding policy is not
112reported and cannot be changed. For minimum requirements see <xref
113 linkend="devices" />.</para>
114 </refsect1>
115
116 <refsect1>
117 <title>Return Value</title>
118
119 <para>On success, the number of bytes read is returned. It is not
120an error if this number is smaller than the number of bytes requested,
121or the amount of data required for one frame. This may happen for
122example because <function>read()</function> was interrupted by a
123signal. On error, -1 is returned, and the <varname>errno</varname>
124variable is set appropriately. In this case the next read will start
125at the beginning of a new frame. Possible error codes are:</para>
126
127 <variablelist>
128 <varlistentry>
129 <term><errorcode>EAGAIN</errorcode></term>
130 <listitem>
131 <para>Non-blocking I/O has been selected using
132O_NONBLOCK and no data was immediately available for reading.</para>
133 </listitem>
134 </varlistentry>
135 <varlistentry>
136 <term><errorcode>EBADF</errorcode></term>
137 <listitem>
138 <para><parameter>fd</parameter> is not a valid file
139descriptor or is not open for reading, or the process already has the
140maximum number of files open.</para>
141 </listitem>
142 </varlistentry>
143 <varlistentry>
144 <term><errorcode>EBUSY</errorcode></term>
145 <listitem>
146 <para>The driver does not support multiple read streams and the
147device is already in use.</para>
148 </listitem>
149 </varlistentry>
150 <varlistentry>
151 <term><errorcode>EFAULT</errorcode></term>
152 <listitem>
153 <para><parameter>buf</parameter> references an inaccessible
154memory area.</para>
155 </listitem>
156 </varlistentry>
157 <varlistentry>
158 <term><errorcode>EINTR</errorcode></term>
159 <listitem>
160 <para>The call was interrupted by a signal before any
161data was read.</para>
162 </listitem>
163 </varlistentry>
164 <varlistentry>
165 <term><errorcode>EIO</errorcode></term>
166 <listitem>
167 <para>I/O error. This indicates some hardware problem or a
168failure to communicate with a remote device (USB camera etc.).</para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
172 <term><errorcode>EINVAL</errorcode></term>
173 <listitem>
174 <para>The <function>read()</function> function is not
175supported by this driver, not on this device, or generally not on this
176type of device.</para>
177 </listitem>
178 </varlistentry>
179 </variablelist>
180 </refsect1>
181</refentry>
182
183<!--
184Local Variables:
185mode: sgml
186sgml-parent-document: "v4l2.sgml"
187indent-tabs-mode: nil
188End:
189-->
diff --git a/Documentation/DocBook/media/v4l/func-select.xml b/Documentation/DocBook/media/v4l/func-select.xml
new file mode 100644
index 000000000000..b6713623181f
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-select.xml
@@ -0,0 +1,138 @@
1<refentry id="func-select">
2 <refmeta>
3 <refentrytitle>V4L2 select()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-select</refname>
9 <refpurpose>Synchronous I/O multiplexing</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>
15#include &lt;sys/time.h&gt;
16#include &lt;sys/types.h&gt;
17#include &lt;unistd.h&gt;</funcsynopsisinfo>
18 <funcprototype>
19 <funcdef>int <function>select</function></funcdef>
20 <paramdef>int <parameter>nfds</parameter></paramdef>
21 <paramdef>fd_set *<parameter>readfds</parameter></paramdef>
22 <paramdef>fd_set *<parameter>writefds</parameter></paramdef>
23 <paramdef>fd_set *<parameter>exceptfds</parameter></paramdef>
24 <paramdef>struct timeval *<parameter>timeout</parameter></paramdef>
25 </funcprototype>
26 </funcsynopsis>
27 </refsynopsisdiv>
28
29 <refsect1>
30 <title>Description</title>
31
32 <para>With the <function>select()</function> function applications
33can suspend execution until the driver has captured data or is ready
34to accept data for output.</para>
35
36 <para>When streaming I/O has been negotiated this function waits
37until a buffer has been filled or displayed and can be dequeued with
38the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing
39queue of the driver the function returns immediately.</para>
40
41 <para>On success <function>select()</function> returns the total
42number of bits set in the <structname>fd_set</structname>s. When the
43function timed out it returns a value of zero. On failure it returns
44<returnvalue>-1</returnvalue> and the <varname>errno</varname>
45variable is set appropriately. When the application did not call
46&VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the
47<function>select()</function> function succeeds, setting the bit of
48the file descriptor in <parameter>readfds</parameter> or
49<parameter>writefds</parameter>, but subsequent &VIDIOC-DQBUF; calls
50will fail.<footnote><para>The Linux kernel implements
51<function>select()</function> like the &func-poll; function, but
52<function>select()</function> cannot return a
53<constant>POLLERR</constant>.</para>
54 </footnote></para>
55
56 <para>When use of the <function>read()</function> function has
57been negotiated and the driver does not capture yet, the
58<function>select()</function> function starts capturing. When that
59fails, <function>select()</function> returns successful and a
60subsequent <function>read()</function> call, which also attempts to
61start capturing, will return an appropriate error code. When the
62driver captures continuously (as opposed to, for example, still
63images) and data is already available the
64<function>select()</function> function returns immediately.</para>
65
66 <para>When use of the <function>write()</function> function has
67been negotiated the <function>select()</function> function just waits
68until the driver is ready for a non-blocking
69<function>write()</function> call.</para>
70
71 <para>All drivers implementing the <function>read()</function> or
72<function>write()</function> function or streaming I/O must also
73support the <function>select()</function> function.</para>
74
75 <para>For more details see the <function>select()</function>
76manual page.</para>
77
78 </refsect1>
79
80 <refsect1>
81 <title>Return Value</title>
82
83 <para>On success, <function>select()</function> returns the number
84of descriptors contained in the three returned descriptor sets, which
85will be zero if the timeout expired. On error
86<returnvalue>-1</returnvalue> is returned, and the
87<varname>errno</varname> variable is set appropriately; the sets and
88<parameter>timeout</parameter> are undefined. Possible error codes
89are:</para>
90
91 <variablelist>
92 <varlistentry>
93 <term><errorcode>EBADF</errorcode></term>
94 <listitem>
95 <para>One or more of the file descriptor sets specified a
96file descriptor that is not open.</para>
97 </listitem>
98 </varlistentry>
99 <varlistentry>
100 <term><errorcode>EBUSY</errorcode></term>
101 <listitem>
102 <para>The driver does not support multiple read or write
103streams and the device is already in use.</para>
104 </listitem>
105 </varlistentry>
106 <varlistentry>
107 <term><errorcode>EFAULT</errorcode></term>
108 <listitem>
109 <para>The <parameter>readfds</parameter>,
110<parameter>writefds</parameter>, <parameter>exceptfds</parameter> or
111<parameter>timeout</parameter> pointer references an inaccessible memory
112area.</para>
113 </listitem>
114 </varlistentry>
115 <varlistentry>
116 <term><errorcode>EINTR</errorcode></term>
117 <listitem>
118 <para>The call was interrupted by a signal.</para>
119 </listitem>
120 </varlistentry>
121 <varlistentry>
122 <term><errorcode>EINVAL</errorcode></term>
123 <listitem>
124 <para>The <parameter>nfds</parameter> argument is less than
125zero or greater than <constant>FD_SETSIZE</constant>.</para>
126 </listitem>
127 </varlistentry>
128 </variablelist>
129 </refsect1>
130</refentry>
131
132<!--
133Local Variables:
134mode: sgml
135sgml-parent-document: "v4l2.sgml"
136indent-tabs-mode: nil
137End:
138-->
diff --git a/Documentation/DocBook/media/v4l/func-write.xml b/Documentation/DocBook/media/v4l/func-write.xml
new file mode 100644
index 000000000000..2c09c09371c3
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/func-write.xml
@@ -0,0 +1,136 @@
1<refentry id="func-write">
2 <refmeta>
3 <refentrytitle>V4L2 write()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>v4l2-write</refname>
9 <refpurpose>Write to a V4L2 device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>ssize_t <function>write</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>void *<parameter>buf</parameter></paramdef>
19 <paramdef>size_t <parameter>count</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>buf</parameter></term>
36 <listitem>
37 <para></para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>count</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><function>write()</function> writes up to
53<parameter>count</parameter> bytes to the device referenced by the
54file descriptor <parameter>fd</parameter> from the buffer starting at
55<parameter>buf</parameter>. When the hardware outputs are not active
56yet, this function enables them. When <parameter>count</parameter> is
57zero, <function>write()</function> returns
58<returnvalue>0</returnvalue> without any other effect.</para>
59
60 <para>When the application does not provide more data in time, the
61previous video frame, raw VBI image, sliced VPS or WSS data is
62displayed again. Sliced Teletext or Closed Caption data is not
63repeated, the driver inserts a blank line instead.</para>
64 </refsect1>
65
66 <refsect1>
67 <title>Return Value</title>
68
69 <para>On success, the number of bytes written are returned. Zero
70indicates nothing was written. On error, <returnvalue>-1</returnvalue>
71is returned, and the <varname>errno</varname> variable is set
72appropriately. In this case the next write will start at the beginning
73of a new frame. Possible error codes are:</para>
74
75 <variablelist>
76 <varlistentry>
77 <term><errorcode>EAGAIN</errorcode></term>
78 <listitem>
79 <para>Non-blocking I/O has been selected using the <link
80linkend="func-open"><constant>O_NONBLOCK</constant></link> flag and no
81buffer space was available to write the data immediately.</para>
82 </listitem>
83 </varlistentry>
84 <varlistentry>
85 <term><errorcode>EBADF</errorcode></term>
86 <listitem>
87 <para><parameter>fd</parameter> is not a valid file
88descriptor or is not open for writing.</para>
89 </listitem>
90 </varlistentry>
91 <varlistentry>
92 <term><errorcode>EBUSY</errorcode></term>
93 <listitem>
94 <para>The driver does not support multiple write streams and the
95device is already in use.</para>
96 </listitem>
97 </varlistentry>
98 <varlistentry>
99 <term><errorcode>EFAULT</errorcode></term>
100 <listitem>
101 <para><parameter>buf</parameter> references an inaccessible
102memory area.</para>
103 </listitem>
104 </varlistentry>
105 <varlistentry>
106 <term><errorcode>EINTR</errorcode></term>
107 <listitem>
108 <para>The call was interrupted by a signal before any
109data was written.</para>
110 </listitem>
111 </varlistentry>
112 <varlistentry>
113 <term><errorcode>EIO</errorcode></term>
114 <listitem>
115 <para>I/O error. This indicates some hardware problem.</para>
116 </listitem>
117 </varlistentry>
118 <varlistentry>
119 <term><errorcode>EINVAL</errorcode></term>
120 <listitem>
121 <para>The <function>write()</function> function is not
122supported by this driver, not on this device, or generally not on this
123type of device.</para>
124 </listitem>
125 </varlistentry>
126 </variablelist>
127 </refsect1>
128</refentry>
129
130<!--
131Local Variables:
132mode: sgml
133sgml-parent-document: "v4l2.sgml"
134indent-tabs-mode: nil
135End:
136-->
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
new file mode 100644
index 000000000000..227e7ac45a06
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -0,0 +1,1265 @@
1 <title>Input/Output</title>
2
3 <para>The V4L2 API defines several different methods to read from or
4write to a device. All drivers exchanging data with applications must
5support at least one of them.</para>
6
7 <para>The classic I/O method using the <function>read()</function>
8and <function>write()</function> function is automatically selected
9after opening a V4L2 device. When the driver does not support this
10method attempts to read or write will fail at any time.</para>
11
12 <para>Other methods must be negotiated. To select the streaming I/O
13method with memory mapped or user buffers applications call the
14&VIDIOC-REQBUFS; ioctl. The asynchronous I/O method is not defined
15yet.</para>
16
17 <para>Video overlay can be considered another I/O method, although
18the application does not directly receive the image data. It is
19selected by initiating video overlay with the &VIDIOC-S-FMT; ioctl.
20For more information see <xref linkend="overlay" />.</para>
21
22 <para>Generally exactly one I/O method, including overlay, is
23associated with each file descriptor. The only exceptions are
24applications not exchanging data with a driver ("panel applications",
25see <xref linkend="open" />) and drivers permitting simultaneous video capturing
26and overlay using the same file descriptor, for compatibility with V4L
27and earlier versions of V4L2.</para>
28
29 <para><constant>VIDIOC_S_FMT</constant> and
30<constant>VIDIOC_REQBUFS</constant> would permit this to some degree,
31but for simplicity drivers need not support switching the I/O method
32(after first switching away from read/write) other than by closing
33and reopening the device.</para>
34
35 <para>The following sections describe the various I/O methods in
36more detail.</para>
37
38 <section id="rw">
39 <title>Read/Write</title>
40
41 <para>Input and output devices support the
42<function>read()</function> and <function>write()</function> function,
43respectively, when the <constant>V4L2_CAP_READWRITE</constant> flag in
44the <structfield>capabilities</structfield> field of &v4l2-capability;
45returned by the &VIDIOC-QUERYCAP; ioctl is set.</para>
46
47 <para>Drivers may need the CPU to copy the data, but they may also
48support DMA to or from user memory, so this I/O method is not
49necessarily less efficient than other methods merely exchanging buffer
50pointers. It is considered inferior though because no meta-information
51like frame counters or timestamps are passed. This information is
52necessary to recognize frame dropping and to synchronize with other
53data streams. However this is also the simplest I/O method, requiring
54little or no setup to exchange data. It permits command line stunts
55like this (the <application>vidctrl</application> tool is
56fictitious):</para>
57
58 <informalexample>
59 <screen>
60&gt; vidctrl /dev/video --input=0 --format=YUYV --size=352x288
61&gt; dd if=/dev/video of=myimage.422 bs=202752 count=1
62</screen>
63 </informalexample>
64
65 <para>To read from the device applications use the
66&func-read; function, to write the &func-write; function.
67Drivers must implement one I/O method if they
68exchange data with applications, but it need not be this.<footnote>
69 <para>It would be desirable if applications could depend on
70drivers supporting all I/O interfaces, but as much as the complex
71memory mapping I/O can be inadequate for some devices we have no
72reason to require this interface, which is most useful for simple
73applications capturing still images.</para>
74 </footnote> When reading or writing is supported, the driver
75must also support the &func-select; and &func-poll;
76function.<footnote>
77 <para>At the driver level <function>select()</function> and
78<function>poll()</function> are the same, and
79<function>select()</function> is too important to be optional.</para>
80 </footnote></para>
81 </section>
82
83 <section id="mmap">
84 <title>Streaming I/O (Memory Mapping)</title>
85
86 <para>Input and output devices support this I/O method when the
87<constant>V4L2_CAP_STREAMING</constant> flag in the
88<structfield>capabilities</structfield> field of &v4l2-capability;
89returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
90streaming methods, to determine if the memory mapping flavor is
91supported applications must call the &VIDIOC-REQBUFS; ioctl.</para>
92
93 <para>Streaming is an I/O method where only pointers to buffers
94are exchanged between application and driver, the data itself is not
95copied. Memory mapping is primarily intended to map buffers in device
96memory into the application's address space. Device memory can be for
97example the video memory on a graphics card with a video capture
98add-on. However, being the most efficient I/O method available for a
99long time, many other drivers support streaming as well, allocating
100buffers in DMA-able main memory.</para>
101
102 <para>A driver can support many sets of buffers. Each set is
103identified by a unique buffer type value. The sets are independent and
104each set can hold a different type of data. To access different sets
105at the same time different file descriptors must be used.<footnote>
106 <para>One could use one file descriptor and set the buffer
107type field accordingly when calling &VIDIOC-QBUF; etc., but it makes
108the <function>select()</function> function ambiguous. We also like the
109clean approach of one file descriptor per logical stream. Video
110overlay for example is also a logical stream, although the CPU is not
111needed for continuous operation.</para>
112 </footnote></para>
113
114 <para>To allocate device buffers applications call the
115&VIDIOC-REQBUFS; ioctl with the desired number of buffers and buffer
116type, for example <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.
117This ioctl can also be used to change the number of buffers or to free
118the allocated memory, provided none of the buffers are still
119mapped.</para>
120
121 <para>Before applications can access the buffers they must map
122them into their address space with the &func-mmap; function. The
123location of the buffers in device memory can be determined with the
124&VIDIOC-QUERYBUF; ioctl. In the single-planar API case, the
125<structfield>m.offset</structfield> and <structfield>length</structfield>
126returned in a &v4l2-buffer; are passed as sixth and second parameter to the
127<function>mmap()</function> function. When using the multi-planar API,
128struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
129containing its own <structfield>m.offset</structfield> and
130<structfield>length</structfield>. When using the multi-planar API, every
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>
137
138 <example>
139 <title>Mapping buffers in the single-planar API</title>
140 <programlisting>
141&v4l2-requestbuffers; reqbuf;
142struct {
143 void *start;
144 size_t length;
145} *buffers;
146unsigned int i;
147
148memset(&amp;reqbuf, 0, sizeof(reqbuf));
149reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
150reqbuf.memory = V4L2_MEMORY_MMAP;
151reqbuf.count = 20;
152
153if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) {
154 if (errno == EINVAL)
155 printf("Video capturing or mmap-streaming is not supported\n");
156 else
157 perror("VIDIOC_REQBUFS");
158
159 exit(EXIT_FAILURE);
160}
161
162/* We want at least five buffers. */
163
164if (reqbuf.count &lt; 5) {
165 /* You may need to free the buffers here. */
166 printf("Not enough buffer memory\n");
167 exit(EXIT_FAILURE);
168}
169
170buffers = calloc(reqbuf.count, sizeof(*buffers));
171assert(buffers != NULL);
172
173for (i = 0; i &lt; reqbuf.count; i++) {
174 &v4l2-buffer; buffer;
175
176 memset(&amp;buffer, 0, sizeof(buffer));
177 buffer.type = reqbuf.type;
178 buffer.memory = V4L2_MEMORY_MMAP;
179 buffer.index = i;
180
181 if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) {
182 perror("VIDIOC_QUERYBUF");
183 exit(EXIT_FAILURE);
184 }
185
186 buffers[i].length = buffer.length; /* remember for munmap() */
187
188 buffers[i].start = mmap(NULL, buffer.length,
189 PROT_READ | PROT_WRITE, /* recommended */
190 MAP_SHARED, /* recommended */
191 fd, buffer.m.offset);
192
193 if (MAP_FAILED == buffers[i].start) {
194 /* If you do not exit here you should unmap() and free()
195 the buffers mapped so far. */
196 perror("mmap");
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 }
279 }
280}
281
282/* Cleanup. */
283
284for (i = 0; i &lt; reqbuf.count; i++)
285 for (j = 0; j &lt; FMT_NUM_PLANES; j++)
286 munmap(buffers[i].start[j], buffers[i].length[j]);
287 </programlisting>
288 </example>
289
290 <para>Conceptually streaming drivers maintain two buffer queues, an incoming
291and an outgoing queue. They separate the synchronous capture or output
292operation locked to a video clock from the application which is
293subject to random disk or network delays and preemption by
294other processes, thereby reducing the probability of data loss.
295The queues are organized as FIFOs, buffers will be
296output in the order enqueued in the incoming FIFO, and were
297captured in the order dequeued from the outgoing FIFO.</para>
298
299 <para>The driver may require a minimum number of buffers enqueued
300at all times to function, apart of this no limit exists on the number
301of buffers applications can enqueue in advance, or dequeue and
302process. They can also enqueue in a different order than buffers have
303been dequeued, and the driver can <emphasis>fill</emphasis> enqueued
304<emphasis>empty</emphasis> buffers in any order. <footnote>
305 <para>Random enqueue order permits applications processing
306images out of order (such as video codecs) to return buffers earlier,
307reducing the probability of data loss. Random fill order allows
308drivers to reuse buffers on a LIFO-basis, taking advantage of caches
309holding scatter-gather lists and the like.</para>
310 </footnote> The index number of a buffer (&v4l2-buffer;
311<structfield>index</structfield>) plays no role here, it only
312identifies the buffer.</para>
313
314 <para>Initially all mapped buffers are in dequeued state,
315inaccessible by the driver. For capturing applications it is customary
316to first enqueue all mapped buffers, then to start capturing and enter
317the read loop. Here the application waits until a filled buffer can be
318dequeued, and re-enqueues the buffer when the data is no longer
319needed. Output applications fill and enqueue buffers, when enough
320buffers are stacked up the output is started with
321<constant>VIDIOC_STREAMON</constant>. In the write loop, when
322the application runs out of free buffers, it must wait until an empty
323buffer can be dequeued and reused.</para>
324
325 <para>To enqueue and dequeue a buffer applications use the
326&VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
327mapped, enqueued, full or empty can be determined at any time using the
328&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
329application until one or more buffers can be dequeued. By default
330<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
331outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
332given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
333returns immediately with an &EAGAIN; when no buffer is available. The
334&func-select; or &func-poll; function are always available.</para>
335
336 <para>To start and stop capturing or output applications call the
337&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
338<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
339queues as a side effect. Since there is no notion of doing anything
340"now" on a multitasking system, if an application needs to synchronize
341with another event it should examine the &v4l2-buffer;
342<structfield>timestamp</structfield> of captured buffers, or set the
343field before enqueuing buffers for output.</para>
344
345 <para>Drivers implementing memory mapping I/O must
346support the <constant>VIDIOC_REQBUFS</constant>,
347<constant>VIDIOC_QUERYBUF</constant>,
348<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
349<constant>VIDIOC_STREAMON</constant> and
350<constant>VIDIOC_STREAMOFF</constant> ioctl, the
351<function>mmap()</function>, <function>munmap()</function>,
352<function>select()</function> and <function>poll()</function>
353function.<footnote>
354 <para>At the driver level <function>select()</function> and
355<function>poll()</function> are the same, and
356<function>select()</function> is too important to be optional. The
357rest should be evident.</para>
358 </footnote></para>
359
360 <para>[capture example]</para>
361
362 </section>
363
364 <section id="userp">
365 <title>Streaming I/O (User Pointers)</title>
366
367 <para>Input and output devices support this I/O method when the
368<constant>V4L2_CAP_STREAMING</constant> flag in the
369<structfield>capabilities</structfield> field of &v4l2-capability;
370returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
371pointer method (not only memory mapping) is supported must be
372determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
373
374 <para>This I/O method combines advantages of the read/write and
375memory mapping methods. Buffers (planes) are allocated by the application
376itself, and can reside for example in virtual or shared memory. Only
377pointers to data are exchanged, these pointers and meta-information
378are passed in &v4l2-buffer; (or in &v4l2-plane; in the multi-planar API case).
379The driver must be switched into user pointer I/O mode by calling the
380&VIDIOC-REQBUFS; with the desired buffer type. No buffers (planes) are allocated
381beforehand, consequently they are not indexed and cannot be queried like mapped
382buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
383
384 <example>
385 <title>Initiating streaming I/O with user pointers</title>
386
387 <programlisting>
388&v4l2-requestbuffers; reqbuf;
389
390memset (&amp;reqbuf, 0, sizeof (reqbuf));
391reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
392reqbuf.memory = V4L2_MEMORY_USERPTR;
393
394if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
395 if (errno == EINVAL)
396 printf ("Video capturing or user pointer streaming is not supported\n");
397 else
398 perror ("VIDIOC_REQBUFS");
399
400 exit (EXIT_FAILURE);
401}
402 </programlisting>
403 </example>
404
405 <para>Buffer (plane) addresses and sizes are passed on the fly with the
406&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
407applications can pass different addresses and sizes at each
408<constant>VIDIOC_QBUF</constant> call. If required by the hardware the
409driver swaps memory pages within physical memory to create a
410continuous area of memory. This happens transparently to the
411application in the virtual memory subsystem of the kernel. When buffer
412pages have been swapped out to disk they are brought back and finally
413locked in physical memory for DMA.<footnote>
414 <para>We expect that frequently used buffers are typically not
415swapped out. Anyway, the process of swapping, locking or generating
416scatter-gather lists may be time consuming. The delay can be masked by
417the depth of the incoming buffer queue, and perhaps by maintaining
418caches assuming a buffer will be soon enqueued again. On the other
419hand, to optimize memory usage drivers can limit the number of buffers
420locked in advance and recycle the most recently used buffers first. Of
421course, the pages of empty buffers in the incoming queue need not be
422saved to disk. Output buffers must be saved on the incoming and
423outgoing queue because an application may share them with other
424processes.</para>
425 </footnote></para>
426
427 <para>Filled or displayed buffers are dequeued with the
428&VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any
429time between the completion of the DMA and this ioctl. The memory is
430also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
431when the device is closed. Applications must take care not to free
432buffers without dequeuing. For once, the buffers remain locked until
433further, wasting physical memory. Second the driver will not be
434notified when the memory is returned to the application's free list
435and subsequently reused for other purposes, possibly completing the
436requested DMA and overwriting valuable data.</para>
437
438 <para>For capturing applications it is customary to enqueue a
439number of empty buffers, to start capturing and enter the read loop.
440Here the application waits until a filled buffer can be dequeued, and
441re-enqueues the buffer when the data is no longer needed. Output
442applications fill and enqueue buffers, when enough buffers are stacked
443up output is started. In the write loop, when the application
444runs out of free buffers it must wait until an empty buffer can be
445dequeued and reused. Two methods exist to suspend execution of the
446application until one or more buffers can be dequeued. By default
447<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
448outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
449given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
450returns immediately with an &EAGAIN; when no buffer is available. The
451&func-select; or &func-poll; function are always available.</para>
452
453 <para>To start and stop capturing or output applications call the
454&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
455<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
456queues and unlocks all buffers as a side effect. Since there is no
457notion of doing anything "now" on a multitasking system, if an
458application needs to synchronize with another event it should examine
459the &v4l2-buffer; <structfield>timestamp</structfield> of captured
460buffers, or set the field before enqueuing buffers for output.</para>
461
462 <para>Drivers implementing user pointer I/O must
463support the <constant>VIDIOC_REQBUFS</constant>,
464<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
465<constant>VIDIOC_STREAMON</constant> and
466<constant>VIDIOC_STREAMOFF</constant> ioctl, the
467<function>select()</function> and <function>poll()</function> function.<footnote>
468 <para>At the driver level <function>select()</function> and
469<function>poll()</function> are the same, and
470<function>select()</function> is too important to be optional. The
471rest should be evident.</para>
472 </footnote></para>
473 </section>
474
475 <section id="async">
476 <title>Asynchronous I/O</title>
477
478 <para>This method is not defined yet.</para>
479 </section>
480
481 <section id="buffer">
482 <title>Buffers</title>
483
484 <para>A buffer contains data exchanged by application and
485driver using one of the Streaming I/O methods. In the multi-planar API, the
486data is held in planes, while the buffer structure acts as a container
487for the planes. Only pointers to buffers (planes) are exchanged, the data
488itself is not copied. These pointers, together with meta-information like
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>
497
498 <para>Nominally timestamps refer to the first data byte transmitted.
499In practice however the wide range of hardware covered by the V4L2 API
500limits timestamp accuracy. Often an interrupt routine will
501sample the system clock shortly after the field or frame was stored
502completely in memory. So applications must expect a constant
503difference up to one field or frame period plus a small (few scan
504lines) random error. The delay and error can be much
505larger due to compression or transmission over an external bus when
506the frames are not properly stamped by the sender. This is frequently
507the case with USB cameras. Here timestamps refer to the instant the
508field or frame was received by the driver, not the capture time. These
509devices identify by not enumerating any video standards, see <xref
510linkend="standard" />.</para>
511
512 <para>Similar limitations apply to output timestamps. Typically
513the video hardware locks to a clock controlling the video timing, the
514horizontal and vertical synchronization pulses. At some point in the
515line sequence, possibly the vertical blanking, an interrupt routine
516samples the system clock, compares against the timestamp and programs
517the hardware to repeat the previous field or frame, or to display the
518buffer contents.</para>
519
520 <para>Apart of limitations of the video device and natural
521inaccuracies of all clocks, it should be noted system time itself is
522not perfectly stable. It can be affected by power saving cycles,
523warped to insert leap seconds, or even turned back or forth by the
524system administrator affecting long term measurements. <footnote>
525 <para>Since no other Linux multimedia
526API supports unadjusted time it would be foolish to introduce here. We
527must use a universally supported clock to synchronize different media,
528hence time of day.</para>
529 </footnote></para>
530
531 <table frame="none" pgwide="1" id="v4l2-buffer">
532 <title>struct <structname>v4l2_buffer</structname></title>
533 <tgroup cols="4">
534 &cs-ustr;
535 <tbody valign="top">
536 <row>
537 <entry>__u32</entry>
538 <entry><structfield>index</structfield></entry>
539 <entry></entry>
540 <entry>Number of the buffer, set by the application. This
541field is only used for <link linkend="mmap">memory mapping</link> I/O
542and can range from zero to the number of buffers allocated
543with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
544 </row>
545 <row>
546 <entry>&v4l2-buf-type;</entry>
547 <entry><structfield>type</structfield></entry>
548 <entry></entry>
549 <entry>Type of the buffer, same as &v4l2-format;
550<structfield>type</structfield> or &v4l2-requestbuffers;
551<structfield>type</structfield>, set by the application.</entry>
552 </row>
553 <row>
554 <entry>__u32</entry>
555 <entry><structfield>bytesused</structfield></entry>
556 <entry></entry>
557 <entry>The number of bytes occupied by the data in the
558buffer. It depends on the negotiated data format and may change with
559each buffer for compressed variable size data like JPEG images.
560Drivers must set this field when <structfield>type</structfield>
561refers to an input stream, applications when an output stream.</entry>
562 </row>
563 <row>
564 <entry>__u32</entry>
565 <entry><structfield>flags</structfield></entry>
566 <entry></entry>
567 <entry>Flags set by the application or driver, see <xref
568linkend="buffer-flags" />.</entry>
569 </row>
570 <row>
571 <entry>&v4l2-field;</entry>
572 <entry><structfield>field</structfield></entry>
573 <entry></entry>
574 <entry>Indicates the field order of the image in the
575buffer, see <xref linkend="v4l2-field" />. This field is not used when
576the buffer contains VBI data. Drivers must set it when
577<structfield>type</structfield> refers to an input stream,
578applications when an output stream.</entry>
579 </row>
580 <row>
581 <entry>struct timeval</entry>
582 <entry><structfield>timestamp</structfield></entry>
583 <entry></entry>
584 <entry><para>For input streams this is the
585system time (as returned by the <function>gettimeofday()</function>
586function) when the first data byte was captured. For output streams
587the data will not be displayed before this time, secondary to the
588nominal frame rate determined by the current video standard in
589enqueued order. Applications can for example zero this field to
590display frames as soon as possible. The driver stores the time at
591which the first data byte was actually sent out in the
592<structfield>timestamp</structfield> field. This permits
593applications to monitor the drift between the video and system
594clock.</para></entry>
595 </row>
596 <row>
597 <entry>&v4l2-timecode;</entry>
598 <entry><structfield>timecode</structfield></entry>
599 <entry></entry>
600 <entry>When <structfield>type</structfield> is
601<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
602<constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
603<structfield>flags</structfield>, this structure contains a frame
604timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
605mode the top and bottom field contain the same timecode.
606Timecodes are intended to help video editing and are typically recorded on
607video tapes, but also embedded in compressed formats like MPEG. This
608field is independent of the <structfield>timestamp</structfield> and
609<structfield>sequence</structfield> fields.</entry>
610 </row>
611 <row>
612 <entry>__u32</entry>
613 <entry><structfield>sequence</structfield></entry>
614 <entry></entry>
615 <entry>Set by the driver, counting the frames in the
616sequence.</entry>
617 </row>
618 <row>
619 <entry spanname="hspan"><para>In <link
620linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
621bottom field have the same sequence number. The count starts at zero
622and includes dropped or repeated frames. A dropped frame was received
623by an input device but could not be stored due to lack of free buffer
624space. A repeated frame was displayed again by an output device
625because the application did not pass new data in
626time.</para><para>Note this may count the frames received
627e.g. over USB, without taking into account the frames dropped by the
628remote hardware due to limited compression throughput or bus
629bandwidth. These devices identify by not enumerating any video
630standards, see <xref linkend="standard" />.</para></entry>
631 </row>
632 <row>
633 <entry>&v4l2-memory;</entry>
634 <entry><structfield>memory</structfield></entry>
635 <entry></entry>
636 <entry>This field must be set by applications and/or drivers
637in accordance with the selected I/O method.</entry>
638 </row>
639 <row>
640 <entry>union</entry>
641 <entry><structfield>m</structfield></entry>
642 </row>
643 <row>
644 <entry></entry>
645 <entry>__u32</entry>
646 <entry><structfield>offset</structfield></entry>
647 <entry>For the single-planar API and when
648<structfield>memory</structfield> is <constant>V4L2_MEMORY_MMAP</constant> this
649is the offset of the buffer from the start of the device memory. The value is
650returned by the driver and apart of serving as parameter to the &func-mmap;
651function not useful for applications. See <xref linkend="mmap" /> for details
652 </entry>
653 </row>
654 <row>
655 <entry></entry>
656 <entry>unsigned long</entry>
657 <entry><structfield>userptr</structfield></entry>
658 <entry>For the single-planar API and when
659<structfield>memory</structfield> is <constant>V4L2_MEMORY_USERPTR</constant>
660this is a pointer to the buffer (casted to unsigned long type) in virtual
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>
672 </row>
673 <row>
674 <entry>__u32</entry>
675 <entry><structfield>length</structfield></entry>
676 <entry></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>
681 </row>
682 <row>
683 <entry>__u32</entry>
684 <entry><structfield>input</structfield></entry>
685 <entry></entry>
686 <entry>Some video capture drivers support rapid and
687synchronous video input changes, a function useful for example in
688video surveillance applications. For this purpose applications set the
689<constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the
690number of a video input as in &v4l2-input; field
691<structfield>index</structfield>.</entry>
692 </row>
693 <row>
694 <entry>__u32</entry>
695 <entry><structfield>reserved</structfield></entry>
696 <entry></entry>
697 <entry>A place holder for future extensions and custom
698(driver defined) buffer types
699<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications
700should set this to 0.</entry>
701 </row>
702 </tbody>
703 </tgroup>
704 </table>
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
766 <table frame="none" pgwide="1" id="v4l2-buf-type">
767 <title>enum v4l2_buf_type</title>
768 <tgroup cols="3">
769 &cs-def;
770 <tbody valign="top">
771 <row>
772 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
773 <entry>1</entry>
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
782 linkend="capture" />.</entry>
783 </row>
784 <row>
785 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
786 <entry>2</entry>
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
795 linkend="output" />.</entry>
796 </row>
797 <row>
798 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
799 <entry>3</entry>
800 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
801 </row>
802 <row>
803 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
804 <entry>4</entry>
805 <entry>Buffer of a raw VBI capture stream, see <xref
806 linkend="raw-vbi" />.</entry>
807 </row>
808 <row>
809 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
810 <entry>5</entry>
811 <entry>Buffer of a raw VBI output stream, see <xref
812 linkend="raw-vbi" />.</entry>
813 </row>
814 <row>
815 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
816 <entry>6</entry>
817 <entry>Buffer of a sliced VBI capture stream, see <xref
818 linkend="sliced" />.</entry>
819 </row>
820 <row>
821 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
822 <entry>7</entry>
823 <entry>Buffer of a sliced VBI output stream, see <xref
824 linkend="sliced" />.</entry>
825 </row>
826 <row>
827 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
828 <entry>8</entry>
829 <entry>Buffer for video output overlay (OSD), see <xref
830 linkend="osd" />. Status: <link
831linkend="experimental">Experimental</link>.</entry>
832 </row>
833 <row>
834 <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
835 <entry>0x80</entry>
836 <entry>This and higher values are reserved for custom
837(driver defined) buffer types.</entry>
838 </row>
839 </tbody>
840 </tgroup>
841 </table>
842
843 <table frame="none" pgwide="1" id="buffer-flags">
844 <title>Buffer Flags</title>
845 <tgroup cols="3">
846 &cs-def;
847 <tbody valign="top">
848 <row>
849 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
850 <entry>0x0001</entry>
851 <entry>The buffer resides in device memory and has been mapped
852into the application's address space, see <xref linkend="mmap" /> for details.
853Drivers set or clear this flag when the
854<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
855 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
856 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
857 </row>
858 <row>
859 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
860 <entry>0x0002</entry>
861 <entry>Internally drivers maintain two buffer queues, an
862incoming and outgoing queue. When this flag is set, the buffer is
863currently on the incoming queue. It automatically moves to the
864outgoing queue after the buffer has been filled (capture devices) or
865displayed (output devices). Drivers set or clear this flag when the
866<constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
867(successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
868always set and after <constant>VIDIOC_DQBUF</constant> always
869cleared.</entry>
870 </row>
871 <row>
872 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
873 <entry>0x0004</entry>
874 <entry>When this flag is set, the buffer is currently on
875the outgoing queue, ready to be dequeued from the driver. Drivers set
876or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
877is called. After calling the <constant>VIDIOC_QBUF</constant> or
878<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
879buffer cannot be on both queues at the same time, the
880<constant>V4L2_BUF_FLAG_QUEUED</constant> and
881<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
882They can be both cleared however, then the buffer is in "dequeued"
883state, in the application domain to say so.</entry>
884 </row>
885 <row>
886 <entry><constant>V4L2_BUF_FLAG_ERROR</constant></entry>
887 <entry>0x0040</entry>
888 <entry>When this flag is set, the buffer has been dequeued
889 successfully, although the data might have been corrupted.
890 This is recoverable, streaming may continue as normal and
891 the buffer may be reused normally.
892 Drivers set this flag when the <constant>VIDIOC_DQBUF</constant>
893 ioctl is called.</entry>
894 </row>
895 <row>
896 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
897 <entry>0x0008</entry>
898 <entry>Drivers set or clear this flag when calling the
899<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
900capture devices when the buffer contains a compressed image which is a
901key frame (or field), &ie; can be decompressed on its own.</entry>
902 </row>
903 <row>
904 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
905 <entry>0x0010</entry>
906 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
907this flags predicted frames or fields which contain only differences to a
908previous key frame.</entry>
909 </row>
910 <row>
911 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
912 <entry>0x0020</entry>
913 <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
914 this is a bidirectional predicted frame or field. [ooc tbd]</entry>
915 </row>
916 <row>
917 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
918 <entry>0x0100</entry>
919 <entry>The <structfield>timecode</structfield> field is valid.
920Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
921ioctl is called.</entry>
922 </row>
923 <row>
924 <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry>
925 <entry>0x0200</entry>
926 <entry>The <structfield>input</structfield> field is valid.
927Applications set or clear this flag before calling the
928<constant>VIDIOC_QBUF</constant> ioctl.</entry>
929 </row>
930 </tbody>
931 </tgroup>
932 </table>
933
934 <table pgwide="1" frame="none" id="v4l2-memory">
935 <title>enum v4l2_memory</title>
936 <tgroup cols="3">
937 &cs-def;
938 <tbody valign="top">
939 <row>
940 <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
941 <entry>1</entry>
942 <entry>The buffer is used for <link linkend="mmap">memory
943mapping</link> I/O.</entry>
944 </row>
945 <row>
946 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
947 <entry>2</entry>
948 <entry>The buffer is used for <link linkend="userp">user
949pointer</link> I/O.</entry>
950 </row>
951 <row>
952 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
953 <entry>3</entry>
954 <entry>[to do]</entry>
955 </row>
956 </tbody>
957 </tgroup>
958 </table>
959
960 <section>
961 <title>Timecodes</title>
962
963 <para>The <structname>v4l2_timecode</structname> structure is
964designed to hold a <xref linkend="smpte12m" /> or similar timecode.
965(struct <structname>timeval</structname> timestamps are stored in
966&v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
967
968 <table frame="none" pgwide="1" id="v4l2-timecode">
969 <title>struct <structname>v4l2_timecode</structname></title>
970 <tgroup cols="3">
971 &cs-str;
972 <tbody valign="top">
973 <row>
974 <entry>__u32</entry>
975 <entry><structfield>type</structfield></entry>
976 <entry>Frame rate the timecodes are based on, see <xref
977 linkend="timecode-type" />.</entry>
978 </row>
979 <row>
980 <entry>__u32</entry>
981 <entry><structfield>flags</structfield></entry>
982 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
983 </row>
984 <row>
985 <entry>__u8</entry>
986 <entry><structfield>frames</structfield></entry>
987 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
988 type of timecode.</entry>
989 </row>
990 <row>
991 <entry>__u8</entry>
992 <entry><structfield>seconds</structfield></entry>
993 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
994 </row>
995 <row>
996 <entry>__u8</entry>
997 <entry><structfield>minutes</structfield></entry>
998 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
999 </row>
1000 <row>
1001 <entry>__u8</entry>
1002 <entry><structfield>hours</structfield></entry>
1003 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
1004 </row>
1005 <row>
1006 <entry>__u8</entry>
1007 <entry><structfield>userbits</structfield>[4]</entry>
1008 <entry>The "user group" bits from the timecode.</entry>
1009 </row>
1010 </tbody>
1011 </tgroup>
1012 </table>
1013
1014 <table frame="none" pgwide="1" id="timecode-type">
1015 <title>Timecode Types</title>
1016 <tgroup cols="3">
1017 &cs-def;
1018 <tbody valign="top">
1019 <row>
1020 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
1021 <entry>1</entry>
1022 <entry>24 frames per second, i.&nbsp;e. film.</entry>
1023 </row>
1024 <row>
1025 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
1026 <entry>2</entry>
1027 <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
1028 </row>
1029 <row>
1030 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
1031 <entry>3</entry>
1032 <entry>30 frames per second, &ie; NTSC video.</entry>
1033 </row>
1034 <row>
1035 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
1036 <entry>4</entry>
1037 <entry></entry>
1038 </row>
1039 <row>
1040 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
1041 <entry>5</entry>
1042 <entry></entry>
1043 </row>
1044 </tbody>
1045 </tgroup>
1046 </table>
1047
1048 <table frame="none" pgwide="1" id="timecode-flags">
1049 <title>Timecode Flags</title>
1050 <tgroup cols="3">
1051 &cs-def;
1052 <tbody valign="top">
1053 <row>
1054 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
1055 <entry>0x0001</entry>
1056 <entry>Indicates "drop frame" semantics for counting frames
1057in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
1058each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
1059count.</entry>
1060 </row>
1061 <row>
1062 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
1063 <entry>0x0002</entry>
1064 <entry>The "color frame" flag.</entry>
1065 </row>
1066 <row>
1067 <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
1068 <entry>0x000C</entry>
1069 <entry>Field mask for the "binary group flags".</entry>
1070 </row>
1071 <row>
1072 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
1073 <entry>0x0000</entry>
1074 <entry>Unspecified format.</entry>
1075 </row>
1076 <row>
1077 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
1078 <entry>0x0008</entry>
1079 <entry>8-bit ISO characters.</entry>
1080 </row>
1081 </tbody>
1082 </tgroup>
1083 </table>
1084 </section>
1085 </section>
1086
1087 <section id="field-order">
1088 <title>Field Order</title>
1089
1090 <para>We have to distinguish between progressive and interlaced
1091video. Progressive video transmits all lines of a video image
1092sequentially. Interlaced video divides an image into two fields,
1093containing only the odd and even lines of the image, respectively.
1094Alternating the so called odd and even field are transmitted, and due
1095to a small delay between fields a cathode ray TV displays the lines
1096interleaved, yielding the original frame. This curious technique was
1097invented because at refresh rates similar to film the image would
1098fade out too quickly. Transmitting fields reduces the flicker without
1099the necessity of doubling the frame rate and with it the bandwidth
1100required for each channel.</para>
1101
1102 <para>It is important to understand a video camera does not expose
1103one frame at a time, merely transmitting the frames separated into
1104fields. The fields are in fact captured at two different instances in
1105time. An object on screen may well move between one field and the
1106next. For applications analysing motion it is of paramount importance
1107to recognize which field of a frame is older, the <emphasis>temporal
1108order</emphasis>.</para>
1109
1110 <para>When the driver provides or accepts images field by field
1111rather than interleaved, it is also important applications understand
1112how the fields combine to frames. We distinguish between top (aka odd) and
1113bottom (aka even) fields, the <emphasis>spatial order</emphasis>: The first line
1114of the top field is the first line of an interlaced frame, the first
1115line of the bottom field is the second line of that frame.</para>
1116
1117 <para>However because fields were captured one after the other,
1118arguing whether a frame commences with the top or bottom field is
1119pointless. Any two successive top and bottom, or bottom and top fields
1120yield a valid frame. Only when the source was progressive to begin
1121with, &eg; when transferring film to video, two fields may come from
1122the same frame, creating a natural order.</para>
1123
1124 <para>Counter to intuition the top field is not necessarily the
1125older field. Whether the older field contains the top or bottom lines
1126is a convention determined by the video standard. Hence the
1127distinction between temporal and spatial order of fields. The diagrams
1128below should make this clearer.</para>
1129
1130 <para>All video capture and output devices must report the current
1131field order. Some drivers may permit the selection of a different
1132order, to this end applications initialize the
1133<structfield>field</structfield> field of &v4l2-pix-format; before
1134calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
1135have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
1136
1137 <table frame="none" pgwide="1" id="v4l2-field">
1138 <title>enum v4l2_field</title>
1139 <tgroup cols="3">
1140 &cs-def;
1141 <tbody valign="top">
1142 <row>
1143 <entry><constant>V4L2_FIELD_ANY</constant></entry>
1144 <entry>0</entry>
1145 <entry>Applications request this field order when any
1146one of the <constant>V4L2_FIELD_NONE</constant>,
1147<constant>V4L2_FIELD_TOP</constant>,
1148<constant>V4L2_FIELD_BOTTOM</constant>, or
1149<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
1150Drivers choose depending on hardware capabilities or e.&nbsp;g. the
1151requested image size, and return the actual field order. &v4l2-buffer;
1152<structfield>field</structfield> can never be
1153<constant>V4L2_FIELD_ANY</constant>.</entry>
1154 </row>
1155 <row>
1156 <entry><constant>V4L2_FIELD_NONE</constant></entry>
1157 <entry>1</entry>
1158 <entry>Images are in progressive format, not interlaced.
1159The driver may also indicate this order when it cannot distinguish
1160between <constant>V4L2_FIELD_TOP</constant> and
1161<constant>V4L2_FIELD_BOTTOM</constant>.</entry>
1162 </row>
1163 <row>
1164 <entry><constant>V4L2_FIELD_TOP</constant></entry>
1165 <entry>2</entry>
1166 <entry>Images consist of the top (aka odd) field only.</entry>
1167 </row>
1168 <row>
1169 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1170 <entry>3</entry>
1171 <entry>Images consist of the bottom (aka even) field only.
1172Applications may wish to prevent a device from capturing interlaced
1173images because they will have "comb" or "feathering" artefacts around
1174moving objects.</entry>
1175 </row>
1176 <row>
1177 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1178 <entry>4</entry>
1179 <entry>Images contain both fields, interleaved line by
1180line. The temporal order of the fields (whether the top or bottom
1181field is first transmitted) depends on the current video standard.
1182M/NTSC transmits the bottom field first, all other standards the top
1183field first.</entry>
1184 </row>
1185 <row>
1186 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1187 <entry>5</entry>
1188 <entry>Images contain both fields, the top field lines
1189are stored first in memory, immediately followed by the bottom field
1190lines. Fields are always stored in temporal order, the older one first
1191in memory. Image sizes refer to the frame, not fields.</entry>
1192 </row>
1193 <row>
1194 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1195 <entry>6</entry>
1196 <entry>Images contain both fields, the bottom field
1197lines are stored first in memory, immediately followed by the top
1198field lines. Fields are always stored in temporal order, the older one
1199first in memory. Image sizes refer to the frame, not fields.</entry>
1200 </row>
1201 <row>
1202 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1203 <entry>7</entry>
1204 <entry>The two fields of a frame are passed in separate
1205buffers, in temporal order, &ie; the older one first. To indicate the field
1206parity (whether the current field is a top or bottom field) the driver
1207or application, depending on data direction, must set &v4l2-buffer;
1208<structfield>field</structfield> to
1209<constant>V4L2_FIELD_TOP</constant> or
1210<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1211to build a frame. If fields are successive, without any dropped fields
1212between them (fields can drop individually), can be determined from
1213the &v4l2-buffer; <structfield>sequence</structfield> field. Image
1214sizes refer to the frame, not fields. This format cannot be selected
1215when using the read/write I/O method.<!-- Where it's indistinguishable
1216from V4L2_FIELD_SEQ_*. --></entry>
1217 </row>
1218 <row>
1219 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1220 <entry>8</entry>
1221 <entry>Images contain both fields, interleaved line by
1222line, top field first. The top field is transmitted first.</entry>
1223 </row>
1224 <row>
1225 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1226 <entry>9</entry>
1227 <entry>Images contain both fields, interleaved line by
1228line, top field first. The bottom field is transmitted first.</entry>
1229 </row>
1230 </tbody>
1231 </tgroup>
1232 </table>
1233
1234 <figure id="fieldseq-tb">
1235 <title>Field Order, Top Field First Transmitted</title>
1236 <mediaobject>
1237 <imageobject>
1238 <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1239 </imageobject>
1240 <imageobject>
1241 <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1242 </imageobject>
1243 </mediaobject>
1244 </figure>
1245
1246 <figure id="fieldseq-bt">
1247 <title>Field Order, Bottom Field First Transmitted</title>
1248 <mediaobject>
1249 <imageobject>
1250 <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1251 </imageobject>
1252 <imageobject>
1253 <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1254 </imageobject>
1255 </mediaobject>
1256 </figure>
1257 </section>
1258
1259 <!--
1260Local Variables:
1261mode: sgml
1262sgml-parent-document: "v4l2.sgml"
1263indent-tabs-mode: nil
1264End:
1265 -->
diff --git a/Documentation/DocBook/media/v4l/keytable.c.xml b/Documentation/DocBook/media/v4l/keytable.c.xml
new file mode 100644
index 000000000000..d53254a3be15
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/keytable.c.xml
@@ -0,0 +1,172 @@
1<programlisting>
2/* keytable.c - This program allows checking/replacing keys at IR
3
4 Copyright (C) 2006-2009 Mauro Carvalho Chehab &lt;mchehab@infradead.org&gt;
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation, version 2 of the License.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14 */
15
16#include &lt;ctype.h&gt;
17#include &lt;errno.h&gt;
18#include &lt;fcntl.h&gt;
19#include &lt;stdio.h&gt;
20#include &lt;stdlib.h&gt;
21#include &lt;string.h&gt;
22#include &lt;linux/input.h&gt;
23#include &lt;sys/ioctl.h&gt;
24
25#include "parse.h"
26
27void prtcode (int *codes)
28{
29 struct parse_key *p;
30
31 for (p=keynames;p-&gt;name!=NULL;p++) {
32 if (p-&gt;value == (unsigned)codes[1]) {
33 printf("scancode 0x%04x = %s (0x%02x)\n", codes[0], p-&gt;name, codes[1]);
34 return;
35 }
36 }
37
38 if (isprint (codes[1]))
39 printf("scancode %d = '%c' (0x%02x)\n", codes[0], codes[1], codes[1]);
40 else
41 printf("scancode %d = 0x%02x\n", codes[0], codes[1]);
42}
43
44int parse_code(char *string)
45{
46 struct parse_key *p;
47
48 for (p=keynames;p-&gt;name!=NULL;p++) {
49 if (!strcasecmp(p-&gt;name, string)) {
50 return p-&gt;value;
51 }
52 }
53 return -1;
54}
55
56int main (int argc, char *argv[])
57{
58 int fd;
59 unsigned int i, j;
60 int codes[2];
61
62 if (argc&lt;2 || argc&gt;4) {
63 printf ("usage: %s &lt;device&gt; to get table; or\n"
64 " %s &lt;device&gt; &lt;scancode&gt; &lt;keycode&gt;\n"
65 " %s &lt;device&gt; &lt;keycode_file&gt;\n",*argv,*argv,*argv);
66 return -1;
67 }
68
69 if ((fd = open(argv[1], O_RDONLY)) &lt; 0) {
70 perror("Couldn't open input device");
71 return(-1);
72 }
73
74 if (argc==4) {
75 int value;
76
77 value=parse_code(argv[3]);
78
79 if (value==-1) {
80 value = strtol(argv[3], NULL, 0);
81 if (errno)
82 perror("value");
83 }
84
85 codes [0] = (unsigned) strtol(argv[2], NULL, 0);
86 codes [1] = (unsigned) value;
87
88 if(ioctl(fd, EVIOCSKEYCODE, codes))
89 perror ("EVIOCSKEYCODE");
90
91 if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
92 prtcode(codes);
93 return 0;
94 }
95
96 if (argc==3) {
97 FILE *fin;
98 int value;
99 char *scancode, *keycode, s[2048];
100
101 fin=fopen(argv[2],"r");
102 if (fin==NULL) {
103 perror ("opening keycode file");
104 return -1;
105 }
106
107 /* Clears old table */
108 for (j = 0; j &lt; 256; j++) {
109 for (i = 0; i &lt; 256; i++) {
110 codes[0] = (j &lt;&lt; 8) | i;
111 codes[1] = KEY_RESERVED;
112 ioctl(fd, EVIOCSKEYCODE, codes);
113 }
114 }
115
116 while (fgets(s,sizeof(s),fin)) {
117 scancode=strtok(s,"\n\t =:");
118 if (!scancode) {
119 perror ("parsing input file scancode");
120 return -1;
121 }
122 if (!strcasecmp(scancode, "scancode")) {
123 scancode = strtok(NULL,"\n\t =:");
124 if (!scancode) {
125 perror ("parsing input file scancode");
126 return -1;
127 }
128 }
129
130 keycode=strtok(NULL,"\n\t =:(");
131 if (!keycode) {
132 perror ("parsing input file keycode");
133 return -1;
134 }
135
136 // printf ("parsing %s=%s:", scancode, keycode);
137 value=parse_code(keycode);
138 // printf ("\tvalue=%d\n",value);
139
140 if (value==-1) {
141 value = strtol(keycode, NULL, 0);
142 if (errno)
143 perror("value");
144 }
145
146 codes [0] = (unsigned) strtol(scancode, NULL, 0);
147 codes [1] = (unsigned) value;
148
149 // printf("\t%04x=%04x\n",codes[0], codes[1]);
150 if(ioctl(fd, EVIOCSKEYCODE, codes)) {
151 fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]);
152 perror ("EVIOCSKEYCODE");
153 }
154
155 if(ioctl(fd, EVIOCGKEYCODE, codes)==0)
156 prtcode(codes);
157 }
158 return 0;
159 }
160
161 /* Get scancode table */
162 for (j = 0; j &lt; 256; j++) {
163 for (i = 0; i &lt; 256; i++) {
164 codes[0] = (j &lt;&lt; 8) | i;
165 if (!ioctl(fd, EVIOCGKEYCODE, codes) &amp;&amp; codes[1] != KEY_RESERVED)
166 prtcode(codes);
167 }
168 }
169 return 0;
170}
171
172</programlisting>
diff --git a/Documentation/DocBook/media/v4l/libv4l.xml b/Documentation/DocBook/media/v4l/libv4l.xml
new file mode 100644
index 000000000000..3cb10ec51929
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/libv4l.xml
@@ -0,0 +1,167 @@
1<title>Libv4l Userspace Library</title>
2<section id="libv4l-introduction">
3 <title>Introduction</title>
4
5 <para>libv4l is a collection of libraries which adds a thin abstraction
6layer on top of video4linux2 devices. The purpose of this (thin) layer
7is to make it easy for application writers to support a wide variety of
8devices without having to write separate code for different devices in the
9same class.</para>
10<para>An example of using libv4l is provided by
11<link linkend='v4l2grab-example'>v4l2grab</link>.
12</para>
13
14 <para>libv4l consists of 3 different libraries:</para>
15 <section>
16 <title>libv4lconvert</title>
17
18 <para>libv4lconvert is a library that converts several
19different pixelformats found in V4L2 drivers into a few common RGB and
20YUY formats.</para>
21 <para>It currently accepts the following V4L2 driver formats:
22<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>,
23<link linkend="V4L2-PIX-FMT-HM12"><constant>V4L2_PIX_FMT_HM12</constant></link>,
24<link linkend="V4L2-PIX-FMT-JPEG"><constant>V4L2_PIX_FMT_JPEG</constant></link>,
25<link linkend="V4L2-PIX-FMT-MJPEG"><constant>V4L2_PIX_FMT_MJPEG</constant></link>,
26<link linkend="V4L2-PIX-FMT-MR97310A"><constant>V4L2_PIX_FMT_MR97310A</constant></link>,
27<link linkend="V4L2-PIX-FMT-OV511"><constant>V4L2_PIX_FMT_OV511</constant></link>,
28<link linkend="V4L2-PIX-FMT-OV518"><constant>V4L2_PIX_FMT_OV518</constant></link>,
29<link linkend="V4L2-PIX-FMT-PAC207"><constant>V4L2_PIX_FMT_PAC207</constant></link>,
30<link linkend="V4L2-PIX-FMT-PJPG"><constant>V4L2_PIX_FMT_PJPG</constant></link>,
31<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>,
32<link linkend="V4L2-PIX-FMT-SBGGR8"><constant>V4L2_PIX_FMT_SBGGR8</constant></link>,
33<link linkend="V4L2-PIX-FMT-SGBRG8"><constant>V4L2_PIX_FMT_SGBRG8</constant></link>,
34<link linkend="V4L2-PIX-FMT-SGRBG8"><constant>V4L2_PIX_FMT_SGRBG8</constant></link>,
35<link linkend="V4L2-PIX-FMT-SN9C10X"><constant>V4L2_PIX_FMT_SN9C10X</constant></link>,
36<link linkend="V4L2-PIX-FMT-SN9C20X-I420"><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></link>,
37<link linkend="V4L2-PIX-FMT-SPCA501"><constant>V4L2_PIX_FMT_SPCA501</constant></link>,
38<link linkend="V4L2-PIX-FMT-SPCA505"><constant>V4L2_PIX_FMT_SPCA505</constant></link>,
39<link linkend="V4L2-PIX-FMT-SPCA508"><constant>V4L2_PIX_FMT_SPCA508</constant></link>,
40<link linkend="V4L2-PIX-FMT-SPCA561"><constant>V4L2_PIX_FMT_SPCA561</constant></link>,
41<link linkend="V4L2-PIX-FMT-SQ905C"><constant>V4L2_PIX_FMT_SQ905C</constant></link>,
42<constant>V4L2_PIX_FMT_SRGGB8</constant>,
43<link linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link>,
44<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>,
45<link linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link>,
46<link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>,
47and <link linkend="V4L2-PIX-FMT-YVYU"><constant>V4L2_PIX_FMT_YVYU</constant></link>.
48</para>
49 <para>Later on libv4lconvert was expanded to also be able to do
50various video processing functions to improve webcam video quality.
51The video processing is split in to 2 parts: libv4lconvert/control and
52libv4lconvert/processing.</para>
53
54 <para>The control part is used to offer video controls which can
55be used to control the video processing functions made available by
56 libv4lconvert/processing. These controls are stored application wide
57(until reboot) by using a persistent shared memory object.</para>
58
59 <para>libv4lconvert/processing offers the actual video
60processing functionality.</para>
61 </section>
62 <section>
63 <title>libv4l1</title>
64 <para>This library offers functions that can be used to quickly
65make v4l1 applications work with v4l2 devices. These functions work exactly
66like the normal open/close/etc, except that libv4l1 does full emulation of
67the v4l1 api on top of v4l2 drivers, in case of v4l1 drivers it
68will just pass calls through.</para>
69 <para>Since those functions are emulations of the old V4L1 API,
70it shouldn't be used for new applications.</para>
71 </section>
72 <section>
73 <title>libv4l2</title>
74 <para>This library should be used for all modern V4L2
75applications.</para>
76 <para>It provides handles to call V4L2 open/ioctl/close/poll
77methods. Instead of just providing the raw output of the device, it enhances
78the calls in the sense that it will use libv4lconvert to provide more video
79formats and to enhance the image quality.</para>
80 <para>In most cases, libv4l2 just passes the calls directly
81through to the v4l2 driver, intercepting the calls to
82<link linkend='vidioc-g-fmt'><constant>VIDIOC_TRY_FMT</constant></link>,
83<link linkend='vidioc-g-fmt'><constant>VIDIOC_G_FMT</constant></link>
84<link linkend='vidioc-g-fmt'><constant>VIDIOC_S_FMT</constant></link>
85<link linkend='vidioc-enum-framesizes'><constant>VIDIOC_ENUM_FRAMESIZES</constant></link>
86and <link linkend='vidioc-enum-frameintervals'><constant>VIDIOC_ENUM_FRAMEINTERVALS</constant></link>
87in order to emulate the formats
88<link linkend="V4L2-PIX-FMT-BGR24"><constant>V4L2_PIX_FMT_BGR24</constant></link>,
89<link linkend="V4L2-PIX-FMT-RGB24"><constant>V4L2_PIX_FMT_RGB24</constant></link>,
90<link linkend="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></link>,
91and <link linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link>,
92if they aren't available in the driver.
93<link linkend='vidioc-enum-fmt'><constant>VIDIOC_ENUM_FMT</constant></link>
94keeps enumerating the hardware supported formats, plus the emulated formats
95offered by libv4l at the end.
96</para>
97 <section id="libv4l-ops">
98 <title>Libv4l device control functions</title>
99 <para>The common file operation methods are provided by
100libv4l.</para>
101 <para>Those functions operate just like glibc
102open/close/dup/ioctl/read/mmap/munmap:</para>
103<itemizedlist><listitem>
104 <para>int v4l2_open(const char *file, int oflag,
105...) -
106operates like the standard <link linkend='func-open'>open()</link> function.
107</para></listitem><listitem>
108 <para>int v4l2_close(int fd) -
109operates like the standard <link linkend='func-close'>close()</link> function.
110</para></listitem><listitem>
111 <para>int v4l2_dup(int fd) -
112operates like the standard dup() function, duplicating a file handler.
113</para></listitem><listitem>
114 <para>int v4l2_ioctl (int fd, unsigned long int request, ...) -
115operates like the standard <link linkend='func-ioctl'>ioctl()</link> function.
116</para></listitem><listitem>
117 <para>int v4l2_read (int fd, void* buffer, size_t n) -
118operates like the standard <link linkend='func-read'>read()</link> function.
119</para></listitem><listitem>
120 <para>void v4l2_mmap(void *start, size_t length, int prot, int flags, int fd, int64_t offset); -
121operates like the standard <link linkend='func-mmap'>mmap()</link> function.
122</para></listitem><listitem>
123 <para>int v4l2_munmap(void *_start, size_t length); -
124operates like the standard <link linkend='func-munmap'>munmap()</link> function.
125</para></listitem>
126</itemizedlist>
127 <para>Those functions provide additional control:</para>
128<itemizedlist><listitem>
129 <para>int v4l2_fd_open(int fd, int v4l2_flags) -
130opens an already opened fd for further use through v4l2lib and possibly
131modify libv4l2's default behavior through the v4l2_flags argument.
132Currently, v4l2_flags can be <constant>V4L2_DISABLE_CONVERSION</constant>,
133to disable format conversion.
134</para></listitem><listitem>
135 <para>int v4l2_set_control(int fd, int cid, int value) -
136This function takes a value of 0 - 65535, and then scales that range to
137the actual range of the given v4l control id, and then if the cid exists
138and is not locked sets the cid to the scaled value.
139</para></listitem><listitem>
140 <para>int v4l2_get_control(int fd, int cid) -
141This function returns a value of 0 - 65535, scaled to from the actual range
142of the given v4l control id. when the cid does not exist, could not be
143accessed for some reason, or some error occurred 0 is returned.
144</para></listitem>
145</itemizedlist>
146 </section>
147 </section>
148 <section>
149
150 <title>v4l1compat.so wrapper library</title>
151
152 <para>This library intercepts calls to
153open/close/ioctl/mmap/mmunmap operations and redirects them to the libv4l
154counterparts, by using LD_PRELOAD=/usr/lib/v4l1compat.so. It also
155emulates V4L1 calls via V4L2 API.</para>
156 <para>It allows usage of binary legacy applications that
157still don't use libv4l.</para>
158 </section>
159
160</section>
161<!--
162Local Variables:
163mode: sgml
164sgml-parent-document: "v4l2.sgml"
165indent-tabs-mode: nil
166End:
167-->
diff --git a/Documentation/DocBook/media/v4l/lirc_device_interface.xml b/Documentation/DocBook/media/v4l/lirc_device_interface.xml
new file mode 100644
index 000000000000..0e0453f39e73
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/lirc_device_interface.xml
@@ -0,0 +1,251 @@
1<section id="lirc_dev">
2<title>LIRC Device Interface</title>
3
4
5<section id="lirc_dev_intro">
6<title>Introduction</title>
7
8<para>The LIRC device interface is a bi-directional interface for
9transporting raw IR data between userspace and kernelspace. Fundamentally,
10it is just a chardev (/dev/lircX, for X = 0, 1, 2, ...), with a number
11of standard struct file_operations defined on it. With respect to
12transporting raw IR data to and fro, the essential fops are read, write
13and ioctl.</para>
14
15<para>Example dmesg output upon a driver registering w/LIRC:</para>
16 <blockquote>
17 <para>$ dmesg |grep lirc_dev</para>
18 <para>lirc_dev: IR Remote Control driver registered, major 248</para>
19 <para>rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0</para>
20 </blockquote>
21
22<para>What you should see for a chardev:</para>
23 <blockquote>
24 <para>$ ls -l /dev/lirc*</para>
25 <para>crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0</para>
26 </blockquote>
27</section>
28
29<section id="lirc_read">
30<title>LIRC read fop</title>
31
32<para>The lircd userspace daemon reads raw IR data from the LIRC chardev. The
33exact format of the data depends on what modes a driver supports, and what
34mode has been selected. lircd obtains supported modes and sets the active mode
35via the ioctl interface, detailed at <xref linkend="lirc_ioctl"/>. The generally
36preferred mode is LIRC_MODE_MODE2, in which packets containing an int value
37describing an IR signal are read from the chardev.</para>
38
39<para>See also <ulink url="http://www.lirc.org/html/technical.html">http://www.lirc.org/html/technical.html</ulink> for more info.</para>
40</section>
41
42<section id="lirc_write">
43<title>LIRC write fop</title>
44
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
47data must start and end with a pulse, therefore, the data must always include
48an uneven number of samples. The write function must block until the data has
49been transmitted by the hardware.</para>
50</section>
51
52<section id="lirc_ioctl">
53<title>LIRC ioctl fop</title>
54
55<para>The LIRC device's ioctl definition is bound by the ioctl function
56definition of struct file_operations, leaving us with an unsigned int
57for the ioctl command and an unsigned long for the arg. For the purposes
58of ioctl portability across 32-bit and 64-bit, these values are capped
59to their 32-bit sizes.</para>
60
61<para>The following ioctls can be used to change specific hardware settings.
62In general each driver should have a default set of settings. The driver
63implementation is expected to re-apply the default settings when the device
64is closed by user-space, so that every application opening the device can rely
65on working with the default settings initially.</para>
66
67<variablelist>
68 <varlistentry>
69 <term>LIRC_GET_FEATURES</term>
70 <listitem>
71 <para>Obviously, get the underlying hardware device's features. If a driver
72 does not announce support of certain features, calling of the corresponding
73 ioctls is undefined.</para>
74 </listitem>
75 </varlistentry>
76 <varlistentry>
77 <term>LIRC_GET_SEND_MODE</term>
78 <listitem>
79 <para>Get supported transmit mode. Only LIRC_MODE_PULSE is supported by lircd.</para>
80 </listitem>
81 </varlistentry>
82 <varlistentry>
83 <term>LIRC_GET_REC_MODE</term>
84 <listitem>
85 <para>Get supported receive modes. Only LIRC_MODE_MODE2 and LIRC_MODE_LIRCCODE
86 are supported by lircd.</para>
87 </listitem>
88 </varlistentry>
89 <varlistentry>
90 <term>LIRC_GET_SEND_CARRIER</term>
91 <listitem>
92 <para>Get carrier frequency (in Hz) currently used for transmit.</para>
93 </listitem>
94 </varlistentry>
95 <varlistentry>
96 <term>LIRC_GET_REC_CARRIER</term>
97 <listitem>
98 <para>Get carrier frequency (in Hz) currently used for IR reception.</para>
99 </listitem>
100 </varlistentry>
101 <varlistentry>
102 <term>LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE</term>
103 <listitem>
104 <para>Get/set the duty cycle (from 0 to 100) of the carrier signal. Currently,
105 no special meaning is defined for 0 or 100, but this could be used to switch
106 off carrier generation in the future, so these values should be reserved.</para>
107 </listitem>
108 </varlistentry>
109 <varlistentry>
110 <term>LIRC_GET_REC_RESOLUTION</term>
111 <listitem>
112 <para>Some receiver have maximum resolution which is defined by internal
113 sample rate or data format limitations. E.g. it's common that signals can
114 only be reported in 50 microsecond steps. This integer value is used by
115 lircd to automatically adjust the aeps tolerance value in the lircd
116 config file.</para>
117 </listitem>
118 </varlistentry>
119 <varlistentry>
120 <term>LIRC_GET_M{IN,AX}_TIMEOUT</term>
121 <listitem>
122 <para>Some devices have internal timers that can be used to detect when
123 there's no IR activity for a long time. This can help lircd in detecting
124 that a IR signal is finished and can speed up the decoding process.
125 Returns an integer value with the minimum/maximum timeout that can be
126 set. Some devices have a fixed timeout, in that case both ioctls will
127 return the same value even though the timeout cannot be changed.</para>
128 </listitem>
129 </varlistentry>
130 <varlistentry>
131 <term>LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE}</term>
132 <listitem>
133 <para>Some devices are able to filter out spikes in the incoming signal
134 using given filter rules. These ioctls return the hardware capabilities
135 that describe the bounds of the possible filters. Filter settings depend
136 on the IR protocols that are expected. lircd derives the settings from
137 all protocols definitions found in its config file.</para>
138 </listitem>
139 </varlistentry>
140 <varlistentry>
141 <term>LIRC_GET_LENGTH</term>
142 <listitem>
143 <para>Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE).
144 Reads on the device must be done in blocks matching the bit count.
145 The bit could should be rounded up so that it matches full bytes.</para>
146 </listitem>
147 </varlistentry>
148 <varlistentry>
149 <term>LIRC_SET_{SEND,REC}_MODE</term>
150 <listitem>
151 <para>Set send/receive mode. Largely obsolete for send, as only
152 LIRC_MODE_PULSE is supported.</para>
153 </listitem>
154 </varlistentry>
155 <varlistentry>
156 <term>LIRC_SET_{SEND,REC}_CARRIER</term>
157 <listitem>
158 <para>Set send/receive carrier (in Hz).</para>
159 </listitem>
160 </varlistentry>
161 <varlistentry>
162 <term>LIRC_SET_TRANSMITTER_MASK</term>
163 <listitem>
164 <para>This enables the given set of transmitters. The first transmitter
165 is encoded by the least significant bit, etc. When an invalid bit mask
166 is given, i.e. a bit is set, even though the device does not have so many
167 transitters, then this ioctl returns the number of available transitters
168 and does nothing otherwise.</para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
172 <term>LIRC_SET_REC_TIMEOUT</term>
173 <listitem>
174 <para>Sets the integer value for IR inactivity timeout (cf.
175 LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 (if
176 supported by the hardware) disables all hardware timeouts and data should
177 be reported as soon as possible. If the exact value cannot be set, then
178 the next possible value _greater_ than the given value should be set.</para>
179 </listitem>
180 </varlistentry>
181 <varlistentry>
182 <term>LIRC_SET_REC_TIMEOUT_REPORTS</term>
183 <listitem>
184 <para>Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By
185 default, timeout reports should be turned off.</para>
186 </listitem>
187 </varlistentry>
188 <varlistentry>
189 <term>LIRC_SET_REC_FILTER_{,PULSE,SPACE}</term>
190 <listitem>
191 <para>Pulses/spaces shorter than this are filtered out by hardware. If
192 filters cannot be set independently for pulse/space, the corresponding
193 ioctls must return an error and LIRC_SET_REC_FILTER shall be used instead.</para>
194 </listitem>
195 </varlistentry>
196 <varlistentry>
197 <term>LIRC_SET_MEASURE_CARRIER_MODE</term>
198 <listitem>
199 <para>Enable (1)/disable (0) measure mode. If enabled, from the next key
200 press on, the driver will send LIRC_MODE2_FREQUENCY packets. By default
201 this should be turned off.</para>
202 </listitem>
203 </varlistentry>
204 <varlistentry>
205 <term>LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE</term>
206 <listitem>
207 <para>To set a range use LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE
208 with the lower bound first and later LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER
209 with the upper bound.</para>
210 </listitem>
211 </varlistentry>
212 <varlistentry>
213 <term>LIRC_NOTIFY_DECODE</term>
214 <listitem>
215 <para>This ioctl is called by lircd whenever a successful decoding of an
216 incoming IR signal could be done. This can be used by supporting hardware
217 to give visual feedback to the user e.g. by flashing a LED.</para>
218 </listitem>
219 </varlistentry>
220 <varlistentry>
221 <term>LIRC_SETUP_{START,END}</term>
222 <listitem>
223 <para>Setting of several driver parameters can be optimized by encapsulating
224 the according ioctl calls with LIRC_SETUP_START/LIRC_SETUP_END. When a
225 driver receives a LIRC_SETUP_START ioctl it can choose to not commit
226 further setting changes to the hardware until a LIRC_SETUP_END is received.
227 But this is open to the driver implementation and every driver must also
228 handle parameter changes which are not encapsulated by LIRC_SETUP_START
229 and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para>
230 </listitem>
231 </varlistentry>
232 <varlistentry>
233 <term>LIRC_SET_WIDEBAND_RECEIVER</term>
234 <listitem>
235 <para>Some receivers are equipped with special wide band receiver which is intended
236 to be used to learn output of existing remote.
237 Calling that ioctl with (1) will enable it, and with (0) disable it.
238 This might be useful of receivers that have otherwise narrow band receiver
239 that prevents them to be used with some remotes.
240 Wide band receiver might also be more precise
241 On the other hand its disadvantage it usually reduced range of reception.
242 Note: wide band receiver might be implictly enabled if you enable
243 carrier reports. In that case it will be disabled as soon as you disable
244 carrier reports. Trying to disable wide band receiver while carrier
245 reports are active will do nothing.</para>
246 </listitem>
247 </varlistentry>
248</variablelist>
249
250</section>
251</section>
diff --git a/Documentation/DocBook/media/v4l/media-controller.xml b/Documentation/DocBook/media/v4l/media-controller.xml
new file mode 100644
index 000000000000..873ac3a621f0
--- /dev/null
+++ b/Documentation/DocBook/media/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-func-open;
82 &sub-media-func-close;
83 &sub-media-func-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/media/v4l/media-func-close.xml b/Documentation/DocBook/media/v4l/media-func-close.xml
new file mode 100644
index 000000000000..be149c802aeb
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/media-func-ioctl.xml b/Documentation/DocBook/media/v4l/media-func-ioctl.xml
new file mode 100644
index 000000000000..bda8604de15c
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/media-func-open.xml b/Documentation/DocBook/media/v4l/media-func-open.xml
new file mode 100644
index 000000000000..f7df034dc9ed
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/media-ioc-device-info.xml b/Documentation/DocBook/media/v4l/media-ioc-device-info.xml
new file mode 100644
index 000000000000..1f3237351bba
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml
new file mode 100644
index 000000000000..576b68b33f2c
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/media-ioc-enum-links.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
new file mode 100644
index 000000000000..d2fc73ef8d56
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/media-ioc-setup-link.xml b/Documentation/DocBook/media/v4l/media-ioc-setup-link.xml
new file mode 100644
index 000000000000..cec97af4dab4
--- /dev/null
+++ b/Documentation/DocBook/media/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_SETUP_LINK</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/media/v4l/nv12mt.gif b/Documentation/DocBook/media/v4l/nv12mt.gif
new file mode 100644
index 000000000000..ef2d4cf8367b
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/nv12mt.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/nv12mt_example.gif b/Documentation/DocBook/media/v4l/nv12mt_example.gif
new file mode 100644
index 000000000000..df81d68108ee
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/nv12mt_example.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/pipeline.pdf b/Documentation/DocBook/media/v4l/pipeline.pdf
new file mode 100644
index 000000000000..ee3e37f04b6a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pipeline.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/pipeline.png b/Documentation/DocBook/media/v4l/pipeline.png
new file mode 100644
index 000000000000..f19b86c2c24d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pipeline.png
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/pixfmt-grey.xml b/Documentation/DocBook/media/v4l/pixfmt-grey.xml
new file mode 100644
index 000000000000..3b72bc6b2de7
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-grey.xml
@@ -0,0 +1,70 @@
1 <refentry id="V4L2-PIX-FMT-GREY">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_GREY ('GREY')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_GREY</constant></refname>
8 <refpurpose>Grey-scale image</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is a grey-scale image. It is really a degenerate
14Y'CbCr format which simply contains no Cb or Cr data.</para>
15
16 <example>
17 <title><constant>V4L2_PIX_FMT_GREY</constant> 4 &times; 4
18pixel image</title>
19
20 <formalpara>
21 <title>Byte Order.</title>
22 <para>Each cell is one byte.
23 <informaltable frame="none">
24 <tgroup cols="5" align="center">
25 <colspec align="left" colwidth="2*" />
26 <tbody valign="top">
27 <row>
28 <entry>start&nbsp;+&nbsp;0:</entry>
29 <entry>Y'<subscript>00</subscript></entry>
30 <entry>Y'<subscript>01</subscript></entry>
31 <entry>Y'<subscript>02</subscript></entry>
32 <entry>Y'<subscript>03</subscript></entry>
33 </row>
34 <row>
35 <entry>start&nbsp;+&nbsp;4:</entry>
36 <entry>Y'<subscript>10</subscript></entry>
37 <entry>Y'<subscript>11</subscript></entry>
38 <entry>Y'<subscript>12</subscript></entry>
39 <entry>Y'<subscript>13</subscript></entry>
40 </row>
41 <row>
42 <entry>start&nbsp;+&nbsp;8:</entry>
43 <entry>Y'<subscript>20</subscript></entry>
44 <entry>Y'<subscript>21</subscript></entry>
45 <entry>Y'<subscript>22</subscript></entry>
46 <entry>Y'<subscript>23</subscript></entry>
47 </row>
48 <row>
49 <entry>start&nbsp;+&nbsp;12:</entry>
50 <entry>Y'<subscript>30</subscript></entry>
51 <entry>Y'<subscript>31</subscript></entry>
52 <entry>Y'<subscript>32</subscript></entry>
53 <entry>Y'<subscript>33</subscript></entry>
54 </row>
55 </tbody>
56 </tgroup>
57 </informaltable>
58 </para>
59 </formalpara>
60 </example>
61 </refsect1>
62 </refentry>
63
64 <!--
65Local Variables:
66mode: sgml
67sgml-parent-document: "pixfmt.sgml"
68indent-tabs-mode: nil
69End:
70 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-m420.xml b/Documentation/DocBook/media/v4l/pixfmt-m420.xml
new file mode 100644
index 000000000000..ce4bc019e5c0
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-m420.xml
@@ -0,0 +1,147 @@
1 <refentry id="V4L2-PIX-FMT-M420">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_M420 ('M420')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_M420</constant></refname>
8 <refpurpose>Format with &frac12; horizontal and vertical chroma
9 resolution, also known as YUV 4:2:0. Hybrid plane line-interleaved
10 layout.</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>M420 is a YUV format with &frac12; horizontal and vertical chroma
16 subsampling (YUV 4:2:0). Pixels are organized as interleaved luma and
17 chroma planes. Two lines of luma data are followed by one line of chroma
18 data.</para>
19 <para>The luma plane has one byte per pixel. The chroma plane contains
20 interleaved CbCr pixels subsampled by &frac12; in the horizontal and
21 vertical directions. Each CbCr pair belongs to four pixels. For example,
22Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
23Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
24Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.</para>
25
26 <para>All line lengths are identical: if the Y lines include pad bytes
27 so do the CbCr lines.</para>
28
29 <example>
30 <title><constant>V4L2_PIX_FMT_M420</constant> 4 &times; 4
31pixel image</title>
32
33 <formalpara>
34 <title>Byte Order.</title>
35 <para>Each cell is one byte.
36 <informaltable frame="none">
37 <tgroup cols="5" align="center">
38 <colspec align="left" colwidth="2*" />
39 <tbody valign="top">
40 <row>
41 <entry>start&nbsp;+&nbsp;0:</entry>
42 <entry>Y'<subscript>00</subscript></entry>
43 <entry>Y'<subscript>01</subscript></entry>
44 <entry>Y'<subscript>02</subscript></entry>
45 <entry>Y'<subscript>03</subscript></entry>
46 </row>
47 <row>
48 <entry>start&nbsp;+&nbsp;4:</entry>
49 <entry>Y'<subscript>10</subscript></entry>
50 <entry>Y'<subscript>11</subscript></entry>
51 <entry>Y'<subscript>12</subscript></entry>
52 <entry>Y'<subscript>13</subscript></entry>
53 </row>
54 <row>
55 <entry>start&nbsp;+&nbsp;8:</entry>
56 <entry>Cb<subscript>00</subscript></entry>
57 <entry>Cr<subscript>00</subscript></entry>
58 <entry>Cb<subscript>01</subscript></entry>
59 <entry>Cr<subscript>01</subscript></entry>
60 </row>
61 <row>
62 <entry>start&nbsp;+&nbsp;16:</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>start&nbsp;+&nbsp;20:</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>
76 <entry>start&nbsp;+&nbsp;24:</entry>
77 <entry>Cb<subscript>10</subscript></entry>
78 <entry>Cr<subscript>10</subscript></entry>
79 <entry>Cb<subscript>11</subscript></entry>
80 <entry>Cr<subscript>11</subscript></entry>
81 </row>
82 </tbody>
83 </tgroup>
84 </informaltable>
85 </para>
86 </formalpara>
87
88 <formalpara>
89 <title>Color Sample Location.</title>
90 <para>
91 <informaltable frame="none">
92 <tgroup cols="7" align="center">
93 <tbody valign="top">
94 <row>
95 <entry></entry>
96 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
97 <entry>2</entry><entry></entry><entry>3</entry>
98 </row>
99 <row>
100 <entry>0</entry>
101 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
102 <entry>Y</entry><entry></entry><entry>Y</entry>
103 </row>
104 <row>
105 <entry></entry>
106 <entry></entry><entry>C</entry><entry></entry><entry></entry>
107 <entry></entry><entry>C</entry><entry></entry>
108 </row>
109 <row>
110 <entry>1</entry>
111 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
112 <entry>Y</entry><entry></entry><entry>Y</entry>
113 </row>
114 <row>
115 <entry></entry>
116 </row>
117 <row>
118 <entry>2</entry>
119 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
120 <entry>Y</entry><entry></entry><entry>Y</entry>
121 </row>
122 <row>
123 <entry></entry>
124 <entry></entry><entry>C</entry><entry></entry><entry></entry>
125 <entry></entry><entry>C</entry><entry></entry>
126 </row>
127 <row>
128 <entry>3</entry>
129 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
130 <entry>Y</entry><entry></entry><entry>Y</entry>
131 </row>
132 </tbody>
133 </tgroup>
134 </informaltable>
135 </para>
136 </formalpara>
137 </example>
138 </refsect1>
139 </refentry>
140
141 <!--
142Local Variables:
143mode: sgml
144sgml-parent-document: "pixfmt.sgml"
145indent-tabs-mode: nil
146End:
147 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml
new file mode 100644
index 000000000000..873f67035181
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml
@@ -0,0 +1,151 @@
1 <refentry>
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname id="V4L2-PIX-FMT-NV12"><constant>V4L2_PIX_FMT_NV12</constant></refname>
8 <refname id="V4L2-PIX-FMT-NV21"><constant>V4L2_PIX_FMT_NV21</constant></refname>
9 <refpurpose>Formats with &frac12; horizontal and vertical
10chroma resolution, also known as YUV 4:2:0. One luminance and one
11chrominance plane with alternating chroma samples as opposed to
12<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
13 </refnamediv>
14 <refsect1>
15 <title>Description</title>
16
17 <para>These are two-plane versions of the YUV 4:2:0 format.
18The three components are separated into two sub-images or planes. The
19Y plane is first. The Y plane has one byte per pixel. For
20<constant>V4L2_PIX_FMT_NV12</constant>, a combined CbCr plane
21immediately follows the Y plane in memory. The CbCr plane is the same
22width, in bytes, as the Y plane (and of the image), but is half as
23tall in pixels. Each CbCr pair belongs to four pixels. For example,
24Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
25Y'<subscript>00</subscript>, Y'<subscript>01</subscript>,
26Y'<subscript>10</subscript>, Y'<subscript>11</subscript>.
27<constant>V4L2_PIX_FMT_NV21</constant> is the same except the Cb and
28Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
29
30 <para>If the Y plane has pad bytes after each row, then the
31CbCr plane has as many pad bytes after its rows.</para>
32
33 <example>
34 <title><constant>V4L2_PIX_FMT_NV12</constant> 4 &times; 4
35pixel 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>start&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>start&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>start&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>start&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>start&nbsp;+&nbsp;16:</entry>
74 <entry>Cb<subscript>00</subscript></entry>
75 <entry>Cr<subscript>00</subscript></entry>
76 <entry>Cb<subscript>01</subscript></entry>
77 <entry>Cr<subscript>01</subscript></entry>
78 </row>
79 <row>
80 <entry>start&nbsp;+&nbsp;20:</entry>
81 <entry>Cb<subscript>10</subscript></entry>
82 <entry>Cr<subscript>10</subscript></entry>
83 <entry>Cb<subscript>11</subscript></entry>
84 <entry>Cr<subscript>11</subscript></entry>
85 </row>
86 </tbody>
87 </tgroup>
88 </informaltable>
89 </para>
90 </formalpara>
91
92 <formalpara>
93 <title>Color Sample Location.</title>
94 <para>
95 <informaltable frame="none">
96 <tgroup cols="7" align="center">
97 <tbody valign="top">
98 <row>
99 <entry></entry>
100 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
101 <entry>2</entry><entry></entry><entry>3</entry>
102 </row>
103 <row>
104 <entry>0</entry>
105 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
106 <entry>Y</entry><entry></entry><entry>Y</entry>
107 </row>
108 <row>
109 <entry></entry>
110 <entry></entry><entry>C</entry><entry></entry><entry></entry>
111 <entry></entry><entry>C</entry><entry></entry>
112 </row>
113 <row>
114 <entry>1</entry>
115 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
116 <entry>Y</entry><entry></entry><entry>Y</entry>
117 </row>
118 <row>
119 <entry></entry>
120 </row>
121 <row>
122 <entry>2</entry>
123 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
124 <entry>Y</entry><entry></entry><entry>Y</entry>
125 </row>
126 <row>
127 <entry></entry>
128 <entry></entry><entry>C</entry><entry></entry><entry></entry>
129 <entry></entry><entry>C</entry><entry></entry>
130 </row>
131 <row>
132 <entry>3</entry>
133 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
134 <entry>Y</entry><entry></entry><entry>Y</entry>
135 </row>
136 </tbody>
137 </tgroup>
138 </informaltable>
139 </para>
140 </formalpara>
141 </example>
142 </refsect1>
143 </refentry>
144
145 <!--
146Local Variables:
147mode: sgml
148sgml-parent-document: "pixfmt.sgml"
149indent-tabs-mode: nil
150End:
151 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml
new file mode 100644
index 000000000000..c9e166d9ded8
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/pixfmt-nv12mt.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml
new file mode 100644
index 000000000000..7a2855a526c1
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/pixfmt-nv16.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml
new file mode 100644
index 000000000000..26094035fc04
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml
@@ -0,0 +1,174 @@
1 <refentry>
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname id="V4L2-PIX-FMT-NV16"><constant>V4L2_PIX_FMT_NV16</constant></refname>
8 <refname id="V4L2-PIX-FMT-NV61"><constant>V4L2_PIX_FMT_NV61</constant></refname>
9 <refpurpose>Formats with &frac12; horizontal
10chroma resolution, also known as YUV 4:2:2. One luminance and one
11chrominance plane with alternating chroma samples as opposed to
12<constant>V4L2_PIX_FMT_YVU420</constant></refpurpose>
13 </refnamediv>
14 <refsect1>
15 <title>Description</title>
16
17 <para>These are two-plane versions of the YUV 4:2:2 format.
18The three components are separated into two sub-images or planes. The
19Y plane is first. The Y plane has one byte per pixel. For
20<constant>V4L2_PIX_FMT_NV16</constant>, a combined CbCr plane
21immediately follows the Y plane in memory. The CbCr plane is the same
22width and height, in bytes, as the Y plane (and of the image).
23Each CbCr pair belongs to two pixels. For example,
24Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to
25Y'<subscript>00</subscript>, Y'<subscript>01</subscript>.
26<constant>V4L2_PIX_FMT_NV61</constant> is the same except the Cb and
27Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para>
28
29 <para>If the Y plane has pad bytes after each row, then the
30CbCr plane has as many pad bytes after its rows.</para>
31
32 <example>
33 <title><constant>V4L2_PIX_FMT_NV16</constant> 4 &times; 4
34pixel image</title>
35
36 <formalpara>
37 <title>Byte Order.</title>
38 <para>Each cell is one byte.
39 <informaltable frame="none">
40 <tgroup cols="5" align="center">
41 <colspec align="left" colwidth="2*" />
42 <tbody valign="top">
43 <row>
44 <entry>start&nbsp;+&nbsp;0:</entry>
45 <entry>Y'<subscript>00</subscript></entry>
46 <entry>Y'<subscript>01</subscript></entry>
47 <entry>Y'<subscript>02</subscript></entry>
48 <entry>Y'<subscript>03</subscript></entry>
49 </row>
50 <row>
51 <entry>start&nbsp;+&nbsp;4:</entry>
52 <entry>Y'<subscript>10</subscript></entry>
53 <entry>Y'<subscript>11</subscript></entry>
54 <entry>Y'<subscript>12</subscript></entry>
55 <entry>Y'<subscript>13</subscript></entry>
56 </row>
57 <row>
58 <entry>start&nbsp;+&nbsp;8:</entry>
59 <entry>Y'<subscript>20</subscript></entry>
60 <entry>Y'<subscript>21</subscript></entry>
61 <entry>Y'<subscript>22</subscript></entry>
62 <entry>Y'<subscript>23</subscript></entry>
63 </row>
64 <row>
65 <entry>start&nbsp;+&nbsp;12:</entry>
66 <entry>Y'<subscript>30</subscript></entry>
67 <entry>Y'<subscript>31</subscript></entry>
68 <entry>Y'<subscript>32</subscript></entry>
69 <entry>Y'<subscript>33</subscript></entry>
70 </row>
71 <row>
72 <entry>start&nbsp;+&nbsp;16:</entry>
73 <entry>Cb<subscript>00</subscript></entry>
74 <entry>Cr<subscript>00</subscript></entry>
75 <entry>Cb<subscript>01</subscript></entry>
76 <entry>Cr<subscript>01</subscript></entry>
77 </row>
78 <row>
79 <entry>start&nbsp;+&nbsp;20:</entry>
80 <entry>Cb<subscript>10</subscript></entry>
81 <entry>Cr<subscript>10</subscript></entry>
82 <entry>Cb<subscript>11</subscript></entry>
83 <entry>Cr<subscript>11</subscript></entry>
84 </row>
85 <row>
86 <entry>start&nbsp;+&nbsp;24:</entry>
87 <entry>Cb<subscript>20</subscript></entry>
88 <entry>Cr<subscript>20</subscript></entry>
89 <entry>Cb<subscript>21</subscript></entry>
90 <entry>Cr<subscript>21</subscript></entry>
91 </row>
92 <row>
93 <entry>start&nbsp;+&nbsp;28:</entry>
94 <entry>Cb<subscript>30</subscript></entry>
95 <entry>Cr<subscript>30</subscript></entry>
96 <entry>Cb<subscript>31</subscript></entry>
97 <entry>Cr<subscript>31</subscript></entry>
98 </row>
99 </tbody>
100 </tgroup>
101 </informaltable>
102 </para>
103 </formalpara>
104
105 <formalpara>
106 <title>Color Sample Location.</title>
107 <para>
108 <informaltable frame="none">
109 <tgroup cols="7" align="center">
110 <tbody valign="top">
111 <row>
112 <entry></entry>
113 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
114 <entry>2</entry><entry></entry><entry>3</entry>
115 </row>
116 <row>
117 <entry>0</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 <entry></entry><entry>C</entry><entry></entry><entry></entry>
124 <entry></entry><entry>C</entry><entry></entry>
125 </row>
126 <row>
127 <entry>1</entry>
128 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
129 <entry>Y</entry><entry></entry><entry>Y</entry>
130 </row>
131 <row>
132 <entry></entry>
133 <entry></entry><entry>C</entry><entry></entry><entry></entry>
134 <entry></entry><entry>C</entry><entry></entry>
135 </row>
136 <row>
137 <entry></entry>
138 </row>
139 <row>
140 <entry>2</entry>
141 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
142 <entry>Y</entry><entry></entry><entry>Y</entry>
143 </row>
144 <row>
145 <entry></entry>
146 <entry></entry><entry>C</entry><entry></entry><entry></entry>
147 <entry></entry><entry>C</entry><entry></entry>
148 </row>
149 <row>
150 <entry>3</entry>
151 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
152 <entry>Y</entry><entry></entry><entry>Y</entry>
153 </row>
154 <row>
155 <entry></entry>
156 <entry></entry><entry>C</entry><entry></entry><entry></entry>
157 <entry></entry><entry>C</entry><entry></entry>
158 </row>
159 </tbody>
160 </tgroup>
161 </informaltable>
162 </para>
163 </formalpara>
164 </example>
165 </refsect1>
166 </refentry>
167
168 <!--
169Local Variables:
170mode: sgml
171sgml-parent-document: "pixfmt.sgml"
172indent-tabs-mode: nil
173End:
174 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
new file mode 100644
index 000000000000..4db272b8a0d3
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-packed-rgb.xml
@@ -0,0 +1,940 @@
1<refentry id="packed-rgb">
2 <refmeta>
3 <refentrytitle>Packed RGB formats</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname>Packed RGB formats</refname>
8 <refpurpose>Packed RGB formats</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>These formats are designed to match the pixel formats of
14typical PC graphics frame buffers. They occupy 8, 16, 24 or 32 bits
15per pixel. These are all packed-pixel formats, meaning all the data
16for a pixel lie next to each other in memory.</para>
17
18 <para>When one of these formats is used, drivers shall report the
19colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para>
20
21 <table pgwide="1" frame="none" id="rgb-formats">
22 <title>Packed RGB Image Formats</title>
23 <tgroup cols="37" align="center">
24 <colspec colname="id" align="left" />
25 <colspec colname="fourcc" />
26 <colspec colname="bit" />
27
28 <colspec colnum="4" colname="b07" align="center" />
29 <colspec colnum="5" colname="b06" align="center" />
30 <colspec colnum="6" colname="b05" align="center" />
31 <colspec colnum="7" colname="b04" align="center" />
32 <colspec colnum="8" colname="b03" align="center" />
33 <colspec colnum="9" colname="b02" align="center" />
34 <colspec colnum="10" colname="b01" align="center" />
35 <colspec colnum="11" colname="b00" align="center" />
36
37 <colspec colnum="13" colname="b17" align="center" />
38 <colspec colnum="14" colname="b16" align="center" />
39 <colspec colnum="15" colname="b15" align="center" />
40 <colspec colnum="16" colname="b14" align="center" />
41 <colspec colnum="17" colname="b13" align="center" />
42 <colspec colnum="18" colname="b12" align="center" />
43 <colspec colnum="19" colname="b11" align="center" />
44 <colspec colnum="20" colname="b10" align="center" />
45
46 <colspec colnum="22" colname="b27" align="center" />
47 <colspec colnum="23" colname="b26" align="center" />
48 <colspec colnum="24" colname="b25" align="center" />
49 <colspec colnum="25" colname="b24" align="center" />
50 <colspec colnum="26" colname="b23" align="center" />
51 <colspec colnum="27" colname="b22" align="center" />
52 <colspec colnum="28" colname="b21" align="center" />
53 <colspec colnum="29" colname="b20" align="center" />
54
55 <colspec colnum="31" colname="b37" align="center" />
56 <colspec colnum="32" colname="b36" align="center" />
57 <colspec colnum="33" colname="b35" align="center" />
58 <colspec colnum="34" colname="b34" align="center" />
59 <colspec colnum="35" colname="b33" align="center" />
60 <colspec colnum="36" colname="b32" align="center" />
61 <colspec colnum="37" colname="b31" align="center" />
62 <colspec colnum="38" colname="b30" align="center" />
63
64 <spanspec namest="b07" nameend="b00" spanname="b0" />
65 <spanspec namest="b17" nameend="b10" spanname="b1" />
66 <spanspec namest="b27" nameend="b20" spanname="b2" />
67 <spanspec namest="b37" nameend="b30" spanname="b3" />
68 <thead>
69 <row>
70 <entry>Identifier</entry>
71 <entry>Code</entry>
72 <entry>&nbsp;</entry>
73 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
74 <entry spanname="b1">Byte&nbsp;1</entry>
75 <entry spanname="b2">Byte&nbsp;2</entry>
76 <entry spanname="b3">Byte&nbsp;3</entry>
77 </row>
78 <row>
79 <entry>&nbsp;</entry>
80 <entry>&nbsp;</entry>
81 <entry>Bit</entry>
82 <entry>7</entry>
83 <entry>6</entry>
84 <entry>5</entry>
85 <entry>4</entry>
86 <entry>3</entry>
87 <entry>2</entry>
88 <entry>1</entry>
89 <entry>0</entry>
90 <entry>&nbsp;</entry>
91 <entry>7</entry>
92 <entry>6</entry>
93 <entry>5</entry>
94 <entry>4</entry>
95 <entry>3</entry>
96 <entry>2</entry>
97 <entry>1</entry>
98 <entry>0</entry>
99 <entry>&nbsp;</entry>
100 <entry>7</entry>
101 <entry>6</entry>
102 <entry>5</entry>
103 <entry>4</entry>
104 <entry>3</entry>
105 <entry>2</entry>
106 <entry>1</entry>
107 <entry>0</entry>
108 <entry>&nbsp;</entry>
109 <entry>7</entry>
110 <entry>6</entry>
111 <entry>5</entry>
112 <entry>4</entry>
113 <entry>3</entry>
114 <entry>2</entry>
115 <entry>1</entry>
116 <entry>0</entry>
117 </row>
118 </thead>
119 <tbody valign="top">
120 <row id="V4L2-PIX-FMT-RGB332">
121 <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
122 <entry>'RGB1'</entry>
123 <entry></entry>
124 <entry>b<subscript>1</subscript></entry>
125 <entry>b<subscript>0</subscript></entry>
126 <entry>g<subscript>2</subscript></entry>
127 <entry>g<subscript>1</subscript></entry>
128 <entry>g<subscript>0</subscript></entry>
129 <entry>r<subscript>2</subscript></entry>
130 <entry>r<subscript>1</subscript></entry>
131 <entry>r<subscript>0</subscript></entry>
132 </row>
133 <row id="V4L2-PIX-FMT-RGB444">
134 <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
135 <entry>'R444'</entry>
136 <entry></entry>
137 <entry>g<subscript>3</subscript></entry>
138 <entry>g<subscript>2</subscript></entry>
139 <entry>g<subscript>1</subscript></entry>
140 <entry>g<subscript>0</subscript></entry>
141 <entry>b<subscript>3</subscript></entry>
142 <entry>b<subscript>2</subscript></entry>
143 <entry>b<subscript>1</subscript></entry>
144 <entry>b<subscript>0</subscript></entry>
145 <entry></entry>
146 <entry>a<subscript>3</subscript></entry>
147 <entry>a<subscript>2</subscript></entry>
148 <entry>a<subscript>1</subscript></entry>
149 <entry>a<subscript>0</subscript></entry>
150 <entry>r<subscript>3</subscript></entry>
151 <entry>r<subscript>2</subscript></entry>
152 <entry>r<subscript>1</subscript></entry>
153 <entry>r<subscript>0</subscript></entry>
154 </row>
155 <row id="V4L2-PIX-FMT-RGB555">
156 <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
157 <entry>'RGBO'</entry>
158 <entry></entry>
159 <entry>g<subscript>2</subscript></entry>
160 <entry>g<subscript>1</subscript></entry>
161 <entry>g<subscript>0</subscript></entry>
162 <entry>r<subscript>4</subscript></entry>
163 <entry>r<subscript>3</subscript></entry>
164 <entry>r<subscript>2</subscript></entry>
165 <entry>r<subscript>1</subscript></entry>
166 <entry>r<subscript>0</subscript></entry>
167 <entry></entry>
168 <entry>a</entry>
169 <entry>b<subscript>4</subscript></entry>
170 <entry>b<subscript>3</subscript></entry>
171 <entry>b<subscript>2</subscript></entry>
172 <entry>b<subscript>1</subscript></entry>
173 <entry>b<subscript>0</subscript></entry>
174 <entry>g<subscript>4</subscript></entry>
175 <entry>g<subscript>3</subscript></entry>
176 </row>
177 <row id="V4L2-PIX-FMT-RGB565">
178 <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
179 <entry>'RGBP'</entry>
180 <entry></entry>
181 <entry>g<subscript>2</subscript></entry>
182 <entry>g<subscript>1</subscript></entry>
183 <entry>g<subscript>0</subscript></entry>
184 <entry>r<subscript>4</subscript></entry>
185 <entry>r<subscript>3</subscript></entry>
186 <entry>r<subscript>2</subscript></entry>
187 <entry>r<subscript>1</subscript></entry>
188 <entry>r<subscript>0</subscript></entry>
189 <entry></entry>
190 <entry>b<subscript>4</subscript></entry>
191 <entry>b<subscript>3</subscript></entry>
192 <entry>b<subscript>2</subscript></entry>
193 <entry>b<subscript>1</subscript></entry>
194 <entry>b<subscript>0</subscript></entry>
195 <entry>g<subscript>5</subscript></entry>
196 <entry>g<subscript>4</subscript></entry>
197 <entry>g<subscript>3</subscript></entry>
198 </row>
199 <row id="V4L2-PIX-FMT-RGB555X">
200 <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
201 <entry>'RGBQ'</entry>
202 <entry></entry>
203 <entry>a</entry>
204 <entry>b<subscript>4</subscript></entry>
205 <entry>b<subscript>3</subscript></entry>
206 <entry>b<subscript>2</subscript></entry>
207 <entry>b<subscript>1</subscript></entry>
208 <entry>b<subscript>0</subscript></entry>
209 <entry>g<subscript>4</subscript></entry>
210 <entry>g<subscript>3</subscript></entry>
211 <entry></entry>
212 <entry>g<subscript>2</subscript></entry>
213 <entry>g<subscript>1</subscript></entry>
214 <entry>g<subscript>0</subscript></entry>
215 <entry>r<subscript>4</subscript></entry>
216 <entry>r<subscript>3</subscript></entry>
217 <entry>r<subscript>2</subscript></entry>
218 <entry>r<subscript>1</subscript></entry>
219 <entry>r<subscript>0</subscript></entry>
220 </row>
221 <row id="V4L2-PIX-FMT-RGB565X">
222 <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
223 <entry>'RGBR'</entry>
224 <entry></entry>
225 <entry>b<subscript>4</subscript></entry>
226 <entry>b<subscript>3</subscript></entry>
227 <entry>b<subscript>2</subscript></entry>
228 <entry>b<subscript>1</subscript></entry>
229 <entry>b<subscript>0</subscript></entry>
230 <entry>g<subscript>5</subscript></entry>
231 <entry>g<subscript>4</subscript></entry>
232 <entry>g<subscript>3</subscript></entry>
233 <entry></entry>
234 <entry>g<subscript>2</subscript></entry>
235 <entry>g<subscript>1</subscript></entry>
236 <entry>g<subscript>0</subscript></entry>
237 <entry>r<subscript>4</subscript></entry>
238 <entry>r<subscript>3</subscript></entry>
239 <entry>r<subscript>2</subscript></entry>
240 <entry>r<subscript>1</subscript></entry>
241 <entry>r<subscript>0</subscript></entry>
242 </row>
243 <row id="V4L2-PIX-FMT-BGR666">
244 <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
245 <entry>'BGRH'</entry>
246 <entry></entry>
247 <entry>b<subscript>5</subscript></entry>
248 <entry>b<subscript>4</subscript></entry>
249 <entry>b<subscript>3</subscript></entry>
250 <entry>b<subscript>2</subscript></entry>
251 <entry>b<subscript>1</subscript></entry>
252 <entry>b<subscript>0</subscript></entry>
253 <entry>g<subscript>5</subscript></entry>
254 <entry>g<subscript>4</subscript></entry>
255 <entry></entry>
256 <entry>g<subscript>3</subscript></entry>
257 <entry>g<subscript>2</subscript></entry>
258 <entry>g<subscript>1</subscript></entry>
259 <entry>g<subscript>0</subscript></entry>
260 <entry>r<subscript>5</subscript></entry>
261 <entry>r<subscript>4</subscript></entry>
262 <entry>r<subscript>3</subscript></entry>
263 <entry>r<subscript>2</subscript></entry>
264 <entry></entry>
265 <entry>r<subscript>1</subscript></entry>
266 <entry>r<subscript>0</subscript></entry>
267 <entry></entry>
268 <entry></entry>
269 <entry></entry>
270 <entry></entry>
271 <entry></entry>
272 <entry></entry>
273 <entry></entry>
274 <entry></entry>
275 <entry></entry>
276 <entry></entry>
277 <entry></entry>
278 <entry></entry>
279 <entry></entry>
280 <entry></entry>
281 </row>
282 <row id="V4L2-PIX-FMT-BGR24">
283 <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
284 <entry>'BGR3'</entry>
285 <entry></entry>
286 <entry>b<subscript>7</subscript></entry>
287 <entry>b<subscript>6</subscript></entry>
288 <entry>b<subscript>5</subscript></entry>
289 <entry>b<subscript>4</subscript></entry>
290 <entry>b<subscript>3</subscript></entry>
291 <entry>b<subscript>2</subscript></entry>
292 <entry>b<subscript>1</subscript></entry>
293 <entry>b<subscript>0</subscript></entry>
294 <entry></entry>
295 <entry>g<subscript>7</subscript></entry>
296 <entry>g<subscript>6</subscript></entry>
297 <entry>g<subscript>5</subscript></entry>
298 <entry>g<subscript>4</subscript></entry>
299 <entry>g<subscript>3</subscript></entry>
300 <entry>g<subscript>2</subscript></entry>
301 <entry>g<subscript>1</subscript></entry>
302 <entry>g<subscript>0</subscript></entry>
303 <entry></entry>
304 <entry>r<subscript>7</subscript></entry>
305 <entry>r<subscript>6</subscript></entry>
306 <entry>r<subscript>5</subscript></entry>
307 <entry>r<subscript>4</subscript></entry>
308 <entry>r<subscript>3</subscript></entry>
309 <entry>r<subscript>2</subscript></entry>
310 <entry>r<subscript>1</subscript></entry>
311 <entry>r<subscript>0</subscript></entry>
312 </row>
313 <row id="V4L2-PIX-FMT-RGB24">
314 <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
315 <entry>'RGB3'</entry>
316 <entry></entry>
317 <entry>r<subscript>7</subscript></entry>
318 <entry>r<subscript>6</subscript></entry>
319 <entry>r<subscript>5</subscript></entry>
320 <entry>r<subscript>4</subscript></entry>
321 <entry>r<subscript>3</subscript></entry>
322 <entry>r<subscript>2</subscript></entry>
323 <entry>r<subscript>1</subscript></entry>
324 <entry>r<subscript>0</subscript></entry>
325 <entry></entry>
326 <entry>g<subscript>7</subscript></entry>
327 <entry>g<subscript>6</subscript></entry>
328 <entry>g<subscript>5</subscript></entry>
329 <entry>g<subscript>4</subscript></entry>
330 <entry>g<subscript>3</subscript></entry>
331 <entry>g<subscript>2</subscript></entry>
332 <entry>g<subscript>1</subscript></entry>
333 <entry>g<subscript>0</subscript></entry>
334 <entry></entry>
335 <entry>b<subscript>7</subscript></entry>
336 <entry>b<subscript>6</subscript></entry>
337 <entry>b<subscript>5</subscript></entry>
338 <entry>b<subscript>4</subscript></entry>
339 <entry>b<subscript>3</subscript></entry>
340 <entry>b<subscript>2</subscript></entry>
341 <entry>b<subscript>1</subscript></entry>
342 <entry>b<subscript>0</subscript></entry>
343 </row>
344 <row id="V4L2-PIX-FMT-BGR32">
345 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
346 <entry>'BGR4'</entry>
347 <entry></entry>
348 <entry>b<subscript>7</subscript></entry>
349 <entry>b<subscript>6</subscript></entry>
350 <entry>b<subscript>5</subscript></entry>
351 <entry>b<subscript>4</subscript></entry>
352 <entry>b<subscript>3</subscript></entry>
353 <entry>b<subscript>2</subscript></entry>
354 <entry>b<subscript>1</subscript></entry>
355 <entry>b<subscript>0</subscript></entry>
356 <entry></entry>
357 <entry>g<subscript>7</subscript></entry>
358 <entry>g<subscript>6</subscript></entry>
359 <entry>g<subscript>5</subscript></entry>
360 <entry>g<subscript>4</subscript></entry>
361 <entry>g<subscript>3</subscript></entry>
362 <entry>g<subscript>2</subscript></entry>
363 <entry>g<subscript>1</subscript></entry>
364 <entry>g<subscript>0</subscript></entry>
365 <entry></entry>
366 <entry>r<subscript>7</subscript></entry>
367 <entry>r<subscript>6</subscript></entry>
368 <entry>r<subscript>5</subscript></entry>
369 <entry>r<subscript>4</subscript></entry>
370 <entry>r<subscript>3</subscript></entry>
371 <entry>r<subscript>2</subscript></entry>
372 <entry>r<subscript>1</subscript></entry>
373 <entry>r<subscript>0</subscript></entry>
374 <entry></entry>
375 <entry>a<subscript>7</subscript></entry>
376 <entry>a<subscript>6</subscript></entry>
377 <entry>a<subscript>5</subscript></entry>
378 <entry>a<subscript>4</subscript></entry>
379 <entry>a<subscript>3</subscript></entry>
380 <entry>a<subscript>2</subscript></entry>
381 <entry>a<subscript>1</subscript></entry>
382 <entry>a<subscript>0</subscript></entry>
383 </row>
384 <row id="V4L2-PIX-FMT-RGB32">
385 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
386 <entry>'RGB4'</entry>
387 <entry></entry>
388 <entry>r<subscript>7</subscript></entry>
389 <entry>r<subscript>6</subscript></entry>
390 <entry>r<subscript>5</subscript></entry>
391 <entry>r<subscript>4</subscript></entry>
392 <entry>r<subscript>3</subscript></entry>
393 <entry>r<subscript>2</subscript></entry>
394 <entry>r<subscript>1</subscript></entry>
395 <entry>r<subscript>0</subscript></entry>
396 <entry></entry>
397 <entry>g<subscript>7</subscript></entry>
398 <entry>g<subscript>6</subscript></entry>
399 <entry>g<subscript>5</subscript></entry>
400 <entry>g<subscript>4</subscript></entry>
401 <entry>g<subscript>3</subscript></entry>
402 <entry>g<subscript>2</subscript></entry>
403 <entry>g<subscript>1</subscript></entry>
404 <entry>g<subscript>0</subscript></entry>
405 <entry></entry>
406 <entry>b<subscript>7</subscript></entry>
407 <entry>b<subscript>6</subscript></entry>
408 <entry>b<subscript>5</subscript></entry>
409 <entry>b<subscript>4</subscript></entry>
410 <entry>b<subscript>3</subscript></entry>
411 <entry>b<subscript>2</subscript></entry>
412 <entry>b<subscript>1</subscript></entry>
413 <entry>b<subscript>0</subscript></entry>
414 <entry></entry>
415 <entry>a<subscript>7</subscript></entry>
416 <entry>a<subscript>6</subscript></entry>
417 <entry>a<subscript>5</subscript></entry>
418 <entry>a<subscript>4</subscript></entry>
419 <entry>a<subscript>3</subscript></entry>
420 <entry>a<subscript>2</subscript></entry>
421 <entry>a<subscript>1</subscript></entry>
422 <entry>a<subscript>0</subscript></entry>
423 </row>
424 </tbody>
425 </tgroup>
426 </table>
427
428 <para>Bit 7 is the most significant bit. The value of a = alpha
429bits is undefined when reading from the driver, ignored when writing
430to the driver, except when alpha blending has been negotiated for a
431<link linkend="overlay">Video Overlay</link> or <link
432linkend="osd">Video Output Overlay</link>.</para>
433
434 <example>
435 <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
436image</title>
437
438 <formalpara>
439 <title>Byte Order.</title>
440 <para>Each cell is one byte.
441 <informaltable frame="none">
442 <tgroup cols="13" align="center">
443 <colspec align="left" colwidth="2*" />
444 <tbody valign="top">
445 <row>
446 <entry>start&nbsp;+&nbsp;0:</entry>
447 <entry>B<subscript>00</subscript></entry>
448 <entry>G<subscript>00</subscript></entry>
449 <entry>R<subscript>00</subscript></entry>
450 <entry>B<subscript>01</subscript></entry>
451 <entry>G<subscript>01</subscript></entry>
452 <entry>R<subscript>01</subscript></entry>
453 <entry>B<subscript>02</subscript></entry>
454 <entry>G<subscript>02</subscript></entry>
455 <entry>R<subscript>02</subscript></entry>
456 <entry>B<subscript>03</subscript></entry>
457 <entry>G<subscript>03</subscript></entry>
458 <entry>R<subscript>03</subscript></entry>
459 </row>
460 <row>
461 <entry>start&nbsp;+&nbsp;12:</entry>
462 <entry>B<subscript>10</subscript></entry>
463 <entry>G<subscript>10</subscript></entry>
464 <entry>R<subscript>10</subscript></entry>
465 <entry>B<subscript>11</subscript></entry>
466 <entry>G<subscript>11</subscript></entry>
467 <entry>R<subscript>11</subscript></entry>
468 <entry>B<subscript>12</subscript></entry>
469 <entry>G<subscript>12</subscript></entry>
470 <entry>R<subscript>12</subscript></entry>
471 <entry>B<subscript>13</subscript></entry>
472 <entry>G<subscript>13</subscript></entry>
473 <entry>R<subscript>13</subscript></entry>
474 </row>
475 <row>
476 <entry>start&nbsp;+&nbsp;24:</entry>
477 <entry>B<subscript>20</subscript></entry>
478 <entry>G<subscript>20</subscript></entry>
479 <entry>R<subscript>20</subscript></entry>
480 <entry>B<subscript>21</subscript></entry>
481 <entry>G<subscript>21</subscript></entry>
482 <entry>R<subscript>21</subscript></entry>
483 <entry>B<subscript>22</subscript></entry>
484 <entry>G<subscript>22</subscript></entry>
485 <entry>R<subscript>22</subscript></entry>
486 <entry>B<subscript>23</subscript></entry>
487 <entry>G<subscript>23</subscript></entry>
488 <entry>R<subscript>23</subscript></entry>
489 </row>
490 <row>
491 <entry>start&nbsp;+&nbsp;36:</entry>
492 <entry>B<subscript>30</subscript></entry>
493 <entry>G<subscript>30</subscript></entry>
494 <entry>R<subscript>30</subscript></entry>
495 <entry>B<subscript>31</subscript></entry>
496 <entry>G<subscript>31</subscript></entry>
497 <entry>R<subscript>31</subscript></entry>
498 <entry>B<subscript>32</subscript></entry>
499 <entry>G<subscript>32</subscript></entry>
500 <entry>R<subscript>32</subscript></entry>
501 <entry>B<subscript>33</subscript></entry>
502 <entry>G<subscript>33</subscript></entry>
503 <entry>R<subscript>33</subscript></entry>
504 </row>
505 </tbody>
506 </tgroup>
507 </informaltable>
508 </para>
509 </formalpara>
510 </example>
511
512 <important>
513 <para>Drivers may interpret these formats differently.</para>
514 </important>
515
516 <para>Some RGB formats above are uncommon and were probably
517defined in error. Drivers may interpret them as in <xref
518 linkend="rgb-formats-corrected" />.</para>
519
520 <table pgwide="1" frame="none" id="rgb-formats-corrected">
521 <title>Packed RGB Image Formats (corrected)</title>
522 <tgroup cols="37" align="center">
523 <colspec colname="id" align="left" />
524 <colspec colname="fourcc" />
525 <colspec colname="bit" />
526
527 <colspec colnum="4" colname="b07" align="center" />
528 <colspec colnum="5" colname="b06" align="center" />
529 <colspec colnum="6" colname="b05" align="center" />
530 <colspec colnum="7" colname="b04" align="center" />
531 <colspec colnum="8" colname="b03" align="center" />
532 <colspec colnum="9" colname="b02" align="center" />
533 <colspec colnum="10" colname="b01" align="center" />
534 <colspec colnum="11" colname="b00" align="center" />
535
536 <colspec colnum="13" colname="b17" align="center" />
537 <colspec colnum="14" colname="b16" align="center" />
538 <colspec colnum="15" colname="b15" align="center" />
539 <colspec colnum="16" colname="b14" align="center" />
540 <colspec colnum="17" colname="b13" align="center" />
541 <colspec colnum="18" colname="b12" align="center" />
542 <colspec colnum="19" colname="b11" align="center" />
543 <colspec colnum="20" colname="b10" align="center" />
544
545 <colspec colnum="22" colname="b27" align="center" />
546 <colspec colnum="23" colname="b26" align="center" />
547 <colspec colnum="24" colname="b25" align="center" />
548 <colspec colnum="25" colname="b24" align="center" />
549 <colspec colnum="26" colname="b23" align="center" />
550 <colspec colnum="27" colname="b22" align="center" />
551 <colspec colnum="28" colname="b21" align="center" />
552 <colspec colnum="29" colname="b20" align="center" />
553
554 <colspec colnum="31" colname="b37" align="center" />
555 <colspec colnum="32" colname="b36" align="center" />
556 <colspec colnum="33" colname="b35" align="center" />
557 <colspec colnum="34" colname="b34" align="center" />
558 <colspec colnum="35" colname="b33" align="center" />
559 <colspec colnum="36" colname="b32" align="center" />
560 <colspec colnum="37" colname="b31" align="center" />
561 <colspec colnum="38" colname="b30" align="center" />
562
563 <spanspec namest="b07" nameend="b00" spanname="b0" />
564 <spanspec namest="b17" nameend="b10" spanname="b1" />
565 <spanspec namest="b27" nameend="b20" spanname="b2" />
566 <spanspec namest="b37" nameend="b30" spanname="b3" />
567 <thead>
568 <row>
569 <entry>Identifier</entry>
570 <entry>Code</entry>
571 <entry>&nbsp;</entry>
572 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
573 <entry spanname="b1">Byte&nbsp;1</entry>
574 <entry spanname="b2">Byte&nbsp;2</entry>
575 <entry spanname="b3">Byte&nbsp;3</entry>
576 </row>
577 <row>
578 <entry>&nbsp;</entry>
579 <entry>&nbsp;</entry>
580 <entry>Bit</entry>
581 <entry>7</entry>
582 <entry>6</entry>
583 <entry>5</entry>
584 <entry>4</entry>
585 <entry>3</entry>
586 <entry>2</entry>
587 <entry>1</entry>
588 <entry>0</entry>
589 <entry>&nbsp;</entry>
590 <entry>7</entry>
591 <entry>6</entry>
592 <entry>5</entry>
593 <entry>4</entry>
594 <entry>3</entry>
595 <entry>2</entry>
596 <entry>1</entry>
597 <entry>0</entry>
598 <entry>&nbsp;</entry>
599 <entry>7</entry>
600 <entry>6</entry>
601 <entry>5</entry>
602 <entry>4</entry>
603 <entry>3</entry>
604 <entry>2</entry>
605 <entry>1</entry>
606 <entry>0</entry>
607 <entry>&nbsp;</entry>
608 <entry>7</entry>
609 <entry>6</entry>
610 <entry>5</entry>
611 <entry>4</entry>
612 <entry>3</entry>
613 <entry>2</entry>
614 <entry>1</entry>
615 <entry>0</entry>
616 </row>
617 </thead>
618 <tbody valign="top">
619 <row><!-- id="V4L2-PIX-FMT-RGB332" -->
620 <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
621 <entry>'RGB1'</entry>
622 <entry></entry>
623 <entry>r<subscript>2</subscript></entry>
624 <entry>r<subscript>1</subscript></entry>
625 <entry>r<subscript>0</subscript></entry>
626 <entry>g<subscript>2</subscript></entry>
627 <entry>g<subscript>1</subscript></entry>
628 <entry>g<subscript>0</subscript></entry>
629 <entry>b<subscript>1</subscript></entry>
630 <entry>b<subscript>0</subscript></entry>
631 </row>
632 <row><!-- id="V4L2-PIX-FMT-RGB444" -->
633 <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
634 <entry>'R444'</entry>
635 <entry></entry>
636 <entry>g<subscript>3</subscript></entry>
637 <entry>g<subscript>2</subscript></entry>
638 <entry>g<subscript>1</subscript></entry>
639 <entry>g<subscript>0</subscript></entry>
640 <entry>b<subscript>3</subscript></entry>
641 <entry>b<subscript>2</subscript></entry>
642 <entry>b<subscript>1</subscript></entry>
643 <entry>b<subscript>0</subscript></entry>
644 <entry></entry>
645 <entry>a<subscript>3</subscript></entry>
646 <entry>a<subscript>2</subscript></entry>
647 <entry>a<subscript>1</subscript></entry>
648 <entry>a<subscript>0</subscript></entry>
649 <entry>r<subscript>3</subscript></entry>
650 <entry>r<subscript>2</subscript></entry>
651 <entry>r<subscript>1</subscript></entry>
652 <entry>r<subscript>0</subscript></entry>
653 </row>
654 <row><!-- id="V4L2-PIX-FMT-RGB555" -->
655 <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
656 <entry>'RGBO'</entry>
657 <entry></entry>
658 <entry>g<subscript>2</subscript></entry>
659 <entry>g<subscript>1</subscript></entry>
660 <entry>g<subscript>0</subscript></entry>
661 <entry>b<subscript>4</subscript></entry>
662 <entry>b<subscript>3</subscript></entry>
663 <entry>b<subscript>2</subscript></entry>
664 <entry>b<subscript>1</subscript></entry>
665 <entry>b<subscript>0</subscript></entry>
666 <entry></entry>
667 <entry>a</entry>
668 <entry>r<subscript>4</subscript></entry>
669 <entry>r<subscript>3</subscript></entry>
670 <entry>r<subscript>2</subscript></entry>
671 <entry>r<subscript>1</subscript></entry>
672 <entry>r<subscript>0</subscript></entry>
673 <entry>g<subscript>4</subscript></entry>
674 <entry>g<subscript>3</subscript></entry>
675 </row>
676 <row><!-- id="V4L2-PIX-FMT-RGB565" -->
677 <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
678 <entry>'RGBP'</entry>
679 <entry></entry>
680 <entry>g<subscript>2</subscript></entry>
681 <entry>g<subscript>1</subscript></entry>
682 <entry>g<subscript>0</subscript></entry>
683 <entry>b<subscript>4</subscript></entry>
684 <entry>b<subscript>3</subscript></entry>
685 <entry>b<subscript>2</subscript></entry>
686 <entry>b<subscript>1</subscript></entry>
687 <entry>b<subscript>0</subscript></entry>
688 <entry></entry>
689 <entry>r<subscript>4</subscript></entry>
690 <entry>r<subscript>3</subscript></entry>
691 <entry>r<subscript>2</subscript></entry>
692 <entry>r<subscript>1</subscript></entry>
693 <entry>r<subscript>0</subscript></entry>
694 <entry>g<subscript>5</subscript></entry>
695 <entry>g<subscript>4</subscript></entry>
696 <entry>g<subscript>3</subscript></entry>
697 </row>
698 <row><!-- id="V4L2-PIX-FMT-RGB555X" -->
699 <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
700 <entry>'RGBQ'</entry>
701 <entry></entry>
702 <entry>a</entry>
703 <entry>r<subscript>4</subscript></entry>
704 <entry>r<subscript>3</subscript></entry>
705 <entry>r<subscript>2</subscript></entry>
706 <entry>r<subscript>1</subscript></entry>
707 <entry>r<subscript>0</subscript></entry>
708 <entry>g<subscript>4</subscript></entry>
709 <entry>g<subscript>3</subscript></entry>
710 <entry></entry>
711 <entry>g<subscript>2</subscript></entry>
712 <entry>g<subscript>1</subscript></entry>
713 <entry>g<subscript>0</subscript></entry>
714 <entry>b<subscript>4</subscript></entry>
715 <entry>b<subscript>3</subscript></entry>
716 <entry>b<subscript>2</subscript></entry>
717 <entry>b<subscript>1</subscript></entry>
718 <entry>b<subscript>0</subscript></entry>
719 </row>
720 <row><!-- id="V4L2-PIX-FMT-RGB565X" -->
721 <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
722 <entry>'RGBR'</entry>
723 <entry></entry>
724 <entry>r<subscript>4</subscript></entry>
725 <entry>r<subscript>3</subscript></entry>
726 <entry>r<subscript>2</subscript></entry>
727 <entry>r<subscript>1</subscript></entry>
728 <entry>r<subscript>0</subscript></entry>
729 <entry>g<subscript>5</subscript></entry>
730 <entry>g<subscript>4</subscript></entry>
731 <entry>g<subscript>3</subscript></entry>
732 <entry></entry>
733 <entry>g<subscript>2</subscript></entry>
734 <entry>g<subscript>1</subscript></entry>
735 <entry>g<subscript>0</subscript></entry>
736 <entry>b<subscript>4</subscript></entry>
737 <entry>b<subscript>3</subscript></entry>
738 <entry>b<subscript>2</subscript></entry>
739 <entry>b<subscript>1</subscript></entry>
740 <entry>b<subscript>0</subscript></entry>
741 </row>
742 <row><!-- id="V4L2-PIX-FMT-BGR666" -->
743 <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry>
744 <entry>'BGRH'</entry>
745 <entry></entry>
746 <entry>b<subscript>5</subscript></entry>
747 <entry>b<subscript>4</subscript></entry>
748 <entry>b<subscript>3</subscript></entry>
749 <entry>b<subscript>2</subscript></entry>
750 <entry>b<subscript>1</subscript></entry>
751 <entry>b<subscript>0</subscript></entry>
752 <entry>g<subscript>5</subscript></entry>
753 <entry>g<subscript>4</subscript></entry>
754 <entry></entry>
755 <entry>g<subscript>3</subscript></entry>
756 <entry>g<subscript>2</subscript></entry>
757 <entry>g<subscript>1</subscript></entry>
758 <entry>g<subscript>0</subscript></entry>
759 <entry>r<subscript>5</subscript></entry>
760 <entry>r<subscript>4</subscript></entry>
761 <entry>r<subscript>3</subscript></entry>
762 <entry>r<subscript>2</subscript></entry>
763 <entry></entry>
764 <entry>r<subscript>1</subscript></entry>
765 <entry>r<subscript>0</subscript></entry>
766 <entry></entry>
767 <entry></entry>
768 <entry></entry>
769 <entry></entry>
770 <entry></entry>
771 <entry></entry>
772 <entry></entry>
773 <entry></entry>
774 <entry></entry>
775 <entry></entry>
776 <entry></entry>
777 <entry></entry>
778 <entry></entry>
779 <entry></entry>
780 </row>
781 <row><!-- id="V4L2-PIX-FMT-BGR24" -->
782 <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
783 <entry>'BGR3'</entry>
784 <entry></entry>
785 <entry>b<subscript>7</subscript></entry>
786 <entry>b<subscript>6</subscript></entry>
787 <entry>b<subscript>5</subscript></entry>
788 <entry>b<subscript>4</subscript></entry>
789 <entry>b<subscript>3</subscript></entry>
790 <entry>b<subscript>2</subscript></entry>
791 <entry>b<subscript>1</subscript></entry>
792 <entry>b<subscript>0</subscript></entry>
793 <entry></entry>
794 <entry>g<subscript>7</subscript></entry>
795 <entry>g<subscript>6</subscript></entry>
796 <entry>g<subscript>5</subscript></entry>
797 <entry>g<subscript>4</subscript></entry>
798 <entry>g<subscript>3</subscript></entry>
799 <entry>g<subscript>2</subscript></entry>
800 <entry>g<subscript>1</subscript></entry>
801 <entry>g<subscript>0</subscript></entry>
802 <entry></entry>
803 <entry>r<subscript>7</subscript></entry>
804 <entry>r<subscript>6</subscript></entry>
805 <entry>r<subscript>5</subscript></entry>
806 <entry>r<subscript>4</subscript></entry>
807 <entry>r<subscript>3</subscript></entry>
808 <entry>r<subscript>2</subscript></entry>
809 <entry>r<subscript>1</subscript></entry>
810 <entry>r<subscript>0</subscript></entry>
811 </row>
812 <row><!-- id="V4L2-PIX-FMT-RGB24" -->
813 <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
814 <entry>'RGB3'</entry>
815 <entry></entry>
816 <entry>r<subscript>7</subscript></entry>
817 <entry>r<subscript>6</subscript></entry>
818 <entry>r<subscript>5</subscript></entry>
819 <entry>r<subscript>4</subscript></entry>
820 <entry>r<subscript>3</subscript></entry>
821 <entry>r<subscript>2</subscript></entry>
822 <entry>r<subscript>1</subscript></entry>
823 <entry>r<subscript>0</subscript></entry>
824 <entry></entry>
825 <entry>g<subscript>7</subscript></entry>
826 <entry>g<subscript>6</subscript></entry>
827 <entry>g<subscript>5</subscript></entry>
828 <entry>g<subscript>4</subscript></entry>
829 <entry>g<subscript>3</subscript></entry>
830 <entry>g<subscript>2</subscript></entry>
831 <entry>g<subscript>1</subscript></entry>
832 <entry>g<subscript>0</subscript></entry>
833 <entry></entry>
834 <entry>b<subscript>7</subscript></entry>
835 <entry>b<subscript>6</subscript></entry>
836 <entry>b<subscript>5</subscript></entry>
837 <entry>b<subscript>4</subscript></entry>
838 <entry>b<subscript>3</subscript></entry>
839 <entry>b<subscript>2</subscript></entry>
840 <entry>b<subscript>1</subscript></entry>
841 <entry>b<subscript>0</subscript></entry>
842 </row>
843 <row><!-- id="V4L2-PIX-FMT-BGR32" -->
844 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
845 <entry>'BGR4'</entry>
846 <entry></entry>
847 <entry>b<subscript>7</subscript></entry>
848 <entry>b<subscript>6</subscript></entry>
849 <entry>b<subscript>5</subscript></entry>
850 <entry>b<subscript>4</subscript></entry>
851 <entry>b<subscript>3</subscript></entry>
852 <entry>b<subscript>2</subscript></entry>
853 <entry>b<subscript>1</subscript></entry>
854 <entry>b<subscript>0</subscript></entry>
855 <entry></entry>
856 <entry>g<subscript>7</subscript></entry>
857 <entry>g<subscript>6</subscript></entry>
858 <entry>g<subscript>5</subscript></entry>
859 <entry>g<subscript>4</subscript></entry>
860 <entry>g<subscript>3</subscript></entry>
861 <entry>g<subscript>2</subscript></entry>
862 <entry>g<subscript>1</subscript></entry>
863 <entry>g<subscript>0</subscript></entry>
864 <entry></entry>
865 <entry>r<subscript>7</subscript></entry>
866 <entry>r<subscript>6</subscript></entry>
867 <entry>r<subscript>5</subscript></entry>
868 <entry>r<subscript>4</subscript></entry>
869 <entry>r<subscript>3</subscript></entry>
870 <entry>r<subscript>2</subscript></entry>
871 <entry>r<subscript>1</subscript></entry>
872 <entry>r<subscript>0</subscript></entry>
873 <entry></entry>
874 <entry>a<subscript>7</subscript></entry>
875 <entry>a<subscript>6</subscript></entry>
876 <entry>a<subscript>5</subscript></entry>
877 <entry>a<subscript>4</subscript></entry>
878 <entry>a<subscript>3</subscript></entry>
879 <entry>a<subscript>2</subscript></entry>
880 <entry>a<subscript>1</subscript></entry>
881 <entry>a<subscript>0</subscript></entry>
882 </row>
883 <row><!-- id="V4L2-PIX-FMT-RGB32" -->
884 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
885 <entry>'RGB4'</entry>
886 <entry></entry>
887 <entry>a<subscript>7</subscript></entry>
888 <entry>a<subscript>6</subscript></entry>
889 <entry>a<subscript>5</subscript></entry>
890 <entry>a<subscript>4</subscript></entry>
891 <entry>a<subscript>3</subscript></entry>
892 <entry>a<subscript>2</subscript></entry>
893 <entry>a<subscript>1</subscript></entry>
894 <entry>a<subscript>0</subscript></entry>
895 <entry></entry>
896 <entry>r<subscript>7</subscript></entry>
897 <entry>r<subscript>6</subscript></entry>
898 <entry>r<subscript>5</subscript></entry>
899 <entry>r<subscript>4</subscript></entry>
900 <entry>r<subscript>3</subscript></entry>
901 <entry>r<subscript>2</subscript></entry>
902 <entry>r<subscript>1</subscript></entry>
903 <entry>r<subscript>0</subscript></entry>
904 <entry></entry>
905 <entry>g<subscript>7</subscript></entry>
906 <entry>g<subscript>6</subscript></entry>
907 <entry>g<subscript>5</subscript></entry>
908 <entry>g<subscript>4</subscript></entry>
909 <entry>g<subscript>3</subscript></entry>
910 <entry>g<subscript>2</subscript></entry>
911 <entry>g<subscript>1</subscript></entry>
912 <entry>g<subscript>0</subscript></entry>
913 <entry></entry>
914 <entry>b<subscript>7</subscript></entry>
915 <entry>b<subscript>6</subscript></entry>
916 <entry>b<subscript>5</subscript></entry>
917 <entry>b<subscript>4</subscript></entry>
918 <entry>b<subscript>3</subscript></entry>
919 <entry>b<subscript>2</subscript></entry>
920 <entry>b<subscript>1</subscript></entry>
921 <entry>b<subscript>0</subscript></entry>
922 </row>
923 </tbody>
924 </tgroup>
925 </table>
926
927 <para>A test utility to determine which RGB formats a driver
928actually supports is available from the LinuxTV v4l-dvb repository.
929See &v4l-dvb; for access instructions.</para>
930
931 </refsect1>
932 </refentry>
933
934 <!--
935Local Variables:
936mode: sgml
937sgml-parent-document: "pixfmt.sgml"
938indent-tabs-mode: nil
939End:
940 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml b/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml
new file mode 100644
index 000000000000..3cab5d0ca75d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-packed-yuv.xml
@@ -0,0 +1,244 @@
1<refentry id="packed-yuv">
2 <refmeta>
3 <refentrytitle>Packed YUV formats</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname>Packed YUV formats</refname>
8 <refpurpose>Packed YUV formats</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>Similar to the packed RGB formats these formats store
14the Y, Cb and Cr component of each pixel in one 16 or 32 bit
15word.</para>
16
17 <table pgwide="1" frame="none">
18 <title>Packed YUV Image Formats</title>
19 <tgroup cols="37" align="center">
20 <colspec colname="id" align="left" />
21 <colspec colname="fourcc" />
22 <colspec colname="bit" />
23
24 <colspec colnum="4" colname="b07" align="center" />
25 <colspec colnum="5" colname="b06" align="center" />
26 <colspec colnum="6" colname="b05" align="center" />
27 <colspec colnum="7" colname="b04" align="center" />
28 <colspec colnum="8" colname="b03" align="center" />
29 <colspec colnum="9" colname="b02" align="center" />
30 <colspec colnum="10" colname="b01" align="center" />
31 <colspec colnum="11" colname="b00" align="center" />
32
33 <colspec colnum="13" colname="b17" align="center" />
34 <colspec colnum="14" colname="b16" align="center" />
35 <colspec colnum="15" colname="b15" align="center" />
36 <colspec colnum="16" colname="b14" align="center" />
37 <colspec colnum="17" colname="b13" align="center" />
38 <colspec colnum="18" colname="b12" align="center" />
39 <colspec colnum="19" colname="b11" align="center" />
40 <colspec colnum="20" colname="b10" align="center" />
41
42 <colspec colnum="22" colname="b27" align="center" />
43 <colspec colnum="23" colname="b26" align="center" />
44 <colspec colnum="24" colname="b25" align="center" />
45 <colspec colnum="25" colname="b24" align="center" />
46 <colspec colnum="26" colname="b23" align="center" />
47 <colspec colnum="27" colname="b22" align="center" />
48 <colspec colnum="28" colname="b21" align="center" />
49 <colspec colnum="29" colname="b20" align="center" />
50
51 <colspec colnum="31" colname="b37" align="center" />
52 <colspec colnum="32" colname="b36" align="center" />
53 <colspec colnum="33" colname="b35" align="center" />
54 <colspec colnum="34" colname="b34" align="center" />
55 <colspec colnum="35" colname="b33" align="center" />
56 <colspec colnum="36" colname="b32" align="center" />
57 <colspec colnum="37" colname="b31" align="center" />
58 <colspec colnum="38" colname="b30" align="center" />
59
60 <spanspec namest="b07" nameend="b00" spanname="b0" />
61 <spanspec namest="b17" nameend="b10" spanname="b1" />
62 <spanspec namest="b27" nameend="b20" spanname="b2" />
63 <spanspec namest="b37" nameend="b30" spanname="b3" />
64 <thead>
65 <row>
66 <entry>Identifier</entry>
67 <entry>Code</entry>
68 <entry>&nbsp;</entry>
69 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
70 <entry spanname="b1">Byte&nbsp;1</entry>
71 <entry spanname="b2">Byte&nbsp;2</entry>
72 <entry spanname="b3">Byte&nbsp;3</entry>
73 </row>
74 <row>
75 <entry>&nbsp;</entry>
76 <entry>&nbsp;</entry>
77 <entry>Bit</entry>
78 <entry>7</entry>
79 <entry>6</entry>
80 <entry>5</entry>
81 <entry>4</entry>
82 <entry>3</entry>
83 <entry>2</entry>
84 <entry>1</entry>
85 <entry>0</entry>
86 <entry>&nbsp;</entry>
87 <entry>7</entry>
88 <entry>6</entry>
89 <entry>5</entry>
90 <entry>4</entry>
91 <entry>3</entry>
92 <entry>2</entry>
93 <entry>1</entry>
94 <entry>0</entry>
95 <entry>&nbsp;</entry>
96 <entry>7</entry>
97 <entry>6</entry>
98 <entry>5</entry>
99 <entry>4</entry>
100 <entry>3</entry>
101 <entry>2</entry>
102 <entry>1</entry>
103 <entry>0</entry>
104 <entry>&nbsp;</entry>
105 <entry>7</entry>
106 <entry>6</entry>
107 <entry>5</entry>
108 <entry>4</entry>
109 <entry>3</entry>
110 <entry>2</entry>
111 <entry>1</entry>
112 <entry>0</entry>
113 </row>
114 </thead>
115 <tbody valign="top">
116 <row id="V4L2-PIX-FMT-YUV444">
117 <entry><constant>V4L2_PIX_FMT_YUV444</constant></entry>
118 <entry>'Y444'</entry>
119 <entry></entry>
120 <entry>Cb<subscript>3</subscript></entry>
121 <entry>Cb<subscript>2</subscript></entry>
122 <entry>Cb<subscript>1</subscript></entry>
123 <entry>Cb<subscript>0</subscript></entry>
124 <entry>Cr<subscript>3</subscript></entry>
125 <entry>Cr<subscript>2</subscript></entry>
126 <entry>Cr<subscript>1</subscript></entry>
127 <entry>Cr<subscript>0</subscript></entry>
128 <entry></entry>
129 <entry>a<subscript>3</subscript></entry>
130 <entry>a<subscript>2</subscript></entry>
131 <entry>a<subscript>1</subscript></entry>
132 <entry>a<subscript>0</subscript></entry>
133 <entry>Y'<subscript>3</subscript></entry>
134 <entry>Y'<subscript>2</subscript></entry>
135 <entry>Y'<subscript>1</subscript></entry>
136 <entry>Y'<subscript>0</subscript></entry>
137 </row>
138
139 <row id="V4L2-PIX-FMT-YUV555">
140 <entry><constant>V4L2_PIX_FMT_YUV555</constant></entry>
141 <entry>'YUVO'</entry>
142 <entry></entry>
143 <entry>Cb<subscript>2</subscript></entry>
144 <entry>Cb<subscript>1</subscript></entry>
145 <entry>Cb<subscript>0</subscript></entry>
146 <entry>Cr<subscript>4</subscript></entry>
147 <entry>Cr<subscript>3</subscript></entry>
148 <entry>Cr<subscript>2</subscript></entry>
149 <entry>Cr<subscript>1</subscript></entry>
150 <entry>Cr<subscript>0</subscript></entry>
151 <entry></entry>
152 <entry>a</entry>
153 <entry>Y'<subscript>4</subscript></entry>
154 <entry>Y'<subscript>3</subscript></entry>
155 <entry>Y'<subscript>2</subscript></entry>
156 <entry>Y'<subscript>1</subscript></entry>
157 <entry>Y'<subscript>0</subscript></entry>
158 <entry>Cb<subscript>4</subscript></entry>
159 <entry>Cb<subscript>3</subscript></entry>
160 </row>
161
162 <row id="V4L2-PIX-FMT-YUV565">
163 <entry><constant>V4L2_PIX_FMT_YUV565</constant></entry>
164 <entry>'YUVP'</entry>
165 <entry></entry>
166 <entry>Cb<subscript>2</subscript></entry>
167 <entry>Cb<subscript>1</subscript></entry>
168 <entry>Cb<subscript>0</subscript></entry>
169 <entry>Cr<subscript>4</subscript></entry>
170 <entry>Cr<subscript>3</subscript></entry>
171 <entry>Cr<subscript>2</subscript></entry>
172 <entry>Cr<subscript>1</subscript></entry>
173 <entry>Cr<subscript>0</subscript></entry>
174 <entry></entry>
175 <entry>Y'<subscript>4</subscript></entry>
176 <entry>Y'<subscript>3</subscript></entry>
177 <entry>Y'<subscript>2</subscript></entry>
178 <entry>Y'<subscript>1</subscript></entry>
179 <entry>Y'<subscript>0</subscript></entry>
180 <entry>Cb<subscript>5</subscript></entry>
181 <entry>Cb<subscript>4</subscript></entry>
182 <entry>Cb<subscript>3</subscript></entry>
183 </row>
184
185 <row id="V4L2-PIX-FMT-YUV32">
186 <entry><constant>V4L2_PIX_FMT_YUV32</constant></entry>
187 <entry>'YUV4'</entry>
188 <entry></entry>
189 <entry>a<subscript>7</subscript></entry>
190 <entry>a<subscript>6</subscript></entry>
191 <entry>a<subscript>5</subscript></entry>
192 <entry>a<subscript>4</subscript></entry>
193 <entry>a<subscript>3</subscript></entry>
194 <entry>a<subscript>2</subscript></entry>
195 <entry>a<subscript>1</subscript></entry>
196 <entry>a<subscript>0</subscript></entry>
197 <entry></entry>
198 <entry>Y'<subscript>7</subscript></entry>
199 <entry>Y'<subscript>6</subscript></entry>
200 <entry>Y'<subscript>5</subscript></entry>
201 <entry>Y'<subscript>4</subscript></entry>
202 <entry>Y'<subscript>3</subscript></entry>
203 <entry>Y'<subscript>2</subscript></entry>
204 <entry>Y'<subscript>1</subscript></entry>
205 <entry>Y'<subscript>0</subscript></entry>
206 <entry></entry>
207 <entry>Cb<subscript>7</subscript></entry>
208 <entry>Cb<subscript>6</subscript></entry>
209 <entry>Cb<subscript>5</subscript></entry>
210 <entry>Cb<subscript>4</subscript></entry>
211 <entry>Cb<subscript>3</subscript></entry>
212 <entry>Cb<subscript>2</subscript></entry>
213 <entry>Cb<subscript>1</subscript></entry>
214 <entry>Cb<subscript>0</subscript></entry>
215 <entry></entry>
216 <entry>Cr<subscript>7</subscript></entry>
217 <entry>Cr<subscript>6</subscript></entry>
218 <entry>Cr<subscript>5</subscript></entry>
219 <entry>Cr<subscript>4</subscript></entry>
220 <entry>Cr<subscript>3</subscript></entry>
221 <entry>Cr<subscript>2</subscript></entry>
222 <entry>Cr<subscript>1</subscript></entry>
223 <entry>Cr<subscript>0</subscript></entry>
224 </row>
225 </tbody>
226 </tgroup>
227 </table>
228
229 <para>Bit 7 is the most significant bit. The value of a = alpha
230bits is undefined when reading from the driver, ignored when writing
231to the driver, except when alpha blending has been negotiated for a
232<link linkend="overlay">Video Overlay</link> or <link
233linkend="osd">Video Output Overlay</link>.</para>
234
235 </refsect1>
236 </refentry>
237
238 <!--
239Local Variables:
240mode: sgml
241sgml-parent-document: "pixfmt.sgml"
242indent-tabs-mode: nil
243End:
244 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml
new file mode 100644
index 000000000000..519a9efbac10
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-sbggr16.xml
@@ -0,0 +1,91 @@
1<refentry id="V4L2-PIX-FMT-SBGGR16">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_SBGGR16 ('BYR2')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_SBGGR16</constant></refname>
8 <refpurpose>Bayer RGB format</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This format is similar to <link
14linkend="V4L2-PIX-FMT-SBGGR8">
15<constant>V4L2_PIX_FMT_SBGGR8</constant></link>, except each pixel has
16a depth of 16 bits. The least significant byte is stored at lower
17memory addresses (little-endian). Note the actual sampling precision
18may be lower than 16 bits, for example 10 bits per pixel with values
19in range 0 to 1023.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SBGGR16</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="5" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>B<subscript>00low</subscript></entry>
35 <entry>B<subscript>00high</subscript></entry>
36 <entry>G<subscript>01low</subscript></entry>
37 <entry>G<subscript>01high</subscript></entry>
38 <entry>B<subscript>02low</subscript></entry>
39 <entry>B<subscript>02high</subscript></entry>
40 <entry>G<subscript>03low</subscript></entry>
41 <entry>G<subscript>03high</subscript></entry>
42 </row>
43 <row>
44 <entry>start&nbsp;+&nbsp;8:</entry>
45 <entry>G<subscript>10low</subscript></entry>
46 <entry>G<subscript>10high</subscript></entry>
47 <entry>R<subscript>11low</subscript></entry>
48 <entry>R<subscript>11high</subscript></entry>
49 <entry>G<subscript>12low</subscript></entry>
50 <entry>G<subscript>12high</subscript></entry>
51 <entry>R<subscript>13low</subscript></entry>
52 <entry>R<subscript>13high</subscript></entry>
53 </row>
54 <row>
55 <entry>start&nbsp;+&nbsp;16:</entry>
56 <entry>B<subscript>20low</subscript></entry>
57 <entry>B<subscript>20high</subscript></entry>
58 <entry>G<subscript>21low</subscript></entry>
59 <entry>G<subscript>21high</subscript></entry>
60 <entry>B<subscript>22low</subscript></entry>
61 <entry>B<subscript>22high</subscript></entry>
62 <entry>G<subscript>23low</subscript></entry>
63 <entry>G<subscript>23high</subscript></entry>
64 </row>
65 <row>
66 <entry>start&nbsp;+&nbsp;24:</entry>
67 <entry>G<subscript>30low</subscript></entry>
68 <entry>G<subscript>30high</subscript></entry>
69 <entry>R<subscript>31low</subscript></entry>
70 <entry>R<subscript>31high</subscript></entry>
71 <entry>G<subscript>32low</subscript></entry>
72 <entry>G<subscript>32high</subscript></entry>
73 <entry>R<subscript>33low</subscript></entry>
74 <entry>R<subscript>33high</subscript></entry>
75 </row>
76 </tbody>
77 </tgroup>
78 </informaltable>
79 </para>
80 </formalpara>
81 </example>
82 </refsect1>
83</refentry>
84
85 <!--
86Local Variables:
87mode: sgml
88sgml-parent-document: "pixfmt.sgml"
89indent-tabs-mode: nil
90End:
91 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml b/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml
new file mode 100644
index 000000000000..5fe84ecc2ebe
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-sbggr8.xml
@@ -0,0 +1,75 @@
1 <refentry id="V4L2-PIX-FMT-SBGGR8">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_SBGGR8 ('BA81')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_SBGGR8</constant></refname>
8 <refpurpose>Bayer RGB format</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is commonly the native format of digital cameras,
14reflecting the arrangement of sensors on the CCD device. Only one red,
15green or blue value is given for each pixel. Missing components must
16be interpolated from neighbouring pixels. From left to right the first
17row consists of a blue and green value, the second row of a green and
18red value. This scheme repeats to the right and down for every two
19columns and rows.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SBGGR8</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="5" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>B<subscript>00</subscript></entry>
35 <entry>G<subscript>01</subscript></entry>
36 <entry>B<subscript>02</subscript></entry>
37 <entry>G<subscript>03</subscript></entry>
38 </row>
39 <row>
40 <entry>start&nbsp;+&nbsp;4:</entry>
41 <entry>G<subscript>10</subscript></entry>
42 <entry>R<subscript>11</subscript></entry>
43 <entry>G<subscript>12</subscript></entry>
44 <entry>R<subscript>13</subscript></entry>
45 </row>
46 <row>
47 <entry>start&nbsp;+&nbsp;8:</entry>
48 <entry>B<subscript>20</subscript></entry>
49 <entry>G<subscript>21</subscript></entry>
50 <entry>B<subscript>22</subscript></entry>
51 <entry>G<subscript>23</subscript></entry>
52 </row>
53 <row>
54 <entry>start&nbsp;+&nbsp;12:</entry>
55 <entry>G<subscript>30</subscript></entry>
56 <entry>R<subscript>31</subscript></entry>
57 <entry>G<subscript>32</subscript></entry>
58 <entry>R<subscript>33</subscript></entry>
59 </row>
60 </tbody>
61 </tgroup>
62 </informaltable>
63 </para>
64 </formalpara>
65 </example>
66 </refsect1>
67 </refentry>
68
69 <!--
70Local Variables:
71mode: sgml
72sgml-parent-document: "pixfmt.sgml"
73indent-tabs-mode: nil
74End:
75 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml
new file mode 100644
index 000000000000..d67a472b0880
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-sgbrg8.xml
@@ -0,0 +1,75 @@
1 <refentry id="V4L2-PIX-FMT-SGBRG8">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_SGBRG8 ('GBRG')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_SGBRG8</constant></refname>
8 <refpurpose>Bayer RGB format</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is commonly the native format of digital cameras,
14reflecting the arrangement of sensors on the CCD device. Only one red,
15green or blue value is given for each pixel. Missing components must
16be interpolated from neighbouring pixels. From left to right the first
17row consists of a green and blue value, the second row of a red and
18green value. This scheme repeats to the right and down for every two
19columns and rows.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SGBRG8</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="5" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>G<subscript>00</subscript></entry>
35 <entry>B<subscript>01</subscript></entry>
36 <entry>G<subscript>02</subscript></entry>
37 <entry>B<subscript>03</subscript></entry>
38 </row>
39 <row>
40 <entry>start&nbsp;+&nbsp;4:</entry>
41 <entry>R<subscript>10</subscript></entry>
42 <entry>G<subscript>11</subscript></entry>
43 <entry>R<subscript>12</subscript></entry>
44 <entry>G<subscript>13</subscript></entry>
45 </row>
46 <row>
47 <entry>start&nbsp;+&nbsp;8:</entry>
48 <entry>G<subscript>20</subscript></entry>
49 <entry>B<subscript>21</subscript></entry>
50 <entry>G<subscript>22</subscript></entry>
51 <entry>B<subscript>23</subscript></entry>
52 </row>
53 <row>
54 <entry>start&nbsp;+&nbsp;12:</entry>
55 <entry>R<subscript>30</subscript></entry>
56 <entry>G<subscript>31</subscript></entry>
57 <entry>R<subscript>32</subscript></entry>
58 <entry>G<subscript>33</subscript></entry>
59 </row>
60 </tbody>
61 </tgroup>
62 </informaltable>
63 </para>
64 </formalpara>
65 </example>
66 </refsect1>
67 </refentry>
68
69 <!--
70Local Variables:
71mode: sgml
72sgml-parent-document: "pixfmt.sgml"
73indent-tabs-mode: nil
74End:
75 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml b/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml
new file mode 100644
index 000000000000..0cdf13b8ac1c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-sgrbg8.xml
@@ -0,0 +1,75 @@
1 <refentry id="V4L2-PIX-FMT-SGRBG8">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_SGRBG8 ('GRBG')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_SGRBG8</constant></refname>
8 <refpurpose>Bayer RGB format</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is commonly the native format of digital cameras,
14reflecting the arrangement of sensors on the CCD device. Only one red,
15green or blue value is given for each pixel. Missing components must
16be interpolated from neighbouring pixels. From left to right the first
17row consists of a green and blue value, the second row of a red and
18green value. This scheme repeats to the right and down for every two
19columns and rows.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SGRBG8</constant> 4 &times;
234 pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="5" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>G<subscript>00</subscript></entry>
35 <entry>R<subscript>01</subscript></entry>
36 <entry>G<subscript>02</subscript></entry>
37 <entry>R<subscript>03</subscript></entry>
38 </row>
39 <row>
40 <entry>start&nbsp;+&nbsp;4:</entry>
41 <entry>R<subscript>10</subscript></entry>
42 <entry>B<subscript>11</subscript></entry>
43 <entry>R<subscript>12</subscript></entry>
44 <entry>B<subscript>13</subscript></entry>
45 </row>
46 <row>
47 <entry>start&nbsp;+&nbsp;8:</entry>
48 <entry>G<subscript>20</subscript></entry>
49 <entry>R<subscript>21</subscript></entry>
50 <entry>G<subscript>22</subscript></entry>
51 <entry>R<subscript>23</subscript></entry>
52 </row>
53 <row>
54 <entry>start&nbsp;+&nbsp;12:</entry>
55 <entry>R<subscript>30</subscript></entry>
56 <entry>B<subscript>31</subscript></entry>
57 <entry>R<subscript>32</subscript></entry>
58 <entry>B<subscript>33</subscript></entry>
59 </row>
60 </tbody>
61 </tgroup>
62 </informaltable>
63 </para>
64 </formalpara>
65 </example>
66 </refsect1>
67 </refentry>
68
69 <!--
70Local Variables:
71mode: sgml
72sgml-parent-document: "pixfmt.sgml"
73indent-tabs-mode: nil
74End:
75 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml
new file mode 100644
index 000000000000..7b274092e60c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-srggb10.xml
@@ -0,0 +1,90 @@
1 <refentry>
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_SRGGB10 ('RG10'),
4 V4L2_PIX_FMT_SGRBG10 ('BA10'),
5 V4L2_PIX_FMT_SGBRG10 ('GB10'),
6 V4L2_PIX_FMT_SBGGR10 ('BG10'),
7 </refentrytitle>
8 &manvol;
9 </refmeta>
10 <refnamediv>
11 <refname id="V4L2-PIX-FMT-SRGGB10"><constant>V4L2_PIX_FMT_SRGGB10</constant></refname>
12 <refname id="V4L2-PIX-FMT-SGRBG10"><constant>V4L2_PIX_FMT_SGRBG10</constant></refname>
13 <refname id="V4L2-PIX-FMT-SGBRG10"><constant>V4L2_PIX_FMT_SGBRG10</constant></refname>
14 <refname id="V4L2-PIX-FMT-SBGGR10"><constant>V4L2_PIX_FMT_SBGGR10</constant></refname>
15 <refpurpose>10-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
2110 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_SBGGR10</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/media/v4l/pixfmt-srggb12.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb12.xml
new file mode 100644
index 000000000000..9ba4fb690bc0
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/pixfmt-srggb8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml
new file mode 100644
index 000000000000..2570e3be3cf1
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-srggb8.xml
@@ -0,0 +1,67 @@
1 <refentry id="V4L2-PIX-FMT-SRGGB8">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_SRGGB8 ('RGGB')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_SRGGB8</constant></refname>
8 <refpurpose>Bayer RGB format</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is commonly the native format of digital cameras,
14reflecting the arrangement of sensors on the CCD device. Only one red,
15green or blue value is given for each pixel. Missing components must
16be interpolated from neighbouring pixels. From left to right the first
17row consists of a red and green value, the second row of a green and
18blue value. This scheme repeats to the right and down for every two
19columns and rows.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_SRGGB8</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="5" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>R<subscript>00</subscript></entry>
35 <entry>G<subscript>01</subscript></entry>
36 <entry>R<subscript>02</subscript></entry>
37 <entry>G<subscript>03</subscript></entry>
38 </row>
39 <row>
40 <entry>start&nbsp;+&nbsp;4:</entry>
41 <entry>G<subscript>10</subscript></entry>
42 <entry>B<subscript>11</subscript></entry>
43 <entry>G<subscript>12</subscript></entry>
44 <entry>B<subscript>13</subscript></entry>
45 </row>
46 <row>
47 <entry>start&nbsp;+&nbsp;8:</entry>
48 <entry>R<subscript>20</subscript></entry>
49 <entry>G<subscript>21</subscript></entry>
50 <entry>R<subscript>22</subscript></entry>
51 <entry>G<subscript>23</subscript></entry>
52 </row>
53 <row>
54 <entry>start&nbsp;+&nbsp;12:</entry>
55 <entry>G<subscript>30</subscript></entry>
56 <entry>B<subscript>31</subscript></entry>
57 <entry>G<subscript>32</subscript></entry>
58 <entry>B<subscript>33</subscript></entry>
59 </row>
60 </tbody>
61 </tgroup>
62 </informaltable>
63 </para>
64 </formalpara>
65 </example>
66 </refsect1>
67 </refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml b/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml
new file mode 100644
index 000000000000..816c8d467c16
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-uyvy.xml
@@ -0,0 +1,128 @@
1 <refentry id="V4L2-PIX-FMT-UYVY">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_UYVY ('UYVY')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_UYVY</constant></refname>
8 <refpurpose>Variation of
9<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
10in memory</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>In this format each four bytes is two pixels. Each four
16bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
17the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
18components have half the horizontal resolution of the Y
19component.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_UYVY</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="9" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>Cb<subscript>00</subscript></entry>
35 <entry>Y'<subscript>00</subscript></entry>
36 <entry>Cr<subscript>00</subscript></entry>
37 <entry>Y'<subscript>01</subscript></entry>
38 <entry>Cb<subscript>01</subscript></entry>
39 <entry>Y'<subscript>02</subscript></entry>
40 <entry>Cr<subscript>01</subscript></entry>
41 <entry>Y'<subscript>03</subscript></entry>
42 </row>
43 <row>
44 <entry>start&nbsp;+&nbsp;8:</entry>
45 <entry>Cb<subscript>10</subscript></entry>
46 <entry>Y'<subscript>10</subscript></entry>
47 <entry>Cr<subscript>10</subscript></entry>
48 <entry>Y'<subscript>11</subscript></entry>
49 <entry>Cb<subscript>11</subscript></entry>
50 <entry>Y'<subscript>12</subscript></entry>
51 <entry>Cr<subscript>11</subscript></entry>
52 <entry>Y'<subscript>13</subscript></entry>
53 </row>
54 <row>
55 <entry>start&nbsp;+&nbsp;16:</entry>
56 <entry>Cb<subscript>20</subscript></entry>
57 <entry>Y'<subscript>20</subscript></entry>
58 <entry>Cr<subscript>20</subscript></entry>
59 <entry>Y'<subscript>21</subscript></entry>
60 <entry>Cb<subscript>21</subscript></entry>
61 <entry>Y'<subscript>22</subscript></entry>
62 <entry>Cr<subscript>21</subscript></entry>
63 <entry>Y'<subscript>23</subscript></entry>
64 </row>
65 <row>
66 <entry>start&nbsp;+&nbsp;24:</entry>
67 <entry>Cb<subscript>30</subscript></entry>
68 <entry>Y'<subscript>30</subscript></entry>
69 <entry>Cr<subscript>30</subscript></entry>
70 <entry>Y'<subscript>31</subscript></entry>
71 <entry>Cb<subscript>31</subscript></entry>
72 <entry>Y'<subscript>32</subscript></entry>
73 <entry>Cr<subscript>31</subscript></entry>
74 <entry>Y'<subscript>33</subscript></entry>
75 </row>
76 </tbody>
77 </tgroup>
78 </informaltable>
79 </para>
80 </formalpara>
81
82 <formalpara>
83 <title>Color Sample Location.</title>
84 <para>
85 <informaltable frame="none">
86 <tgroup cols="7" align="center">
87 <tbody valign="top">
88 <row>
89 <entry></entry>
90 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
91 <entry>2</entry><entry></entry><entry>3</entry>
92 </row>
93 <row>
94 <entry>0</entry>
95 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
96 <entry>Y</entry><entry>C</entry><entry>Y</entry>
97 </row>
98 <row>
99 <entry>1</entry>
100 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
101 <entry>Y</entry><entry>C</entry><entry>Y</entry>
102 </row>
103 <row>
104 <entry>2</entry>
105 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
106 <entry>Y</entry><entry>C</entry><entry>Y</entry>
107 </row>
108 <row>
109 <entry>3</entry>
110 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
111 <entry>Y</entry><entry>C</entry><entry>Y</entry>
112 </row>
113 </tbody>
114 </tgroup>
115 </informaltable>
116 </para>
117 </formalpara>
118 </example>
119 </refsect1>
120 </refentry>
121
122 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
128 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml b/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml
new file mode 100644
index 000000000000..61f12a5e68d9
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-vyuy.xml
@@ -0,0 +1,128 @@
1 <refentry id="V4L2-PIX-FMT-VYUY">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_VYUY ('VYUY')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_VYUY</constant></refname>
8 <refpurpose>Variation of
9<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
10in memory</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>In this format each four bytes is two pixels. Each four
16bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
17the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
18components have half the horizontal resolution of the Y
19component.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_VYUY</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="9" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>Cr<subscript>00</subscript></entry>
35 <entry>Y'<subscript>00</subscript></entry>
36 <entry>Cb<subscript>00</subscript></entry>
37 <entry>Y'<subscript>01</subscript></entry>
38 <entry>Cr<subscript>01</subscript></entry>
39 <entry>Y'<subscript>02</subscript></entry>
40 <entry>Cb<subscript>01</subscript></entry>
41 <entry>Y'<subscript>03</subscript></entry>
42 </row>
43 <row>
44 <entry>start&nbsp;+&nbsp;8:</entry>
45 <entry>Cr<subscript>10</subscript></entry>
46 <entry>Y'<subscript>10</subscript></entry>
47 <entry>Cb<subscript>10</subscript></entry>
48 <entry>Y'<subscript>11</subscript></entry>
49 <entry>Cr<subscript>11</subscript></entry>
50 <entry>Y'<subscript>12</subscript></entry>
51 <entry>Cb<subscript>11</subscript></entry>
52 <entry>Y'<subscript>13</subscript></entry>
53 </row>
54 <row>
55 <entry>start&nbsp;+&nbsp;16:</entry>
56 <entry>Cr<subscript>20</subscript></entry>
57 <entry>Y'<subscript>20</subscript></entry>
58 <entry>Cb<subscript>20</subscript></entry>
59 <entry>Y'<subscript>21</subscript></entry>
60 <entry>Cr<subscript>21</subscript></entry>
61 <entry>Y'<subscript>22</subscript></entry>
62 <entry>Cb<subscript>21</subscript></entry>
63 <entry>Y'<subscript>23</subscript></entry>
64 </row>
65 <row>
66 <entry>start&nbsp;+&nbsp;24:</entry>
67 <entry>Cr<subscript>30</subscript></entry>
68 <entry>Y'<subscript>30</subscript></entry>
69 <entry>Cb<subscript>30</subscript></entry>
70 <entry>Y'<subscript>31</subscript></entry>
71 <entry>Cr<subscript>31</subscript></entry>
72 <entry>Y'<subscript>32</subscript></entry>
73 <entry>Cb<subscript>31</subscript></entry>
74 <entry>Y'<subscript>33</subscript></entry>
75 </row>
76 </tbody>
77 </tgroup>
78 </informaltable>
79 </para>
80 </formalpara>
81
82 <formalpara>
83 <title>Color Sample Location.</title>
84 <para>
85 <informaltable frame="none">
86 <tgroup cols="7" align="center">
87 <tbody valign="top">
88 <row>
89 <entry></entry>
90 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
91 <entry>2</entry><entry></entry><entry>3</entry>
92 </row>
93 <row>
94 <entry>0</entry>
95 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
96 <entry>Y</entry><entry>C</entry><entry>Y</entry>
97 </row>
98 <row>
99 <entry>1</entry>
100 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
101 <entry>Y</entry><entry>C</entry><entry>Y</entry>
102 </row>
103 <row>
104 <entry>2</entry>
105 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
106 <entry>Y</entry><entry>C</entry><entry>Y</entry>
107 </row>
108 <row>
109 <entry>3</entry>
110 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
111 <entry>Y</entry><entry>C</entry><entry>Y</entry>
112 </row>
113 </tbody>
114 </tgroup>
115 </informaltable>
116 </para>
117 </formalpara>
118 </example>
119 </refsect1>
120 </refentry>
121
122 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
128 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y10.xml b/Documentation/DocBook/media/v4l/pixfmt-y10.xml
new file mode 100644
index 000000000000..d065043db8d8
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-y10.xml
@@ -0,0 +1,79 @@
1<refentry id="V4L2-PIX-FMT-Y10">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_Y10 ('Y10 ')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_Y10</constant></refname>
8 <refpurpose>Grey-scale image</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is a grey-scale image with a depth of 10 bits per pixel. Pixels
14are stored in 16-bit words with unused high bits padded with 0. The least
15significant byte is stored at lower memory addresses (little-endian).</para>
16
17 <example>
18 <title><constant>V4L2_PIX_FMT_Y10</constant> 4 &times; 4
19pixel image</title>
20
21 <formalpara>
22 <title>Byte Order.</title>
23 <para>Each cell is one byte.
24 <informaltable frame="none">
25 <tgroup cols="9" align="center">
26 <colspec align="left" colwidth="2*" />
27 <tbody valign="top">
28 <row>
29 <entry>start&nbsp;+&nbsp;0:</entry>
30 <entry>Y'<subscript>00low</subscript></entry>
31 <entry>Y'<subscript>00high</subscript></entry>
32 <entry>Y'<subscript>01low</subscript></entry>
33 <entry>Y'<subscript>01high</subscript></entry>
34 <entry>Y'<subscript>02low</subscript></entry>
35 <entry>Y'<subscript>02high</subscript></entry>
36 <entry>Y'<subscript>03low</subscript></entry>
37 <entry>Y'<subscript>03high</subscript></entry>
38 </row>
39 <row>
40 <entry>start&nbsp;+&nbsp;8:</entry>
41 <entry>Y'<subscript>10low</subscript></entry>
42 <entry>Y'<subscript>10high</subscript></entry>
43 <entry>Y'<subscript>11low</subscript></entry>
44 <entry>Y'<subscript>11high</subscript></entry>
45 <entry>Y'<subscript>12low</subscript></entry>
46 <entry>Y'<subscript>12high</subscript></entry>
47 <entry>Y'<subscript>13low</subscript></entry>
48 <entry>Y'<subscript>13high</subscript></entry>
49 </row>
50 <row>
51 <entry>start&nbsp;+&nbsp;16:</entry>
52 <entry>Y'<subscript>20low</subscript></entry>
53 <entry>Y'<subscript>20high</subscript></entry>
54 <entry>Y'<subscript>21low</subscript></entry>
55 <entry>Y'<subscript>21high</subscript></entry>
56 <entry>Y'<subscript>22low</subscript></entry>
57 <entry>Y'<subscript>22high</subscript></entry>
58 <entry>Y'<subscript>23low</subscript></entry>
59 <entry>Y'<subscript>23high</subscript></entry>
60 </row>
61 <row>
62 <entry>start&nbsp;+&nbsp;24:</entry>
63 <entry>Y'<subscript>30low</subscript></entry>
64 <entry>Y'<subscript>30high</subscript></entry>
65 <entry>Y'<subscript>31low</subscript></entry>
66 <entry>Y'<subscript>31high</subscript></entry>
67 <entry>Y'<subscript>32low</subscript></entry>
68 <entry>Y'<subscript>32high</subscript></entry>
69 <entry>Y'<subscript>33low</subscript></entry>
70 <entry>Y'<subscript>33high</subscript></entry>
71 </row>
72 </tbody>
73 </tgroup>
74 </informaltable>
75 </para>
76 </formalpara>
77 </example>
78 </refsect1>
79</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y10b.xml b/Documentation/DocBook/media/v4l/pixfmt-y10b.xml
new file mode 100644
index 000000000000..adb0ad808c93
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-y10b.xml
@@ -0,0 +1,43 @@
1<refentry id="V4L2-PIX-FMT-Y10BPACK">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_Y10BPACK ('Y10B')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_Y10BPACK</constant></refname>
8 <refpurpose>Grey-scale image as a bit-packed array</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is a packed grey-scale image format with a depth of 10 bits per
14 pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel,
15 with no padding between them and with the most significant bits coming
16 first from the left.</para>
17
18 <example>
19 <title><constant>V4L2_PIX_FMT_Y10BPACK</constant> 4 pixel data stream taking 5 bytes</title>
20
21 <formalpara>
22 <title>Bit-packed representation</title>
23 <para>pixels cross the byte boundary and have a ratio of 5 bytes for each 4
24 pixels.
25 <informaltable frame="all">
26 <tgroup cols="5" align="center">
27 <colspec align="left" colwidth="2*" />
28 <tbody valign="top">
29 <row>
30 <entry>Y'<subscript>00[9:2]</subscript></entry>
31 <entry>Y'<subscript>00[1:0]</subscript>Y'<subscript>01[9:4]</subscript></entry>
32 <entry>Y'<subscript>01[3:0]</subscript>Y'<subscript>02[9:6]</subscript></entry>
33 <entry>Y'<subscript>02[5:0]</subscript>Y'<subscript>03[9:8]</subscript></entry>
34 <entry>Y'<subscript>03[7:0]</subscript></entry>
35 </row>
36 </tbody>
37 </tgroup>
38 </informaltable>
39 </para>
40 </formalpara>
41 </example>
42 </refsect1>
43</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y12.xml b/Documentation/DocBook/media/v4l/pixfmt-y12.xml
new file mode 100644
index 000000000000..ff417b858cc9
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-y12.xml
@@ -0,0 +1,79 @@
1<refentry id="V4L2-PIX-FMT-Y12">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_Y12 ('Y12 ')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_Y12</constant></refname>
8 <refpurpose>Grey-scale image</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is a grey-scale image with a depth of 12 bits per pixel. Pixels
14are stored in 16-bit words with unused high bits padded with 0. The least
15significant byte is stored at lower memory addresses (little-endian).</para>
16
17 <example>
18 <title><constant>V4L2_PIX_FMT_Y12</constant> 4 &times; 4
19pixel image</title>
20
21 <formalpara>
22 <title>Byte Order.</title>
23 <para>Each cell is one byte.
24 <informaltable frame="none">
25 <tgroup cols="9" align="center">
26 <colspec align="left" colwidth="2*" />
27 <tbody valign="top">
28 <row>
29 <entry>start&nbsp;+&nbsp;0:</entry>
30 <entry>Y'<subscript>00low</subscript></entry>
31 <entry>Y'<subscript>00high</subscript></entry>
32 <entry>Y'<subscript>01low</subscript></entry>
33 <entry>Y'<subscript>01high</subscript></entry>
34 <entry>Y'<subscript>02low</subscript></entry>
35 <entry>Y'<subscript>02high</subscript></entry>
36 <entry>Y'<subscript>03low</subscript></entry>
37 <entry>Y'<subscript>03high</subscript></entry>
38 </row>
39 <row>
40 <entry>start&nbsp;+&nbsp;8:</entry>
41 <entry>Y'<subscript>10low</subscript></entry>
42 <entry>Y'<subscript>10high</subscript></entry>
43 <entry>Y'<subscript>11low</subscript></entry>
44 <entry>Y'<subscript>11high</subscript></entry>
45 <entry>Y'<subscript>12low</subscript></entry>
46 <entry>Y'<subscript>12high</subscript></entry>
47 <entry>Y'<subscript>13low</subscript></entry>
48 <entry>Y'<subscript>13high</subscript></entry>
49 </row>
50 <row>
51 <entry>start&nbsp;+&nbsp;16:</entry>
52 <entry>Y'<subscript>20low</subscript></entry>
53 <entry>Y'<subscript>20high</subscript></entry>
54 <entry>Y'<subscript>21low</subscript></entry>
55 <entry>Y'<subscript>21high</subscript></entry>
56 <entry>Y'<subscript>22low</subscript></entry>
57 <entry>Y'<subscript>22high</subscript></entry>
58 <entry>Y'<subscript>23low</subscript></entry>
59 <entry>Y'<subscript>23high</subscript></entry>
60 </row>
61 <row>
62 <entry>start&nbsp;+&nbsp;24:</entry>
63 <entry>Y'<subscript>30low</subscript></entry>
64 <entry>Y'<subscript>30high</subscript></entry>
65 <entry>Y'<subscript>31low</subscript></entry>
66 <entry>Y'<subscript>31high</subscript></entry>
67 <entry>Y'<subscript>32low</subscript></entry>
68 <entry>Y'<subscript>32high</subscript></entry>
69 <entry>Y'<subscript>33low</subscript></entry>
70 <entry>Y'<subscript>33high</subscript></entry>
71 </row>
72 </tbody>
73 </tgroup>
74 </informaltable>
75 </para>
76 </formalpara>
77 </example>
78 </refsect1>
79</refentry>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y16.xml b/Documentation/DocBook/media/v4l/pixfmt-y16.xml
new file mode 100644
index 000000000000..d58404015078
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-y16.xml
@@ -0,0 +1,89 @@
1<refentry id="V4L2-PIX-FMT-Y16">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_Y16 ('Y16 ')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_Y16</constant></refname>
8 <refpurpose>Grey-scale image</refpurpose>
9 </refnamediv>
10 <refsect1>
11 <title>Description</title>
12
13 <para>This is a grey-scale image with a depth of 16 bits per
14pixel. The least significant byte is stored at lower memory addresses
15(little-endian). Note the actual sampling precision may be lower than
1616 bits, for example 10 bits per pixel with values in range 0 to
171023.</para>
18
19 <example>
20 <title><constant>V4L2_PIX_FMT_Y16</constant> 4 &times; 4
21pixel image</title>
22
23 <formalpara>
24 <title>Byte Order.</title>
25 <para>Each cell is one byte.
26 <informaltable frame="none">
27 <tgroup cols="9" align="center">
28 <colspec align="left" colwidth="2*" />
29 <tbody valign="top">
30 <row>
31 <entry>start&nbsp;+&nbsp;0:</entry>
32 <entry>Y'<subscript>00low</subscript></entry>
33 <entry>Y'<subscript>00high</subscript></entry>
34 <entry>Y'<subscript>01low</subscript></entry>
35 <entry>Y'<subscript>01high</subscript></entry>
36 <entry>Y'<subscript>02low</subscript></entry>
37 <entry>Y'<subscript>02high</subscript></entry>
38 <entry>Y'<subscript>03low</subscript></entry>
39 <entry>Y'<subscript>03high</subscript></entry>
40 </row>
41 <row>
42 <entry>start&nbsp;+&nbsp;8:</entry>
43 <entry>Y'<subscript>10low</subscript></entry>
44 <entry>Y'<subscript>10high</subscript></entry>
45 <entry>Y'<subscript>11low</subscript></entry>
46 <entry>Y'<subscript>11high</subscript></entry>
47 <entry>Y'<subscript>12low</subscript></entry>
48 <entry>Y'<subscript>12high</subscript></entry>
49 <entry>Y'<subscript>13low</subscript></entry>
50 <entry>Y'<subscript>13high</subscript></entry>
51 </row>
52 <row>
53 <entry>start&nbsp;+&nbsp;16:</entry>
54 <entry>Y'<subscript>20low</subscript></entry>
55 <entry>Y'<subscript>20high</subscript></entry>
56 <entry>Y'<subscript>21low</subscript></entry>
57 <entry>Y'<subscript>21high</subscript></entry>
58 <entry>Y'<subscript>22low</subscript></entry>
59 <entry>Y'<subscript>22high</subscript></entry>
60 <entry>Y'<subscript>23low</subscript></entry>
61 <entry>Y'<subscript>23high</subscript></entry>
62 </row>
63 <row>
64 <entry>start&nbsp;+&nbsp;24:</entry>
65 <entry>Y'<subscript>30low</subscript></entry>
66 <entry>Y'<subscript>30high</subscript></entry>
67 <entry>Y'<subscript>31low</subscript></entry>
68 <entry>Y'<subscript>31high</subscript></entry>
69 <entry>Y'<subscript>32low</subscript></entry>
70 <entry>Y'<subscript>32high</subscript></entry>
71 <entry>Y'<subscript>33low</subscript></entry>
72 <entry>Y'<subscript>33high</subscript></entry>
73 </row>
74 </tbody>
75 </tgroup>
76 </informaltable>
77 </para>
78 </formalpara>
79 </example>
80 </refsect1>
81</refentry>
82
83 <!--
84Local Variables:
85mode: sgml
86sgml-parent-document: "pixfmt.sgml"
87indent-tabs-mode: nil
88End:
89 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-y41p.xml b/Documentation/DocBook/media/v4l/pixfmt-y41p.xml
new file mode 100644
index 000000000000..73c8536efb05
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-y41p.xml
@@ -0,0 +1,157 @@
1 <refentry id="V4L2-PIX-FMT-Y41P">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_Y41P ('Y41P')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_Y41P</constant></refname>
8 <refpurpose>Format with &frac14; horizontal chroma
9resolution, also known as YUV 4:1:1</refpurpose>
10 </refnamediv>
11 <refsect1>
12 <title>Description</title>
13
14 <para>In this format each 12 bytes is eight pixels. In the
15twelve bytes are two CbCr pairs and eight Y's. The first CbCr pair
16goes with the first four Y's, and the second CbCr pair goes with the
17other four Y's. The Cb and Cr components have one fourth the
18horizontal resolution of the Y component.</para>
19
20 <para>Do not confuse this format with <link
21linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link>.
22Y41P is derived from "YUV 4:1:1 <emphasis>packed</emphasis>", while
23YUV411P stands for "YUV 4:1:1 <emphasis>planar</emphasis>".</para>
24
25 <example>
26 <title><constant>V4L2_PIX_FMT_Y41P</constant> 8 &times; 4
27pixel image</title>
28
29 <formalpara>
30 <title>Byte Order</title>
31 <para>Each cell is one byte.
32 <informaltable frame="none">
33 <tgroup cols="13" align="center">
34 <colspec align="left" colwidth="2*" />
35 <tbody valign="top">
36 <row>
37 <entry>start&nbsp;+&nbsp;0:</entry>
38 <entry>Cb<subscript>00</subscript></entry>
39 <entry>Y'<subscript>00</subscript></entry>
40 <entry>Cr<subscript>00</subscript></entry>
41 <entry>Y'<subscript>01</subscript></entry>
42 <entry>Cb<subscript>01</subscript></entry>
43 <entry>Y'<subscript>02</subscript></entry>
44 <entry>Cr<subscript>01</subscript></entry>
45 <entry>Y'<subscript>03</subscript></entry>
46 <entry>Y'<subscript>04</subscript></entry>
47 <entry>Y'<subscript>05</subscript></entry>
48 <entry>Y'<subscript>06</subscript></entry>
49 <entry>Y'<subscript>07</subscript></entry>
50 </row>
51 <row>
52 <entry>start&nbsp;+&nbsp;12:</entry>
53 <entry>Cb<subscript>10</subscript></entry>
54 <entry>Y'<subscript>10</subscript></entry>
55 <entry>Cr<subscript>10</subscript></entry>
56 <entry>Y'<subscript>11</subscript></entry>
57 <entry>Cb<subscript>11</subscript></entry>
58 <entry>Y'<subscript>12</subscript></entry>
59 <entry>Cr<subscript>11</subscript></entry>
60 <entry>Y'<subscript>13</subscript></entry>
61 <entry>Y'<subscript>14</subscript></entry>
62 <entry>Y'<subscript>15</subscript></entry>
63 <entry>Y'<subscript>16</subscript></entry>
64 <entry>Y'<subscript>17</subscript></entry>
65 </row>
66 <row>
67 <entry>start&nbsp;+&nbsp;24:</entry>
68 <entry>Cb<subscript>20</subscript></entry>
69 <entry>Y'<subscript>20</subscript></entry>
70 <entry>Cr<subscript>20</subscript></entry>
71 <entry>Y'<subscript>21</subscript></entry>
72 <entry>Cb<subscript>21</subscript></entry>
73 <entry>Y'<subscript>22</subscript></entry>
74 <entry>Cr<subscript>21</subscript></entry>
75 <entry>Y'<subscript>23</subscript></entry>
76 <entry>Y'<subscript>24</subscript></entry>
77 <entry>Y'<subscript>25</subscript></entry>
78 <entry>Y'<subscript>26</subscript></entry>
79 <entry>Y'<subscript>27</subscript></entry>
80 </row>
81 <row>
82 <entry>start&nbsp;+&nbsp;36:</entry>
83 <entry>Cb<subscript>30</subscript></entry>
84 <entry>Y'<subscript>30</subscript></entry>
85 <entry>Cr<subscript>30</subscript></entry>
86 <entry>Y'<subscript>31</subscript></entry>
87 <entry>Cb<subscript>31</subscript></entry>
88 <entry>Y'<subscript>32</subscript></entry>
89 <entry>Cr<subscript>31</subscript></entry>
90 <entry>Y'<subscript>33</subscript></entry>
91 <entry>Y'<subscript>34</subscript></entry>
92 <entry>Y'<subscript>35</subscript></entry>
93 <entry>Y'<subscript>36</subscript></entry>
94 <entry>Y'<subscript>37</subscript></entry>
95 </row>
96 </tbody>
97 </tgroup>
98 </informaltable></para>
99 </formalpara>
100
101 <formalpara>
102 <title>Color Sample Location.</title>
103 <para>
104 <informaltable frame="none">
105 <tgroup cols="15" align="center">
106 <tbody valign="top">
107 <row>
108 <entry></entry>
109 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
110 <entry>2</entry><entry></entry><entry>3</entry><entry></entry>
111 <entry>4</entry><entry></entry><entry>5</entry><entry></entry>
112 <entry>6</entry><entry></entry><entry>7</entry>
113 </row>
114 <row>
115 <entry>0</entry>
116 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
117 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
118 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
119 <entry>Y</entry><entry></entry><entry>Y</entry>
120 </row>
121 <row>
122 <entry>1</entry>
123 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
124 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
125 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
126 <entry>Y</entry><entry></entry><entry>Y</entry>
127 </row>
128 <row>
129 <entry>2</entry>
130 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
131 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
132 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
133 <entry>Y</entry><entry></entry><entry>Y</entry>
134 </row>
135 <row>
136 <entry>3</entry>
137 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
138 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
139 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
140 <entry>Y</entry><entry></entry><entry>Y</entry>
141 </row>
142 </tbody>
143 </tgroup>
144 </informaltable>
145 </para>
146 </formalpara>
147 </example>
148 </refsect1>
149 </refentry>
150
151 <!--
152Local Variables:
153mode: sgml
154sgml-parent-document: "pixfmt.sgml"
155indent-tabs-mode: nil
156End:
157 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml
new file mode 100644
index 000000000000..8eb4a193d770
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-yuv410.xml
@@ -0,0 +1,141 @@
1 <refentry>
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname id="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></refname>
8 <refname id="V4L2-PIX-FMT-YUV410"><constant>V4L2_PIX_FMT_YUV410</constant></refname>
9 <refpurpose>Planar formats with &frac14; horizontal and
10vertical chroma resolution, also known as YUV 4:1:0</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>These are planar formats, as opposed to a packed format.
16The three components are separated into three sub-images or planes.
17The Y plane is first. The Y plane has one byte per pixel. For
18<constant>V4L2_PIX_FMT_YVU410</constant>, the Cr plane immediately
19follows the Y plane in memory. The Cr plane is &frac14; the width and
20&frac14; the height of the Y plane (and of the image). Each Cr belongs
21to 16 pixels, a four-by-four square of the image. Following the Cr
22plane is the Cb plane, just like the Cr plane.
23<constant>V4L2_PIX_FMT_YUV410</constant> is the same, except the Cb
24plane comes first, then the Cr plane.</para>
25
26 <para>If the Y plane has pad bytes after each row, then the Cr
27and Cb planes have &frac14; as many pad bytes after their rows. In
28other words, four Cx rows (including padding) are exactly as long as
29one Y row (including padding).</para>
30
31 <example>
32 <title><constant>V4L2_PIX_FMT_YVU410</constant> 4 &times; 4
33pixel image</title>
34
35 <formalpara>
36 <title>Byte Order.</title>
37 <para>Each cell is one byte.
38 <informaltable frame="none">
39 <tgroup cols="5" align="center">
40 <colspec align="left" colwidth="2*" />
41 <tbody valign="top">
42 <row>
43 <entry>start&nbsp;+&nbsp;0:</entry>
44 <entry>Y'<subscript>00</subscript></entry>
45 <entry>Y'<subscript>01</subscript></entry>
46 <entry>Y'<subscript>02</subscript></entry>
47 <entry>Y'<subscript>03</subscript></entry>
48 </row>
49 <row>
50 <entry>start&nbsp;+&nbsp;4:</entry>
51 <entry>Y'<subscript>10</subscript></entry>
52 <entry>Y'<subscript>11</subscript></entry>
53 <entry>Y'<subscript>12</subscript></entry>
54 <entry>Y'<subscript>13</subscript></entry>
55 </row>
56 <row>
57 <entry>start&nbsp;+&nbsp;8:</entry>
58 <entry>Y'<subscript>20</subscript></entry>
59 <entry>Y'<subscript>21</subscript></entry>
60 <entry>Y'<subscript>22</subscript></entry>
61 <entry>Y'<subscript>23</subscript></entry>
62 </row>
63 <row>
64 <entry>start&nbsp;+&nbsp;12:</entry>
65 <entry>Y'<subscript>30</subscript></entry>
66 <entry>Y'<subscript>31</subscript></entry>
67 <entry>Y'<subscript>32</subscript></entry>
68 <entry>Y'<subscript>33</subscript></entry>
69 </row>
70 <row>
71 <entry>start&nbsp;+&nbsp;16:</entry>
72 <entry>Cr<subscript>00</subscript></entry>
73 </row>
74 <row>
75 <entry>start&nbsp;+&nbsp;17:</entry>
76 <entry>Cb<subscript>00</subscript></entry>
77 </row>
78 </tbody>
79 </tgroup>
80 </informaltable>
81 </para>
82 </formalpara>
83
84 <formalpara>
85 <title>Color Sample Location.</title>
86 <para>
87 <informaltable frame="none">
88 <tgroup cols="7" align="center">
89 <tbody valign="top">
90 <row>
91 <entry></entry>
92 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
93 <entry>2</entry><entry></entry><entry>3</entry>
94 </row>
95 <row>
96 <entry>0</entry>
97 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
98 <entry>Y</entry><entry></entry><entry>Y</entry>
99 </row>
100 <row>
101 <entry></entry>
102 </row>
103 <row>
104 <entry>1</entry>
105 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
106 <entry>Y</entry><entry></entry><entry>Y</entry>
107 </row>
108 <row>
109 <entry></entry>
110 <entry></entry><entry></entry><entry></entry><entry>C</entry>
111 <entry></entry><entry></entry><entry></entry>
112 </row>
113 <row>
114 <entry>2</entry>
115 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
116 <entry>Y</entry><entry></entry><entry>Y</entry>
117 </row>
118 <row>
119 <entry></entry>
120 </row>
121 <row>
122 <entry>3</entry>
123 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
124 <entry>Y</entry><entry></entry><entry>Y</entry>
125 </row>
126 </tbody>
127 </tgroup>
128 </informaltable>
129 </para>
130 </formalpara>
131 </example>
132 </refsect1>
133 </refentry>
134
135 <!--
136Local Variables:
137mode: sgml
138sgml-parent-document: "pixfmt.sgml"
139indent-tabs-mode: nil
140End:
141 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml
new file mode 100644
index 000000000000..00e0960a9869
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-yuv411p.xml
@@ -0,0 +1,155 @@
1 <refentry id="V4L2-PIX-FMT-YUV411P">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_YUV411P ('411P')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_YUV411P</constant></refname>
8 <refpurpose>Format with &frac14; horizontal chroma resolution,
9also known as YUV 4:1:1. Planar layout as opposed to
10<constant>V4L2_PIX_FMT_Y41P</constant></refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>This format is not commonly used. This is a planar
16format similar to the 4:2:2 planar format except with half as many
17chroma. The three components are separated into three sub-images or
18planes. The Y plane is first. The Y plane has one byte per pixel. The
19Cb plane immediately follows the Y plane in memory. The Cb plane is
20&frac14; the width of the Y plane (and of the image). Each Cb belongs
21to 4 pixels all on the same row. For example,
22Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
23Y'<subscript>01</subscript>, Y'<subscript>02</subscript> and
24Y'<subscript>03</subscript>. Following the Cb plane is the Cr plane,
25just like the Cb plane.</para>
26
27 <para>If the Y plane has pad bytes after each row, then the Cr
28and Cb planes have &frac14; as many pad bytes after their rows. In
29other words, four C x rows (including padding) is exactly as long as
30one Y row (including padding).</para>
31
32 <example>
33 <title><constant>V4L2_PIX_FMT_YUV411P</constant> 4 &times; 4
34pixel image</title>
35
36 <formalpara>
37 <title>Byte Order.</title>
38 <para>Each cell is one byte.
39 <informaltable frame="none">
40 <tgroup cols="5" align="center">
41 <colspec align="left" colwidth="2*" />
42 <tbody valign="top">
43 <row>
44 <entry>start&nbsp;+&nbsp;0:</entry>
45 <entry>Y'<subscript>00</subscript></entry>
46 <entry>Y'<subscript>01</subscript></entry>
47 <entry>Y'<subscript>02</subscript></entry>
48 <entry>Y'<subscript>03</subscript></entry>
49 </row>
50 <row>
51 <entry>start&nbsp;+&nbsp;4:</entry>
52 <entry>Y'<subscript>10</subscript></entry>
53 <entry>Y'<subscript>11</subscript></entry>
54 <entry>Y'<subscript>12</subscript></entry>
55 <entry>Y'<subscript>13</subscript></entry>
56 </row>
57 <row>
58 <entry>start&nbsp;+&nbsp;8:</entry>
59 <entry>Y'<subscript>20</subscript></entry>
60 <entry>Y'<subscript>21</subscript></entry>
61 <entry>Y'<subscript>22</subscript></entry>
62 <entry>Y'<subscript>23</subscript></entry>
63 </row>
64 <row>
65 <entry>start&nbsp;+&nbsp;12:</entry>
66 <entry>Y'<subscript>30</subscript></entry>
67 <entry>Y'<subscript>31</subscript></entry>
68 <entry>Y'<subscript>32</subscript></entry>
69 <entry>Y'<subscript>33</subscript></entry>
70 </row>
71 <row>
72 <entry>start&nbsp;+&nbsp;16:</entry>
73 <entry>Cb<subscript>00</subscript></entry>
74 </row>
75 <row>
76 <entry>start&nbsp;+&nbsp;17:</entry>
77 <entry>Cb<subscript>10</subscript></entry>
78 </row>
79 <row>
80 <entry>start&nbsp;+&nbsp;18:</entry>
81 <entry>Cb<subscript>20</subscript></entry>
82 </row>
83 <row>
84 <entry>start&nbsp;+&nbsp;19:</entry>
85 <entry>Cb<subscript>30</subscript></entry>
86 </row>
87 <row>
88 <entry>start&nbsp;+&nbsp;20:</entry>
89 <entry>Cr<subscript>00</subscript></entry>
90 </row>
91 <row>
92 <entry>start&nbsp;+&nbsp;21:</entry>
93 <entry>Cr<subscript>10</subscript></entry>
94 </row>
95 <row>
96 <entry>start&nbsp;+&nbsp;22:</entry>
97 <entry>Cr<subscript>20</subscript></entry>
98 </row>
99 <row>
100 <entry>start&nbsp;+&nbsp;23:</entry>
101 <entry>Cr<subscript>30</subscript></entry>
102 </row>
103 </tbody>
104 </tgroup>
105 </informaltable>
106 </para>
107 </formalpara>
108
109 <formalpara>
110 <title>Color Sample Location.</title>
111 <para>
112 <informaltable frame="none">
113 <tgroup cols="7" align="center">
114 <tbody valign="top">
115 <row>
116 <entry></entry>
117 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
118 <entry>2</entry><entry></entry><entry>3</entry>
119 </row>
120 <row>
121 <entry>0</entry>
122 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
123 <entry>Y</entry><entry></entry><entry>Y</entry>
124 </row>
125 <row>
126 <entry>1</entry>
127 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
128 <entry>Y</entry><entry></entry><entry>Y</entry>
129 </row>
130 <row>
131 <entry>2</entry>
132 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
133 <entry>Y</entry><entry></entry><entry>Y</entry>
134 </row>
135 <row>
136 <entry>3</entry>
137 <entry>Y</entry><entry></entry><entry>Y</entry><entry>C</entry>
138 <entry>Y</entry><entry></entry><entry>Y</entry>
139 </row>
140 </tbody>
141 </tgroup>
142 </informaltable>
143 </para>
144 </formalpara>
145 </example>
146 </refsect1>
147 </refentry>
148
149 <!--
150Local Variables:
151mode: sgml
152sgml-parent-document: "v4l2.sgml"
153indent-tabs-mode: nil
154End:
155 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml
new file mode 100644
index 000000000000..42d7de5e456d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-yuv420.xml
@@ -0,0 +1,157 @@
1 <refentry>
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname id="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></refname>
8 <refname id="V4L2-PIX-FMT-YUV420"><constant>V4L2_PIX_FMT_YUV420</constant></refname>
9 <refpurpose>Planar formats with &frac12; horizontal and
10vertical chroma resolution, also known as YUV 4:2:0</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>These are planar formats, as opposed to a packed format.
16The three components are separated into three sub- images or planes.
17The Y plane is first. The Y plane has one byte per pixel. For
18<constant>V4L2_PIX_FMT_YVU420</constant>, the Cr plane immediately
19follows the Y plane in memory. The Cr plane is half the width and half
20the height of the Y plane (and of the image). Each Cr belongs to four
21pixels, a two-by-two square of the image. For example,
22Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
23Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and
24Y'<subscript>11</subscript>. Following the Cr plane is the Cb plane,
25just like the Cr plane. <constant>V4L2_PIX_FMT_YUV420</constant> is
26the same except the Cb plane comes first, then the Cr plane.</para>
27
28 <para>If the Y plane has pad bytes after each row, then the Cr
29and Cb planes have half as many pad bytes after their rows. In other
30words, two Cx rows (including padding) is exactly as long as one Y row
31(including padding).</para>
32
33 <example>
34 <title><constant>V4L2_PIX_FMT_YVU420</constant> 4 &times; 4
35pixel 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>start&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>start&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>start&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>start&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>start&nbsp;+&nbsp;16:</entry>
74 <entry>Cr<subscript>00</subscript></entry>
75 <entry>Cr<subscript>01</subscript></entry>
76 </row>
77 <row>
78 <entry>start&nbsp;+&nbsp;18:</entry>
79 <entry>Cr<subscript>10</subscript></entry>
80 <entry>Cr<subscript>11</subscript></entry>
81 </row>
82 <row>
83 <entry>start&nbsp;+&nbsp;20:</entry>
84 <entry>Cb<subscript>00</subscript></entry>
85 <entry>Cb<subscript>01</subscript></entry>
86 </row>
87 <row>
88 <entry>start&nbsp;+&nbsp;22:</entry>
89 <entry>Cb<subscript>10</subscript></entry>
90 <entry>Cb<subscript>11</subscript></entry>
91 </row>
92 </tbody>
93 </tgroup>
94 </informaltable>
95 </para>
96 </formalpara>
97
98 <formalpara>
99 <title>Color Sample Location.</title>
100 <para>
101 <informaltable frame="none">
102 <tgroup cols="7" align="center">
103 <tbody valign="top">
104 <row>
105 <entry></entry>
106 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
107 <entry>2</entry><entry></entry><entry>3</entry>
108 </row>
109 <row>
110 <entry>0</entry>
111 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
112 <entry>Y</entry><entry></entry><entry>Y</entry>
113 </row>
114 <row>
115 <entry></entry>
116 <entry></entry><entry>C</entry><entry></entry><entry></entry>
117 <entry></entry><entry>C</entry><entry></entry>
118 </row>
119 <row>
120 <entry>1</entry>
121 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
122 <entry>Y</entry><entry></entry><entry>Y</entry>
123 </row>
124 <row>
125 <entry></entry>
126 </row>
127 <row>
128 <entry>2</entry>
129 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
130 <entry>Y</entry><entry></entry><entry>Y</entry>
131 </row>
132 <row>
133 <entry></entry>
134 <entry></entry><entry>C</entry><entry></entry><entry></entry>
135 <entry></entry><entry>C</entry><entry></entry>
136 </row>
137 <row>
138 <entry>3</entry>
139 <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry>
140 <entry>Y</entry><entry></entry><entry>Y</entry>
141 </row>
142 </tbody>
143 </tgroup>
144 </informaltable>
145 </para>
146 </formalpara>
147 </example>
148 </refsect1>
149 </refentry>
150
151 <!--
152Local Variables:
153mode: sgml
154sgml-parent-document: "pixfmt.sgml"
155indent-tabs-mode: nil
156End:
157 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv420m.xml
new file mode 100644
index 000000000000..f5d8f57495c8
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/pixfmt-yuv422p.xml b/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml
new file mode 100644
index 000000000000..4348bd9f0d01
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-yuv422p.xml
@@ -0,0 +1,161 @@
1 <refentry id="V4L2-PIX-FMT-YUV422P">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_YUV422P ('422P')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_YUV422P</constant></refname>
8 <refpurpose>Format with &frac12; horizontal chroma resolution,
9also known as YUV 4:2:2. Planar layout as opposed to
10<constant>V4L2_PIX_FMT_YUYV</constant></refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>This format is not commonly used. This is a planar
16version of the YUYV format. The three components are separated into
17three sub-images or planes. The Y plane is first. The Y plane has one
18byte per pixel. The Cb plane immediately follows the Y plane in
19memory. The Cb plane is half the width of the Y plane (and of the
20image). Each Cb belongs to two pixels. For example,
21Cb<subscript>0</subscript> belongs to Y'<subscript>00</subscript>,
22Y'<subscript>01</subscript>. Following the Cb plane is the Cr plane,
23just like the Cb plane.</para>
24
25 <para>If the Y plane has pad bytes after each row, then the Cr
26and Cb planes have half as many pad bytes after their rows. In other
27words, two Cx rows (including padding) is exactly as long as one Y row
28(including padding).</para>
29
30 <example>
31 <title><constant>V4L2_PIX_FMT_YUV422P</constant> 4 &times; 4
32pixel image</title>
33
34 <formalpara>
35 <title>Byte Order.</title>
36 <para>Each cell is one byte.
37 <informaltable frame="none">
38 <tgroup cols="5" align="center">
39 <colspec align="left" colwidth="2*" />
40 <tbody valign="top">
41 <row>
42 <entry>start&nbsp;+&nbsp;0:</entry>
43 <entry>Y'<subscript>00</subscript></entry>
44 <entry>Y'<subscript>01</subscript></entry>
45 <entry>Y'<subscript>02</subscript></entry>
46 <entry>Y'<subscript>03</subscript></entry>
47 </row>
48 <row>
49 <entry>start&nbsp;+&nbsp;4:</entry>
50 <entry>Y'<subscript>10</subscript></entry>
51 <entry>Y'<subscript>11</subscript></entry>
52 <entry>Y'<subscript>12</subscript></entry>
53 <entry>Y'<subscript>13</subscript></entry>
54 </row>
55 <row>
56 <entry>start&nbsp;+&nbsp;8:</entry>
57 <entry>Y'<subscript>20</subscript></entry>
58 <entry>Y'<subscript>21</subscript></entry>
59 <entry>Y'<subscript>22</subscript></entry>
60 <entry>Y'<subscript>23</subscript></entry>
61 </row>
62 <row>
63 <entry>start&nbsp;+&nbsp;12:</entry>
64 <entry>Y'<subscript>30</subscript></entry>
65 <entry>Y'<subscript>31</subscript></entry>
66 <entry>Y'<subscript>32</subscript></entry>
67 <entry>Y'<subscript>33</subscript></entry>
68 </row>
69 <row>
70 <entry>start&nbsp;+&nbsp;16:</entry>
71 <entry>Cb<subscript>00</subscript></entry>
72 <entry>Cb<subscript>01</subscript></entry>
73 </row>
74 <row>
75 <entry>start&nbsp;+&nbsp;18:</entry>
76 <entry>Cb<subscript>10</subscript></entry>
77 <entry>Cb<subscript>11</subscript></entry>
78 </row>
79 <row>
80 <entry>start&nbsp;+&nbsp;20:</entry>
81 <entry>Cb<subscript>20</subscript></entry>
82 <entry>Cb<subscript>21</subscript></entry>
83 </row>
84 <row>
85 <entry>start&nbsp;+&nbsp;22:</entry>
86 <entry>Cb<subscript>30</subscript></entry>
87 <entry>Cb<subscript>31</subscript></entry>
88 </row>
89 <row>
90 <entry>start&nbsp;+&nbsp;24:</entry>
91 <entry>Cr<subscript>00</subscript></entry>
92 <entry>Cr<subscript>01</subscript></entry>
93 </row>
94 <row>
95 <entry>start&nbsp;+&nbsp;26:</entry>
96 <entry>Cr<subscript>10</subscript></entry>
97 <entry>Cr<subscript>11</subscript></entry>
98 </row>
99 <row>
100 <entry>start&nbsp;+&nbsp;28:</entry>
101 <entry>Cr<subscript>20</subscript></entry>
102 <entry>Cr<subscript>21</subscript></entry>
103 </row>
104 <row>
105 <entry>start&nbsp;+&nbsp;30:</entry>
106 <entry>Cr<subscript>30</subscript></entry>
107 <entry>Cr<subscript>31</subscript></entry>
108 </row>
109 </tbody>
110 </tgroup>
111 </informaltable>
112 </para>
113 </formalpara>
114
115 <formalpara>
116 <title>Color Sample Location.</title>
117 <para>
118 <informaltable frame="none">
119 <tgroup cols="7" align="center">
120 <tbody valign="top">
121 <row>
122 <entry></entry>
123 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
124 <entry>2</entry><entry></entry><entry>3</entry>
125 </row>
126 <row>
127 <entry>0</entry>
128 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
129 <entry>Y</entry><entry>C</entry><entry>Y</entry>
130 </row>
131 <row>
132 <entry>1</entry>
133 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
134 <entry>Y</entry><entry>C</entry><entry>Y</entry>
135 </row>
136 <row>
137 <entry>2</entry>
138 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
139 <entry>Y</entry><entry>C</entry><entry>Y</entry>
140 </row>
141 <row>
142 <entry>3</entry>
143 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
144 <entry>Y</entry><entry>C</entry><entry>Y</entry>
145 </row>
146 </tbody>
147 </tgroup>
148 </informaltable>
149 </para>
150 </formalpara>
151 </example>
152 </refsect1>
153 </refentry>
154
155 <!--
156Local Variables:
157mode: sgml
158sgml-parent-document: "pixfmt.sgml"
159indent-tabs-mode: nil
160End:
161 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml b/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml
new file mode 100644
index 000000000000..bdb2ffacbbcc
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-yuyv.xml
@@ -0,0 +1,128 @@
1 <refentry id="V4L2-PIX-FMT-YUYV">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_YUYV ('YUYV')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_YUYV</constant></refname>
8 <refpurpose>Packed format with &frac12; horizontal chroma
9resolution, also known as YUV 4:2:2</refpurpose>
10 </refnamediv>
11 <refsect1>
12 <title>Description</title>
13
14 <para>In this format each four bytes is two pixels. Each four
15bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
16the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
17components have half the horizontal resolution of the Y component.
18<constant>V4L2_PIX_FMT_YUYV </constant> is known in the Windows
19environment as YUY2.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_YUYV</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="9" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>Y'<subscript>00</subscript></entry>
35 <entry>Cb<subscript>00</subscript></entry>
36 <entry>Y'<subscript>01</subscript></entry>
37 <entry>Cr<subscript>00</subscript></entry>
38 <entry>Y'<subscript>02</subscript></entry>
39 <entry>Cb<subscript>01</subscript></entry>
40 <entry>Y'<subscript>03</subscript></entry>
41 <entry>Cr<subscript>01</subscript></entry>
42 </row>
43 <row>
44 <entry>start&nbsp;+&nbsp;8:</entry>
45 <entry>Y'<subscript>10</subscript></entry>
46 <entry>Cb<subscript>10</subscript></entry>
47 <entry>Y'<subscript>11</subscript></entry>
48 <entry>Cr<subscript>10</subscript></entry>
49 <entry>Y'<subscript>12</subscript></entry>
50 <entry>Cb<subscript>11</subscript></entry>
51 <entry>Y'<subscript>13</subscript></entry>
52 <entry>Cr<subscript>11</subscript></entry>
53 </row>
54 <row>
55 <entry>start&nbsp;+&nbsp;16:</entry>
56 <entry>Y'<subscript>20</subscript></entry>
57 <entry>Cb<subscript>20</subscript></entry>
58 <entry>Y'<subscript>21</subscript></entry>
59 <entry>Cr<subscript>20</subscript></entry>
60 <entry>Y'<subscript>22</subscript></entry>
61 <entry>Cb<subscript>21</subscript></entry>
62 <entry>Y'<subscript>23</subscript></entry>
63 <entry>Cr<subscript>21</subscript></entry>
64 </row>
65 <row>
66 <entry>start&nbsp;+&nbsp;24:</entry>
67 <entry>Y'<subscript>30</subscript></entry>
68 <entry>Cb<subscript>30</subscript></entry>
69 <entry>Y'<subscript>31</subscript></entry>
70 <entry>Cr<subscript>30</subscript></entry>
71 <entry>Y'<subscript>32</subscript></entry>
72 <entry>Cb<subscript>31</subscript></entry>
73 <entry>Y'<subscript>33</subscript></entry>
74 <entry>Cr<subscript>31</subscript></entry>
75 </row>
76 </tbody>
77 </tgroup>
78 </informaltable>
79 </para>
80 </formalpara>
81
82 <formalpara>
83 <title>Color Sample Location.</title>
84 <para>
85 <informaltable frame="none">
86 <tgroup cols="7" align="center">
87 <tbody valign="top">
88 <row>
89 <entry></entry>
90 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
91 <entry>2</entry><entry></entry><entry>3</entry>
92 </row>
93 <row>
94 <entry>0</entry>
95 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
96 <entry>Y</entry><entry>C</entry><entry>Y</entry>
97 </row>
98 <row>
99 <entry>1</entry>
100 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
101 <entry>Y</entry><entry>C</entry><entry>Y</entry>
102 </row>
103 <row>
104 <entry>2</entry>
105 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
106 <entry>Y</entry><entry>C</entry><entry>Y</entry>
107 </row>
108 <row>
109 <entry>3</entry>
110 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
111 <entry>Y</entry><entry>C</entry><entry>Y</entry>
112 </row>
113 </tbody>
114 </tgroup>
115 </informaltable>
116 </para>
117 </formalpara>
118 </example>
119 </refsect1>
120 </refentry>
121
122 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
128 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml b/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml
new file mode 100644
index 000000000000..40d17ae39dde
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt-yvyu.xml
@@ -0,0 +1,128 @@
1 <refentry id="V4L2-PIX-FMT-YVYU">
2 <refmeta>
3 <refentrytitle>V4L2_PIX_FMT_YVYU ('YVYU')</refentrytitle>
4 &manvol;
5 </refmeta>
6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_YVYU</constant></refname>
8 <refpurpose>Variation of
9<constant>V4L2_PIX_FMT_YUYV</constant> with different order of samples
10in memory</refpurpose>
11 </refnamediv>
12 <refsect1>
13 <title>Description</title>
14
15 <para>In this format each four bytes is two pixels. Each four
16bytes is two Y's, a Cb and a Cr. Each Y goes to one of the pixels, and
17the Cb and Cr belong to both pixels. As you can see, the Cr and Cb
18components have half the horizontal resolution of the Y
19component.</para>
20
21 <example>
22 <title><constant>V4L2_PIX_FMT_YVYU</constant> 4 &times; 4
23pixel image</title>
24
25 <formalpara>
26 <title>Byte Order.</title>
27 <para>Each cell is one byte.
28 <informaltable frame="none">
29 <tgroup cols="9" align="center">
30 <colspec align="left" colwidth="2*" />
31 <tbody valign="top">
32 <row>
33 <entry>start&nbsp;+&nbsp;0:</entry>
34 <entry>Y'<subscript>00</subscript></entry>
35 <entry>Cr<subscript>00</subscript></entry>
36 <entry>Y'<subscript>01</subscript></entry>
37 <entry>Cb<subscript>00</subscript></entry>
38 <entry>Y'<subscript>02</subscript></entry>
39 <entry>Cr<subscript>01</subscript></entry>
40 <entry>Y'<subscript>03</subscript></entry>
41 <entry>Cb<subscript>01</subscript></entry>
42 </row>
43 <row>
44 <entry>start&nbsp;+&nbsp;8:</entry>
45 <entry>Y'<subscript>10</subscript></entry>
46 <entry>Cr<subscript>10</subscript></entry>
47 <entry>Y'<subscript>11</subscript></entry>
48 <entry>Cb<subscript>10</subscript></entry>
49 <entry>Y'<subscript>12</subscript></entry>
50 <entry>Cr<subscript>11</subscript></entry>
51 <entry>Y'<subscript>13</subscript></entry>
52 <entry>Cb<subscript>11</subscript></entry>
53 </row>
54 <row>
55 <entry>start&nbsp;+&nbsp;16:</entry>
56 <entry>Y'<subscript>20</subscript></entry>
57 <entry>Cr<subscript>20</subscript></entry>
58 <entry>Y'<subscript>21</subscript></entry>
59 <entry>Cb<subscript>20</subscript></entry>
60 <entry>Y'<subscript>22</subscript></entry>
61 <entry>Cr<subscript>21</subscript></entry>
62 <entry>Y'<subscript>23</subscript></entry>
63 <entry>Cb<subscript>21</subscript></entry>
64 </row>
65 <row>
66 <entry>start&nbsp;+&nbsp;24:</entry>
67 <entry>Y'<subscript>30</subscript></entry>
68 <entry>Cr<subscript>30</subscript></entry>
69 <entry>Y'<subscript>31</subscript></entry>
70 <entry>Cb<subscript>30</subscript></entry>
71 <entry>Y'<subscript>32</subscript></entry>
72 <entry>Cr<subscript>31</subscript></entry>
73 <entry>Y'<subscript>33</subscript></entry>
74 <entry>Cb<subscript>31</subscript></entry>
75 </row>
76 </tbody>
77 </tgroup>
78 </informaltable>
79 </para>
80 </formalpara>
81
82 <formalpara>
83 <title>Color Sample Location.</title>
84 <para>
85 <informaltable frame="none">
86 <tgroup cols="7" align="center">
87 <tbody valign="top">
88 <row>
89 <entry></entry>
90 <entry>0</entry><entry></entry><entry>1</entry><entry></entry>
91 <entry>2</entry><entry></entry><entry>3</entry>
92 </row>
93 <row>
94 <entry>0</entry>
95 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
96 <entry>Y</entry><entry>C</entry><entry>Y</entry>
97 </row>
98 <row>
99 <entry>1</entry>
100 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
101 <entry>Y</entry><entry>C</entry><entry>Y</entry>
102 </row>
103 <row>
104 <entry>2</entry>
105 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
106 <entry>Y</entry><entry>C</entry><entry>Y</entry>
107 </row>
108 <row>
109 <entry>3</entry>
110 <entry>Y</entry><entry>C</entry><entry>Y</entry><entry></entry>
111 <entry>Y</entry><entry>C</entry><entry>Y</entry>
112 </row>
113 </tbody>
114 </tgroup>
115 </informaltable>
116 </para>
117 </formalpara>
118 </example>
119 </refsect1>
120 </refentry>
121
122 <!--
123Local Variables:
124mode: sgml
125sgml-parent-document: "pixfmt.sgml"
126indent-tabs-mode: nil
127End:
128 -->
diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml
new file mode 100644
index 000000000000..deb660207f94
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/pixfmt.xml
@@ -0,0 +1,951 @@
1 <title>Image Formats</title>
2
3 <para>The V4L2 API was primarily designed for devices exchanging
4image data with applications. The
5<structname>v4l2_pix_format</structname> and <structname>v4l2_pix_format_mplane
6</structname> structures define the format and layout of an image in memory.
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
10capturing and output, for overlay frame buffer formats see also
11&VIDIOC-G-FBUF;.)</para>
12
13<section>
14 <title>Single-planar format structure</title>
15 <table pgwide="1" frame="none" id="v4l2-pix-format">
16 <title>struct <structname>v4l2_pix_format</structname></title>
17 <tgroup cols="3">
18 &cs-str;
19 <tbody valign="top">
20 <row>
21 <entry>__u32</entry>
22 <entry><structfield>width</structfield></entry>
23 <entry>Image width in pixels.</entry>
24 </row>
25 <row>
26 <entry>__u32</entry>
27 <entry><structfield>height</structfield></entry>
28 <entry>Image height in pixels.</entry>
29 </row>
30 <row>
31 <entry spanname="hspan">Applications set these fields to
32request an image size, drivers return the closest possible values. In
33case of planar formats the <structfield>width</structfield> and
34<structfield>height</structfield> applies to the largest plane. To
35avoid ambiguities drivers must return values rounded up to a multiple
36of the scale factor of any smaller planes. For example when the image
37format is YUV 4:2:0, <structfield>width</structfield> and
38<structfield>height</structfield> must be multiples of two.</entry>
39 </row>
40 <row>
41 <entry>__u32</entry>
42 <entry><structfield>pixelformat</structfield></entry>
43 <entry>The pixel format or type of compression, set by the
44application. This is a little endian <link
45linkend="v4l2-fourcc">four character code</link>. V4L2 defines
46standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref
47linkend="yuv-formats" />, and reserved codes in <xref
48linkend="reserved-formats" /></entry>
49 </row>
50 <row>
51 <entry>&v4l2-field;</entry>
52 <entry><structfield>field</structfield></entry>
53 <entry>Video images are typically interlaced. Applications
54can request to capture or output only the top or bottom field, or both
55fields interlaced or sequentially stored in one buffer or alternating
56in separate buffers. Drivers return the actual field order selected.
57For details see <xref linkend="field-order" />.</entry>
58 </row>
59 <row>
60 <entry>__u32</entry>
61 <entry><structfield>bytesperline</structfield></entry>
62 <entry>Distance in bytes between the leftmost pixels in two
63adjacent lines.</entry>
64 </row>
65 <row>
66 <entry spanname="hspan"><para>Both applications and drivers
67can set this field to request padding bytes at the end of each line.
68Drivers however may ignore the value requested by the application,
69returning <structfield>width</structfield> times bytes per pixel or a
70larger value required by the hardware. That implies applications can
71just set this field to zero to get a reasonable
72default.</para><para>Video hardware may access padding bytes,
73therefore they must reside in accessible memory. Consider cases where
74padding bytes after the last line of an image cross a system page
75boundary. Input devices may write padding bytes, the value is
76undefined. Output devices ignore the contents of padding
77bytes.</para><para>When the image format is planar the
78<structfield>bytesperline</structfield> value applies to the largest
79plane and is divided by the same factor as the
80<structfield>width</structfield> field for any smaller planes. For
81example the Cb and Cr planes of a YUV 4:2:0 image have half as many
82padding bytes following each line as the Y plane. To avoid ambiguities
83drivers must return a <structfield>bytesperline</structfield> value
84rounded up to a multiple of the scale factor.</para></entry>
85 </row>
86 <row>
87 <entry>__u32</entry>
88 <entry><structfield>sizeimage</structfield></entry>
89 <entry>Size in bytes of the buffer to hold a complete image,
90set by the driver. Usually this is
91<structfield>bytesperline</structfield> times
92<structfield>height</structfield>. When the image consists of variable
93length compressed data this is the maximum number of bytes required to
94hold an image.</entry>
95 </row>
96 <row>
97 <entry>&v4l2-colorspace;</entry>
98 <entry><structfield>colorspace</structfield></entry>
99 <entry>This information supplements the
100<structfield>pixelformat</structfield> and must be set by the driver,
101see <xref linkend="colorspaces" />.</entry>
102 </row>
103 <row>
104 <entry>__u32</entry>
105 <entry><structfield>priv</structfield></entry>
106 <entry>Reserved for custom (driver defined) additional
107information about formats. When not used drivers and applications must
108set this field to zero.</entry>
109 </row>
110 </tbody>
111 </tgroup>
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>
205
206 <section>
207 <title>Standard Image Formats</title>
208
209 <para>In order to exchange images between drivers and
210applications, it is necessary to have standard image data formats
211which both sides will interpret the same way. V4L2 includes several
212such formats, and this section is intended to be an unambiguous
213specification of the standard image data formats in V4L2.</para>
214
215 <para>V4L2 drivers are not limited to these formats, however.
216Driver-specific formats are possible. In that case the application may
217depend on a codec to convert images to one of the standard formats
218when needed. But the data can still be stored and retrieved in the
219proprietary format. For example, a device may support a proprietary
220compressed format. Applications can still capture and save the data in
221the compressed format, saving much disk space, and later use a codec
222to convert the images to the X Windows screen format when the video is
223to be displayed.</para>
224
225 <para>Even so, ultimately, some standard formats are needed, so
226the V4L2 specification would not be complete without well-defined
227standard formats.</para>
228
229 <para>The V4L2 standard formats are mainly uncompressed formats. The
230pixels are always arranged in memory from left to right, and from top
231to bottom. The first byte of data in the image buffer is always for
232the leftmost pixel of the topmost row. Following that is the pixel
233immediately to its right, and so on until the end of the top row of
234pixels. Following the rightmost pixel of the row there may be zero or
235more bytes of padding to guarantee that each row of pixel data has a
236certain alignment. Following the pad bytes, if any, is data for the
237leftmost pixel of the second row from the top, and so on. The last row
238has just as many pad bytes after it as the other rows.</para>
239
240 <para>In V4L2 each format has an identifier which looks like
241<constant>PIX_FMT_XXX</constant>, defined in the <link
242linkend="videodev">videodev.h</link> header file. These identifiers
243represent <link linkend="v4l2-fourcc">four character (FourCC) codes</link>
244which are also listed below, however they are not the same as those
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>
254 </section>
255
256 <section id="colorspaces">
257 <title>Colorspaces</title>
258
259 <para>[intro]</para>
260
261 <!-- See proposal by Billy Biggs, video4linux-list@redhat.com
262on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and
263http://vektor.theorem.ca/graphics/ycbcr/ and
264http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html -->
265
266 <para>
267 <variablelist>
268 <varlistentry>
269 <term>Gamma Correction</term>
270 <listitem>
271 <para>[to do]</para>
272 <para>E'<subscript>R</subscript> = f(R)</para>
273 <para>E'<subscript>G</subscript> = f(G)</para>
274 <para>E'<subscript>B</subscript> = f(B)</para>
275 </listitem>
276 </varlistentry>
277 <varlistentry>
278 <term>Construction of luminance and color-difference
279signals</term>
280 <listitem>
281 <para>[to do]</para>
282 <para>E'<subscript>Y</subscript> =
283Coeff<subscript>R</subscript> E'<subscript>R</subscript>
284+ Coeff<subscript>G</subscript> E'<subscript>G</subscript>
285+ Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
286 <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript>
287- Coeff<subscript>R</subscript> E'<subscript>R</subscript>
288- Coeff<subscript>G</subscript> E'<subscript>G</subscript>
289- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
290 <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript>
291- Coeff<subscript>R</subscript> E'<subscript>R</subscript>
292- Coeff<subscript>G</subscript> E'<subscript>G</subscript>
293- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
294 </listitem>
295 </varlistentry>
296 <varlistentry>
297 <term>Re-normalized color-difference signals</term>
298 <listitem>
299 <para>The color-difference signals are scaled back to unity
300range [-0.5;+0.5]:</para>
301 <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para>
302 <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para>
303 <para>P<subscript>B</subscript> =
304K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) =
305 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript>
306+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript>
307+ 0.5 E'<subscript>B</subscript></para>
308 <para>P<subscript>R</subscript> =
309K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) =
310 0.5 E'<subscript>R</subscript>
311+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript>
312+ 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para>
313 </listitem>
314 </varlistentry>
315 <varlistentry>
316 <term>Quantization</term>
317 <listitem>
318 <para>[to do]</para>
319 <para>Y' = (Lum. Levels - 1) &middot; E'<subscript>Y</subscript> + Lum. Offset</para>
320 <para>C<subscript>B</subscript> = (Chrom. Levels - 1)
321&middot; P<subscript>B</subscript> + Chrom. Offset</para>
322 <para>C<subscript>R</subscript> = (Chrom. Levels - 1)
323&middot; P<subscript>R</subscript> + Chrom. Offset</para>
324 <para>Rounding to the nearest integer and clamping to the range
325[0;255] finally yields the digital color components Y'CbCr
326stored in YUV images.</para>
327 </listitem>
328 </varlistentry>
329 </variablelist>
330 </para>
331
332 <example>
333 <title>ITU-R Rec. BT.601 color conversion</title>
334
335 <para>Forward Transformation</para>
336
337 <programlisting>
338int ER, EG, EB; /* gamma corrected RGB input [0;255] */
339int Y1, Cb, Cr; /* output [0;255] */
340
341double r, g, b; /* temporaries */
342double y1, pb, pr;
343
344int
345clamp (double x)
346{
347 int r = x; /* round to nearest */
348
349 if (r &lt; 0) return 0;
350 else if (r &gt; 255) return 255;
351 else return r;
352}
353
354r = ER / 255.0;
355g = EG / 255.0;
356b = EB / 255.0;
357
358y1 = 0.299 * r + 0.587 * g + 0.114 * b;
359pb = -0.169 * r - 0.331 * g + 0.5 * b;
360pr = 0.5 * r - 0.419 * g - 0.081 * b;
361
362Y1 = clamp (219 * y1 + 16);
363Cb = clamp (224 * pb + 128);
364Cr = clamp (224 * pr + 128);
365
366/* or shorter */
367
368y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB;
369
370Y1 = clamp ( (219 / 255.0) * y1 + 16);
371Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128);
372Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128);
373 </programlisting>
374
375 <para>Inverse Transformation</para>
376
377 <programlisting>
378int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */
379int ER, EG, EB; /* output [0;255] */
380
381double r, g, b; /* temporaries */
382double y1, pb, pr;
383
384int
385clamp (double x)
386{
387 int r = x; /* round to nearest */
388
389 if (r &lt; 0) return 0;
390 else if (r &gt; 255) return 255;
391 else return r;
392}
393
394y1 = (255 / 219.0) * (Y1 - 16);
395pb = (255 / 224.0) * (Cb - 128);
396pr = (255 / 224.0) * (Cr - 128);
397
398r = 1.0 * y1 + 0 * pb + 1.402 * pr;
399g = 1.0 * y1 - 0.344 * pb - 0.714 * pr;
400b = 1.0 * y1 + 1.772 * pb + 0 * pr;
401
402ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */
403EG = clamp (g * 255);
404EB = clamp (b * 255);
405 </programlisting>
406 </example>
407
408 <table pgwide="1" id="v4l2-colorspace" orient="land">
409 <title>enum v4l2_colorspace</title>
410 <tgroup cols="11" align="center">
411 <colspec align="left" />
412 <colspec align="center" />
413 <colspec align="left" />
414 <colspec colname="cr" />
415 <colspec colname="cg" />
416 <colspec colname="cb" />
417 <colspec colname="wp" />
418 <colspec colname="gc" />
419 <colspec colname="lum" />
420 <colspec colname="qy" />
421 <colspec colname="qc" />
422 <spanspec namest="cr" nameend="cb" spanname="chrom" />
423 <spanspec namest="qy" nameend="qc" spanname="quant" />
424 <spanspec namest="lum" nameend="qc" spanname="spam" />
425 <thead>
426 <row>
427 <entry morerows="1">Identifier</entry>
428 <entry morerows="1">Value</entry>
429 <entry morerows="1">Description</entry>
430 <entry spanname="chrom">Chromaticities<footnote>
431 <para>The coordinates of the color primaries are
432given in the CIE system (1931)</para>
433 </footnote></entry>
434 <entry morerows="1">White Point</entry>
435 <entry morerows="1">Gamma Correction</entry>
436 <entry morerows="1">Luminance E'<subscript>Y</subscript></entry>
437 <entry spanname="quant">Quantization</entry>
438 </row>
439 <row>
440 <entry>Red</entry>
441 <entry>Green</entry>
442 <entry>Blue</entry>
443 <entry>Y'</entry>
444 <entry>Cb, Cr</entry>
445 </row>
446 </thead>
447 <tbody valign="top">
448 <row>
449 <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry>
450 <entry>1</entry>
451 <entry>NTSC/PAL according to <xref linkend="smpte170m" />,
452<xref linkend="itu601" /></entry>
453 <entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
454 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
455 <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
456 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
457 Illuminant D<subscript>65</subscript></entry>
458 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
4591.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
460 <entry>0.299&nbsp;E'<subscript>R</subscript>
461+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
462+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
463 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
464 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
465 </row>
466 <row>
467 <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry>
468 <entry>2</entry>
469 <entry>1125-Line (US) HDTV, see <xref
470linkend="smpte240m" /></entry>
471 <entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
472 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
473 <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
474 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
475 Illuminant D<subscript>65</subscript></entry>
476 <entry>E' = 4&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.0228,
4771.1115&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.1115&nbsp;for&nbsp;0.0228&nbsp;&lt;&nbsp;I</entry>
478 <entry>0.212&nbsp;E'<subscript>R</subscript>
479+&nbsp;0.701&nbsp;E'<subscript>G</subscript>
480+&nbsp;0.087&nbsp;E'<subscript>B</subscript></entry>
481 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
482 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
483 </row>
484 <row>
485 <entry><constant>V4L2_COLORSPACE_REC709</constant></entry>
486 <entry>3</entry>
487 <entry>HDTV and modern devices, see <xref
488linkend="itu709" /></entry>
489 <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
490 <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
491 <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
492 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
493 Illuminant D<subscript>65</subscript></entry>
494 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
4951.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
496 <entry>0.2125&nbsp;E'<subscript>R</subscript>
497+&nbsp;0.7154&nbsp;E'<subscript>G</subscript>
498+&nbsp;0.0721&nbsp;E'<subscript>B</subscript></entry>
499 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
500 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
501 </row>
502 <row>
503 <entry><constant>V4L2_COLORSPACE_BT878</constant></entry>
504 <entry>4</entry>
505 <entry>Broken Bt878 extents<footnote>
506 <para>The ubiquitous Bt878 video capture chip
507quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range
508of Y' = 16 &hellip; 253, unlike Rec. 601 Y' = 16 &hellip;
509235. This is not a typo in the Bt878 documentation, it has been
510implemented in silicon. The chroma extents are unclear.</para>
511 </footnote>, <xref linkend="itu601" /></entry>
512 <entry>?</entry>
513 <entry>?</entry>
514 <entry>?</entry>
515 <entry>?</entry>
516 <entry>?</entry>
517 <entry>0.299&nbsp;E'<subscript>R</subscript>
518+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
519+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
520 <entry><emphasis>237</emphasis>&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
521 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128 (probably)</entry>
522 </row>
523 <row>
524 <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry>
525 <entry>5</entry>
526 <entry>M/NTSC<footnote>
527 <para>No identifier exists for M/PAL which uses
528the chromaticities of M/NTSC, the remaining parameters are equal to B and
529G/PAL.</para>
530 </footnote> according to <xref linkend="itu470" />, <xref
531 linkend="itu601" /></entry>
532 <entry>x&nbsp;=&nbsp;0.67, y&nbsp;=&nbsp;0.33</entry>
533 <entry>x&nbsp;=&nbsp;0.21, y&nbsp;=&nbsp;0.71</entry>
534 <entry>x&nbsp;=&nbsp;0.14, y&nbsp;=&nbsp;0.08</entry>
535 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.316, Illuminant C</entry>
536 <entry>?</entry>
537 <entry>0.299&nbsp;E'<subscript>R</subscript>
538+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
539+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
540 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
541 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
542 </row>
543 <row>
544 <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry>
545 <entry>6</entry>
546 <entry>625-line PAL and SECAM systems according to <xref
547linkend="itu470" />, <xref linkend="itu601" /></entry>
548 <entry>x&nbsp;=&nbsp;0.64, y&nbsp;=&nbsp;0.33</entry>
549 <entry>x&nbsp;=&nbsp;0.29, y&nbsp;=&nbsp;0.60</entry>
550 <entry>x&nbsp;=&nbsp;0.15, y&nbsp;=&nbsp;0.06</entry>
551 <entry>x&nbsp;=&nbsp;0.313, y&nbsp;=&nbsp;0.329,
552Illuminant D<subscript>65</subscript></entry>
553 <entry>?</entry>
554 <entry>0.299&nbsp;E'<subscript>R</subscript>
555+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
556+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
557 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
558 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
559 </row>
560 <row>
561 <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry>
562 <entry>7</entry>
563 <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry>
564 <entry>?</entry>
565 <entry>?</entry>
566 <entry>?</entry>
567 <entry>?</entry>
568 <entry>?</entry>
569 <entry>0.299&nbsp;E'<subscript>R</subscript>
570+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
571+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
572 <entry>256&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16<footnote>
573 <para>Note JFIF quantizes
574Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and
575[-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals
576are still clamped to [0;255].</para>
577 </footnote></entry>
578 <entry>256&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
579 </row>
580 <row>
581 <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry>
582 <entry>8</entry>
583 <entry>[?]</entry>
584 <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
585 <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
586 <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
587 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
588 Illuminant D<subscript>65</subscript></entry>
589 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
5901.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
591 <entry spanname="spam">n/a</entry>
592 </row>
593 </tbody>
594 </tgroup>
595 </table>
596 </section>
597
598 <section id="pixfmt-indexed">
599 <title>Indexed Format</title>
600
601 <para>In this format each pixel is represented by an 8 bit index
602into a 256 entry ARGB palette. It is intended for <link
603linkend="osd">Video Output Overlays</link> only. There are no ioctls to
604access the palette, this must be done with ioctls of the Linux framebuffer API.</para>
605
606 <table pgwide="0" frame="none">
607 <title>Indexed Image Format</title>
608 <tgroup cols="37" align="center">
609 <colspec colname="id" align="left" />
610 <colspec colname="fourcc" />
611 <colspec colname="bit" />
612
613 <colspec colnum="4" colname="b07" align="center" />
614 <colspec colnum="5" colname="b06" align="center" />
615 <colspec colnum="6" colname="b05" align="center" />
616 <colspec colnum="7" colname="b04" align="center" />
617 <colspec colnum="8" colname="b03" align="center" />
618 <colspec colnum="9" colname="b02" align="center" />
619 <colspec colnum="10" colname="b01" align="center" />
620 <colspec colnum="11" colname="b00" align="center" />
621
622 <spanspec namest="b07" nameend="b00" spanname="b0" />
623 <spanspec namest="b17" nameend="b10" spanname="b1" />
624 <spanspec namest="b27" nameend="b20" spanname="b2" />
625 <spanspec namest="b37" nameend="b30" spanname="b3" />
626 <thead>
627 <row>
628 <entry>Identifier</entry>
629 <entry>Code</entry>
630 <entry>&nbsp;</entry>
631 <entry spanname="b0">Byte&nbsp;0</entry>
632 </row>
633 <row>
634 <entry>&nbsp;</entry>
635 <entry>&nbsp;</entry>
636 <entry>Bit</entry>
637 <entry>7</entry>
638 <entry>6</entry>
639 <entry>5</entry>
640 <entry>4</entry>
641 <entry>3</entry>
642 <entry>2</entry>
643 <entry>1</entry>
644 <entry>0</entry>
645 </row>
646 </thead>
647 <tbody valign="top">
648 <row id="V4L2-PIX-FMT-PAL8">
649 <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry>
650 <entry>'PAL8'</entry>
651 <entry></entry>
652 <entry>i<subscript>7</subscript></entry>
653 <entry>i<subscript>6</subscript></entry>
654 <entry>i<subscript>5</subscript></entry>
655 <entry>i<subscript>4</subscript></entry>
656 <entry>i<subscript>3</subscript></entry>
657 <entry>i<subscript>2</subscript></entry>
658 <entry>i<subscript>1</subscript></entry>
659 <entry>i<subscript>0</subscript></entry>
660 </row>
661 </tbody>
662 </tgroup>
663 </table>
664 </section>
665
666 <section id="pixfmt-rgb">
667 <title>RGB Formats</title>
668
669 &sub-packed-rgb;
670 &sub-sbggr8;
671 &sub-sgbrg8;
672 &sub-sgrbg8;
673 &sub-srggb8;
674 &sub-sbggr16;
675 &sub-srggb10;
676 &sub-srggb12;
677 </section>
678
679 <section id="yuv-formats">
680 <title>YUV Formats</title>
681
682 <para>YUV is the format native to TV broadcast and composite video
683signals. It separates the brightness information (Y) from the color
684information (U and V or Cb and Cr). The color information consists of
685red and blue <emphasis>color difference</emphasis> signals, this way
686the green component can be reconstructed by subtracting from the
687brightness component. See <xref linkend="colorspaces" /> for conversion
688examples. YUV was chosen because early television would only transmit
689brightness information. To add color in a way compatible with existing
690receivers a new signal carrier was added to transmit the color
691difference signals. Secondary in the YUV format the U and V components
692usually have lower resolution than the Y component. This is an analog
693video compression technique taking advantage of a property of the
694human visual system, being more sensitive to brightness
695information.</para>
696
697 &sub-packed-yuv;
698 &sub-grey;
699 &sub-y10;
700 &sub-y12;
701 &sub-y10b;
702 &sub-y16;
703 &sub-yuyv;
704 &sub-uyvy;
705 &sub-yvyu;
706 &sub-vyuy;
707 &sub-y41p;
708 &sub-yuv420;
709 &sub-yuv420m;
710 &sub-yuv410;
711 &sub-yuv422p;
712 &sub-yuv411p;
713 &sub-nv12;
714 &sub-nv12m;
715 &sub-nv12mt;
716 &sub-nv16;
717 &sub-m420;
718 </section>
719
720 <section>
721 <title>Compressed Formats</title>
722
723 <table pgwide="1" frame="none" id="compressed-formats">
724 <title>Compressed Image Formats</title>
725 <tgroup cols="3" align="left">
726 &cs-def;
727 <thead>
728 <row>
729 <entry>Identifier</entry>
730 <entry>Code</entry>
731 <entry>Details</entry>
732 </row>
733 </thead>
734 <tbody valign="top">
735 <row id="V4L2-PIX-FMT-JPEG">
736 <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry>
737 <entry>'JPEG'</entry>
738 <entry>TBD. See also &VIDIOC-G-JPEGCOMP;,
739 &VIDIOC-S-JPEGCOMP;.</entry>
740 </row>
741 <row id="V4L2-PIX-FMT-MPEG">
742 <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry>
743 <entry>'MPEG'</entry>
744 <entry>MPEG stream. The actual format is determined by
745extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
746<xref linkend="mpeg-control-id" />.</entry>
747 </row>
748 </tbody>
749 </tgroup>
750 </table>
751 </section>
752
753 <section id="pixfmt-reserved">
754 <title>Reserved Format Identifiers</title>
755
756 <para>These formats are not defined by this specification, they
757are just listed for reference and to avoid naming conflicts. If you
758want to register your own format, send an e-mail to the linux-media mailing
759list &v4l-ml; for inclusion in the <filename>videodev2.h</filename>
760file. If you want to share your format with other developers add a
761link to your documentation and send a copy to the linux-media mailing list
762for inclusion in this section. If you think your format should be listed
763in a standard format section please make a proposal on the linux-media mailing
764list.</para>
765
766 <table pgwide="1" frame="none" id="reserved-formats">
767 <title>Reserved Image Formats</title>
768 <tgroup cols="3" align="left">
769 &cs-def;
770 <thead>
771 <row>
772 <entry>Identifier</entry>
773 <entry>Code</entry>
774 <entry>Details</entry>
775 </row>
776 </thead>
777 <tbody valign="top">
778 <row id="V4L2-PIX-FMT-DV">
779 <entry><constant>V4L2_PIX_FMT_DV</constant></entry>
780 <entry>'dvsd'</entry>
781 <entry>unknown</entry>
782 </row>
783 <row id="V4L2-PIX-FMT-ET61X251">
784 <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry>
785 <entry>'E625'</entry>
786 <entry>Compressed format of the ET61X251 driver.</entry>
787 </row>
788 <row id="V4L2-PIX-FMT-HI240">
789 <entry><constant>V4L2_PIX_FMT_HI240</constant></entry>
790 <entry>'HI24'</entry>
791 <entry><para>8 bit RGB format used by the BTTV driver.</para></entry>
792 </row>
793 <row id="V4L2-PIX-FMT-HM12">
794 <entry><constant>V4L2_PIX_FMT_HM12</constant></entry>
795 <entry>'HM12'</entry>
796 <entry><para>YUV 4:2:0 format used by the
797IVTV driver, <ulink url="http://www.ivtvdriver.org/">
798http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
799kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename>
800</para></entry>
801 </row>
802 <row id="V4L2-PIX-FMT-CPIA1">
803 <entry><constant>V4L2_PIX_FMT_CPIA1</constant></entry>
804 <entry>'CPIA'</entry>
805 <entry>YUV format used by the gspca cpia1 driver.</entry>
806 </row>
807 <row id="V4L2-PIX-FMT-SPCA501">
808 <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry>
809 <entry>'S501'</entry>
810 <entry>YUYV per line used by the gspca driver.</entry>
811 </row>
812 <row id="V4L2-PIX-FMT-SPCA505">
813 <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry>
814 <entry>'S505'</entry>
815 <entry>YYUV per line used by the gspca driver.</entry>
816 </row>
817 <row id="V4L2-PIX-FMT-SPCA508">
818 <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry>
819 <entry>'S508'</entry>
820 <entry>YUVY per line used by the gspca driver.</entry>
821 </row>
822 <row id="V4L2-PIX-FMT-SPCA561">
823 <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry>
824 <entry>'S561'</entry>
825 <entry>Compressed GBRG Bayer format used by the gspca driver.</entry>
826 </row>
827 <row id="V4L2-PIX-FMT-SGRBG10DPCM8">
828 <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry>
829 <entry>'DB10'</entry>
830 <entry>10 bit raw Bayer DPCM compressed to 8 bits.</entry>
831 </row>
832 <row id="V4L2-PIX-FMT-PAC207">
833 <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry>
834 <entry>'P207'</entry>
835 <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
836 </row>
837 <row id="V4L2-PIX-FMT-MR97310A">
838 <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry>
839 <entry>'M310'</entry>
840 <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
841 </row>
842 <row id="V4L2-PIX-FMT-OV511">
843 <entry><constant>V4L2_PIX_FMT_OV511</constant></entry>
844 <entry>'O511'</entry>
845 <entry>OV511 JPEG format used by the gspca driver.</entry>
846 </row>
847 <row id="V4L2-PIX-FMT-OV518">
848 <entry><constant>V4L2_PIX_FMT_OV518</constant></entry>
849 <entry>'O518'</entry>
850 <entry>OV518 JPEG format used by the gspca driver.</entry>
851 </row>
852 <row id="V4L2-PIX-FMT-PJPG">
853 <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry>
854 <entry>'PJPG'</entry>
855 <entry>Pixart 73xx JPEG format used by the gspca driver.</entry>
856 </row>
857 <row id="V4L2-PIX-FMT-SQ905C">
858 <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry>
859 <entry>'905C'</entry>
860 <entry>Compressed RGGB bayer format used by the gspca driver.</entry>
861 </row>
862 <row id="V4L2-PIX-FMT-MJPEG">
863 <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry>
864 <entry>'MJPG'</entry>
865 <entry>Compressed format used by the Zoran driver</entry>
866 </row>
867 <row id="V4L2-PIX-FMT-PWC1">
868 <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry>
869 <entry>'PWC1'</entry>
870 <entry>Compressed format of the PWC driver.</entry>
871 </row>
872 <row id="V4L2-PIX-FMT-PWC2">
873 <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry>
874 <entry>'PWC2'</entry>
875 <entry>Compressed format of the PWC driver.</entry>
876 </row>
877 <row id="V4L2-PIX-FMT-SN9C10X">
878 <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry>
879 <entry>'S910'</entry>
880 <entry>Compressed format of the SN9C102 driver.</entry>
881 </row>
882 <row id="V4L2-PIX-FMT-SN9C20X-I420">
883 <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry>
884 <entry>'S920'</entry>
885 <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
886 </row>
887 <row id="V4L2-PIX-FMT-SN9C2028">
888 <entry><constant>V4L2_PIX_FMT_SN9C2028</constant></entry>
889 <entry>'SONX'</entry>
890 <entry>Compressed GBRG bayer format of the gspca sn9c2028 driver.</entry>
891 </row>
892 <row id="V4L2-PIX-FMT-STV0680">
893 <entry><constant>V4L2_PIX_FMT_STV0680</constant></entry>
894 <entry>'S680'</entry>
895 <entry>Bayer format of the gspca stv0680 driver.</entry>
896 </row>
897 <row id="V4L2-PIX-FMT-WNVA">
898 <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry>
899 <entry>'WNVA'</entry>
900 <entry><para>Used by the Winnov Videum driver, <ulink
901url="http://www.thedirks.org/winnov/">
902http://www.thedirks.org/winnov/</ulink></para></entry>
903 </row>
904 <row id="V4L2-PIX-FMT-TM6000">
905 <entry><constant>V4L2_PIX_FMT_TM6000</constant></entry>
906 <entry>'TM60'</entry>
907 <entry><para>Used by Trident tm6000</para></entry>
908 </row>
909 <row id="V4L2-PIX-FMT-CIT-YYVYUY">
910 <entry><constant>V4L2_PIX_FMT_CIT_YYVYUY</constant></entry>
911 <entry>'CITV'</entry>
912 <entry><para>Used by xirlink CIT, found at IBM webcams.</para>
913 <para>Uses one line of Y then 1 line of VYUY</para>
914 </entry>
915 </row>
916 <row id="V4L2-PIX-FMT-KONICA420">
917 <entry><constant>V4L2_PIX_FMT_KONICA420</constant></entry>
918 <entry>'KONI'</entry>
919 <entry><para>Used by Konica webcams.</para>
920 <para>YUV420 planar in blocks of 256 pixels.</para>
921 </entry>
922 </row>
923 <row id="V4L2-PIX-FMT-YYUV">
924 <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry>
925 <entry>'YYUV'</entry>
926 <entry>unknown</entry>
927 </row>
928 <row id="V4L2-PIX-FMT-Y4">
929 <entry><constant>V4L2_PIX_FMT_Y4</constant></entry>
930 <entry>'Y04 '</entry>
931 <entry>Old 4-bit greyscale format. Only the least significant 4 bits of each byte are used,
932the other bits are set to 0.</entry>
933 </row>
934 <row id="V4L2-PIX-FMT-Y6">
935 <entry><constant>V4L2_PIX_FMT_Y6</constant></entry>
936 <entry>'Y06 '</entry>
937 <entry>Old 6-bit greyscale format. Only the least significant 6 bits of each byte are used,
938the other bits are set to 0.</entry>
939 </row>
940 </tbody>
941 </tgroup>
942 </table>
943 </section>
944
945 <!--
946Local Variables:
947mode: sgml
948sgml-parent-document: "v4l2.sgml"
949indent-tabs-mode: nil
950End:
951 -->
diff --git a/Documentation/DocBook/media/v4l/planar-apis.xml b/Documentation/DocBook/media/v4l/planar-apis.xml
new file mode 100644
index 000000000000..878ce2040488
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/remote_controllers.xml b/Documentation/DocBook/media/v4l/remote_controllers.xml
new file mode 100644
index 000000000000..160e464d44b7
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/remote_controllers.xml
@@ -0,0 +1,177 @@
1<title>Remote Controllers</title>
2<section id="Remote_controllers_Intro">
3<title>Introduction</title>
4
5<para>Currently, most analog and digital devices have a Infrared input for remote controllers. Each
6manufacturer has their own type of control. It is not rare for the same manufacturer to ship different
7types of controls, depending on the device.</para>
8<para>Unfortunately, for several years, there was no effort to create uniform IR keycodes for
9different devices. This caused the same IR keyname to be mapped completely differently on
10different IR devices. This resulted that the same IR keyname to be mapped completely different on
11different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para>
12<para>This standard should be used by both V4L/DVB drivers and userspace applications</para>
13<para>The modules register the remote as keyboard within the linux input layer. This means that the IR key strokes will look like normal keyboard key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event devices (CONFIG_INPUT_EVDEV) it is possible for applications to access the remote via /dev/input/event devices.</para>
14
15<table pgwide="1" frame="none" id="rc_standard_keymap">
16<title>IR default keymapping</title>
17<tgroup cols="3">
18&cs-str;
19<tbody valign="top">
20<row>
21<entry>Key code</entry>
22<entry>Meaning</entry>
23<entry>Key examples on IR</entry>
24</row>
25
26<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row>
27
28<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row>
29<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row>
30<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row>
31<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row>
32<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row>
33<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row>
34<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row>
35<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row>
36<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row>
37<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row>
38
39<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row>
40
41<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>&gt;&gt; / FORWARD</entry></row>
42<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry>&lt;&lt;&lt; / BACK</entry></row>
43<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>&gt;&gt;&gt; / FORWARD</entry></row>
44<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row>
45<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row>
46<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry>&lt;&lt; / PREV / PREVIOUS</entry></row>
47<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row>
48<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row>
49<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / &gt;</entry></row>
50<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row>
51<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row>
52<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row>
53<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row>
54<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row>
55<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row>
56<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row>
57<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row>
58
59<row><entry><emphasis role="bold">Image control</emphasis></entry></row>
60
61<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row>
62<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row>
63
64<row><entry><constant>KEY_ANGLE</constant></entry><entry>Switch video camera angle (on videos with more than one angle stored)</entry><entry>ANGLE / SWAP</entry></row>
65<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row>
66<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row>
67
68<row><entry><emphasis role="bold">Audio control</emphasis></entry></row>
69
70<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row>
71<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row>
72<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row>
73<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row>
74<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row>
75<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row>
76
77<row><entry><emphasis role="bold">Channel control</emphasis></entry></row>
78
79<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row>
80<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row>
81<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row>
82<row><entry><constant>KEY_DIGITS</constant></entry><entry>Use more than one digit for channel</entry><entry>PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit</entry></row>
83<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row>
84
85<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row>
86
87<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row>
88<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row>
89<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row>
90<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row>
91
92<row><entry><emphasis role="bold">Media selection</emphasis></entry></row>
93
94<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row>
95<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row>
96<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-&gt; ) / CLOSE / OPEN</entry></row>
97
98<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row>
99<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row>
100<row><entry><constant>KEY_RADIO</constant></entry><entry>Put into AM/FM radio mode</entry><entry>RADIO / TV/FM / TV/RADIO / FM / FM/RADIO</entry></row>
101<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row>
102<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row>
103<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row>
104<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row>
105
106<row><entry><emphasis role="bold">Power control</emphasis></entry></row>
107
108<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row>
109<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row>
110<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row>
111<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row>
112
113<row><entry><emphasis role="bold">Window control</emphasis></entry></row>
114
115<row><entry><constant>KEY_CLEAR</constant></entry><entry>Stop sroweam and return to default input video/audio</entry><entry>CLEAR / RESET / BOSS KEY</entry></row>
116<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row>
117<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row>
118<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row>
119<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row>
120<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row>
121<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row>
122<row><entry><constant>KEY_ZOOM</constant></entry><entry>Put device into zoom/full screen mode</entry><entry>ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH</entry></row>
123
124<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row>
125
126<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row>
127<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row>
128<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row>
129<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row>
130<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row>
131<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row>
132<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row>
133<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row>
134<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row>
135
136<row><entry><emphasis role="bold">Miscellaneous keys</emphasis></entry></row>
137
138<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row>
139<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row>
140
141</tbody>
142</tgroup>
143</table>
144
145<para>It should be noticed that, sometimes, there some fundamental missing keys at some cheaper IR's. Due to that, it is recommended to:</para>
146
147<table pgwide="1" frame="none" id="rc_keymap_notes">
148<title>Notes</title>
149<tgroup cols="1">
150&cs-str;
151<tbody valign="top">
152<row>
153<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry>
154</row><row>
155<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry>
156</row><row>
157<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry>
158</row><row>
159<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry>
160</row>
161</tbody>
162</tgroup>
163</table>
164
165</section>
166
167<section id="Remote_controllers_table_change">
168<title>Changing default Remote Controller mappings</title>
169<para>The event interface provides two ioctls to be used against
170the /dev/input/event device, to allow changing the default
171keymapping.</para>
172
173<para>This program demonstrates how to replace the keymap tables.</para>
174&sub-keytable-c;
175</section>
176
177&sub-lirc_device_interface;
diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml
new file mode 100644
index 000000000000..8d3409d2c632
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/subdev-formats.xml
@@ -0,0 +1,2572 @@
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-SGBRG8-1X8">
460 <entry>V4L2_MBUS_FMT_SGBRG8_1X8</entry>
461 <entry>0x3013</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-SGRBG8-1X8">
477 <entry>V4L2_MBUS_FMT_SGRBG8_1X8</entry>
478 <entry>0x3002</entry>
479 <entry></entry>
480 <entry>-</entry>
481 <entry>-</entry>
482 <entry>-</entry>
483 <entry>-</entry>
484 <entry>g<subscript>7</subscript></entry>
485 <entry>g<subscript>6</subscript></entry>
486 <entry>g<subscript>5</subscript></entry>
487 <entry>g<subscript>4</subscript></entry>
488 <entry>g<subscript>3</subscript></entry>
489 <entry>g<subscript>2</subscript></entry>
490 <entry>g<subscript>1</subscript></entry>
491 <entry>g<subscript>0</subscript></entry>
492 </row>
493 <row id="V4L2-MBUS-FMT-SRGGB8-1X8">
494 <entry>V4L2_MBUS_FMT_SRGGB8_1X8</entry>
495 <entry>0x3014</entry>
496 <entry></entry>
497 <entry>-</entry>
498 <entry>-</entry>
499 <entry>-</entry>
500 <entry>-</entry>
501 <entry>r<subscript>7</subscript></entry>
502 <entry>r<subscript>6</subscript></entry>
503 <entry>r<subscript>5</subscript></entry>
504 <entry>r<subscript>4</subscript></entry>
505 <entry>r<subscript>3</subscript></entry>
506 <entry>r<subscript>2</subscript></entry>
507 <entry>r<subscript>1</subscript></entry>
508 <entry>r<subscript>0</subscript></entry>
509 </row>
510 <row id="V4L2-MBUS-FMT-SBGGR10-DPCM8-1X8">
511 <entry>V4L2_MBUS_FMT_SBGGR10_DPCM8_1X8</entry>
512 <entry>0x300b</entry>
513 <entry></entry>
514 <entry>-</entry>
515 <entry>-</entry>
516 <entry>-</entry>
517 <entry>-</entry>
518 <entry>b<subscript>7</subscript></entry>
519 <entry>b<subscript>6</subscript></entry>
520 <entry>b<subscript>5</subscript></entry>
521 <entry>b<subscript>4</subscript></entry>
522 <entry>b<subscript>3</subscript></entry>
523 <entry>b<subscript>2</subscript></entry>
524 <entry>b<subscript>1</subscript></entry>
525 <entry>b<subscript>0</subscript></entry>
526 </row>
527 <row id="V4L2-MBUS-FMT-SGBRG10-DPCM8-1X8">
528 <entry>V4L2_MBUS_FMT_SGBRG10_DPCM8_1X8</entry>
529 <entry>0x300c</entry>
530 <entry></entry>
531 <entry>-</entry>
532 <entry>-</entry>
533 <entry>-</entry>
534 <entry>-</entry>
535 <entry>g<subscript>7</subscript></entry>
536 <entry>g<subscript>6</subscript></entry>
537 <entry>g<subscript>5</subscript></entry>
538 <entry>g<subscript>4</subscript></entry>
539 <entry>g<subscript>3</subscript></entry>
540 <entry>g<subscript>2</subscript></entry>
541 <entry>g<subscript>1</subscript></entry>
542 <entry>g<subscript>0</subscript></entry>
543 </row>
544 <row id="V4L2-MBUS-FMT-SGRBG10-DPCM8-1X8">
545 <entry>V4L2_MBUS_FMT_SGRBG10_DPCM8_1X8</entry>
546 <entry>0x3009</entry>
547 <entry></entry>
548 <entry>-</entry>
549 <entry>-</entry>
550 <entry>-</entry>
551 <entry>-</entry>
552 <entry>g<subscript>7</subscript></entry>
553 <entry>g<subscript>6</subscript></entry>
554 <entry>g<subscript>5</subscript></entry>
555 <entry>g<subscript>4</subscript></entry>
556 <entry>g<subscript>3</subscript></entry>
557 <entry>g<subscript>2</subscript></entry>
558 <entry>g<subscript>1</subscript></entry>
559 <entry>g<subscript>0</subscript></entry>
560 </row>
561 <row id="V4L2-MBUS-FMT-SRGGB10-DPCM8-1X8">
562 <entry>V4L2_MBUS_FMT_SRGGB10_DPCM8_1X8</entry>
563 <entry>0x300d</entry>
564 <entry></entry>
565 <entry>-</entry>
566 <entry>-</entry>
567 <entry>-</entry>
568 <entry>-</entry>
569 <entry>r<subscript>7</subscript></entry>
570 <entry>r<subscript>6</subscript></entry>
571 <entry>r<subscript>5</subscript></entry>
572 <entry>r<subscript>4</subscript></entry>
573 <entry>r<subscript>3</subscript></entry>
574 <entry>r<subscript>2</subscript></entry>
575 <entry>r<subscript>1</subscript></entry>
576 <entry>r<subscript>0</subscript></entry>
577 </row>
578 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-BE">
579 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_BE</entry>
580 <entry>0x3003</entry>
581 <entry></entry>
582 <entry>-</entry>
583 <entry>-</entry>
584 <entry>-</entry>
585 <entry>-</entry>
586 <entry>0</entry>
587 <entry>0</entry>
588 <entry>0</entry>
589 <entry>0</entry>
590 <entry>0</entry>
591 <entry>0</entry>
592 <entry>b<subscript>9</subscript></entry>
593 <entry>b<subscript>8</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>b<subscript>7</subscript></entry>
604 <entry>b<subscript>6</subscript></entry>
605 <entry>b<subscript>5</subscript></entry>
606 <entry>b<subscript>4</subscript></entry>
607 <entry>b<subscript>3</subscript></entry>
608 <entry>b<subscript>2</subscript></entry>
609 <entry>b<subscript>1</subscript></entry>
610 <entry>b<subscript>0</subscript></entry>
611 </row>
612 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-LE">
613 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_LE</entry>
614 <entry>0x3004</entry>
615 <entry></entry>
616 <entry>-</entry>
617 <entry>-</entry>
618 <entry>-</entry>
619 <entry>-</entry>
620 <entry>b<subscript>7</subscript></entry>
621 <entry>b<subscript>6</subscript></entry>
622 <entry>b<subscript>5</subscript></entry>
623 <entry>b<subscript>4</subscript></entry>
624 <entry>b<subscript>3</subscript></entry>
625 <entry>b<subscript>2</subscript></entry>
626 <entry>b<subscript>1</subscript></entry>
627 <entry>b<subscript>0</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>0</entry>
638 <entry>0</entry>
639 <entry>0</entry>
640 <entry>0</entry>
641 <entry>0</entry>
642 <entry>0</entry>
643 <entry>b<subscript>9</subscript></entry>
644 <entry>b<subscript>8</subscript></entry>
645 </row>
646 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-BE">
647 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_BE</entry>
648 <entry>0x3005</entry>
649 <entry></entry>
650 <entry>-</entry>
651 <entry>-</entry>
652 <entry>-</entry>
653 <entry>-</entry>
654 <entry>b<subscript>9</subscript></entry>
655 <entry>b<subscript>8</subscript></entry>
656 <entry>b<subscript>7</subscript></entry>
657 <entry>b<subscript>6</subscript></entry>
658 <entry>b<subscript>5</subscript></entry>
659 <entry>b<subscript>4</subscript></entry>
660 <entry>b<subscript>3</subscript></entry>
661 <entry>b<subscript>2</subscript></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>1</subscript></entry>
672 <entry>b<subscript>0</subscript></entry>
673 <entry>0</entry>
674 <entry>0</entry>
675 <entry>0</entry>
676 <entry>0</entry>
677 <entry>0</entry>
678 <entry>0</entry>
679 </row>
680 <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-LE">
681 <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_LE</entry>
682 <entry>0x3006</entry>
683 <entry></entry>
684 <entry>-</entry>
685 <entry>-</entry>
686 <entry>-</entry>
687 <entry>-</entry>
688 <entry>b<subscript>1</subscript></entry>
689 <entry>b<subscript>0</subscript></entry>
690 <entry>0</entry>
691 <entry>0</entry>
692 <entry>0</entry>
693 <entry>0</entry>
694 <entry>0</entry>
695 <entry>0</entry>
696 </row>
697 <row>
698 <entry></entry>
699 <entry></entry>
700 <entry></entry>
701 <entry>-</entry>
702 <entry>-</entry>
703 <entry>-</entry>
704 <entry>-</entry>
705 <entry>b<subscript>9</subscript></entry>
706 <entry>b<subscript>8</subscript></entry>
707 <entry>b<subscript>7</subscript></entry>
708 <entry>b<subscript>6</subscript></entry>
709 <entry>b<subscript>5</subscript></entry>
710 <entry>b<subscript>4</subscript></entry>
711 <entry>b<subscript>3</subscript></entry>
712 <entry>b<subscript>2</subscript></entry>
713 </row>
714 <row id="V4L2-MBUS-FMT-SBGGR10-1X10">
715 <entry>V4L2_MBUS_FMT_SBGGR10_1X10</entry>
716 <entry>0x3007</entry>
717 <entry></entry>
718 <entry>-</entry>
719 <entry>-</entry>
720 <entry>b<subscript>9</subscript></entry>
721 <entry>b<subscript>8</subscript></entry>
722 <entry>b<subscript>7</subscript></entry>
723 <entry>b<subscript>6</subscript></entry>
724 <entry>b<subscript>5</subscript></entry>
725 <entry>b<subscript>4</subscript></entry>
726 <entry>b<subscript>3</subscript></entry>
727 <entry>b<subscript>2</subscript></entry>
728 <entry>b<subscript>1</subscript></entry>
729 <entry>b<subscript>0</subscript></entry>
730 </row>
731 <row id="V4L2-MBUS-FMT-SGBRG10-1X10">
732 <entry>V4L2_MBUS_FMT_SGBRG10_1X10</entry>
733 <entry>0x300e</entry>
734 <entry></entry>
735 <entry>-</entry>
736 <entry>-</entry>
737 <entry>g<subscript>9</subscript></entry>
738 <entry>g<subscript>8</subscript></entry>
739 <entry>g<subscript>7</subscript></entry>
740 <entry>g<subscript>6</subscript></entry>
741 <entry>g<subscript>5</subscript></entry>
742 <entry>g<subscript>4</subscript></entry>
743 <entry>g<subscript>3</subscript></entry>
744 <entry>g<subscript>2</subscript></entry>
745 <entry>g<subscript>1</subscript></entry>
746 <entry>g<subscript>0</subscript></entry>
747 </row>
748 <row id="V4L2-MBUS-FMT-SGRBG10-1X10">
749 <entry>V4L2_MBUS_FMT_SGRBG10_1X10</entry>
750 <entry>0x300a</entry>
751 <entry></entry>
752 <entry>-</entry>
753 <entry>-</entry>
754 <entry>g<subscript>9</subscript></entry>
755 <entry>g<subscript>8</subscript></entry>
756 <entry>g<subscript>7</subscript></entry>
757 <entry>g<subscript>6</subscript></entry>
758 <entry>g<subscript>5</subscript></entry>
759 <entry>g<subscript>4</subscript></entry>
760 <entry>g<subscript>3</subscript></entry>
761 <entry>g<subscript>2</subscript></entry>
762 <entry>g<subscript>1</subscript></entry>
763 <entry>g<subscript>0</subscript></entry>
764 </row>
765 <row id="V4L2-MBUS-FMT-SRGGB10-1X10">
766 <entry>V4L2_MBUS_FMT_SRGGB10_1X10</entry>
767 <entry>0x300f</entry>
768 <entry></entry>
769 <entry>-</entry>
770 <entry>-</entry>
771 <entry>r<subscript>9</subscript></entry>
772 <entry>r<subscript>8</subscript></entry>
773 <entry>r<subscript>7</subscript></entry>
774 <entry>r<subscript>6</subscript></entry>
775 <entry>r<subscript>5</subscript></entry>
776 <entry>r<subscript>4</subscript></entry>
777 <entry>r<subscript>3</subscript></entry>
778 <entry>r<subscript>2</subscript></entry>
779 <entry>r<subscript>1</subscript></entry>
780 <entry>r<subscript>0</subscript></entry>
781 </row>
782 <row id="V4L2-MBUS-FMT-SBGGR12-1X12">
783 <entry>V4L2_MBUS_FMT_SBGGR12_1X12</entry>
784 <entry>0x3008</entry>
785 <entry></entry>
786 <entry>b<subscript>11</subscript></entry>
787 <entry>b<subscript>10</subscript></entry>
788 <entry>b<subscript>9</subscript></entry>
789 <entry>b<subscript>8</subscript></entry>
790 <entry>b<subscript>7</subscript></entry>
791 <entry>b<subscript>6</subscript></entry>
792 <entry>b<subscript>5</subscript></entry>
793 <entry>b<subscript>4</subscript></entry>
794 <entry>b<subscript>3</subscript></entry>
795 <entry>b<subscript>2</subscript></entry>
796 <entry>b<subscript>1</subscript></entry>
797 <entry>b<subscript>0</subscript></entry>
798 </row>
799 <row id="V4L2-MBUS-FMT-SGBRG12-1X12">
800 <entry>V4L2_MBUS_FMT_SGBRG12_1X12</entry>
801 <entry>0x3010</entry>
802 <entry></entry>
803 <entry>g<subscript>11</subscript></entry>
804 <entry>g<subscript>10</subscript></entry>
805 <entry>g<subscript>9</subscript></entry>
806 <entry>g<subscript>8</subscript></entry>
807 <entry>g<subscript>7</subscript></entry>
808 <entry>g<subscript>6</subscript></entry>
809 <entry>g<subscript>5</subscript></entry>
810 <entry>g<subscript>4</subscript></entry>
811 <entry>g<subscript>3</subscript></entry>
812 <entry>g<subscript>2</subscript></entry>
813 <entry>g<subscript>1</subscript></entry>
814 <entry>g<subscript>0</subscript></entry>
815 </row>
816 <row id="V4L2-MBUS-FMT-SGRBG12-1X12">
817 <entry>V4L2_MBUS_FMT_SGRBG12_1X12</entry>
818 <entry>0x3011</entry>
819 <entry></entry>
820 <entry>g<subscript>11</subscript></entry>
821 <entry>g<subscript>10</subscript></entry>
822 <entry>g<subscript>9</subscript></entry>
823 <entry>g<subscript>8</subscript></entry>
824 <entry>g<subscript>7</subscript></entry>
825 <entry>g<subscript>6</subscript></entry>
826 <entry>g<subscript>5</subscript></entry>
827 <entry>g<subscript>4</subscript></entry>
828 <entry>g<subscript>3</subscript></entry>
829 <entry>g<subscript>2</subscript></entry>
830 <entry>g<subscript>1</subscript></entry>
831 <entry>g<subscript>0</subscript></entry>
832 </row>
833 <row id="V4L2-MBUS-FMT-SRGGB12-1X12">
834 <entry>V4L2_MBUS_FMT_SRGGB12_1X12</entry>
835 <entry>0x3012</entry>
836 <entry></entry>
837 <entry>r<subscript>11</subscript></entry>
838 <entry>r<subscript>10</subscript></entry>
839 <entry>r<subscript>9</subscript></entry>
840 <entry>r<subscript>8</subscript></entry>
841 <entry>r<subscript>7</subscript></entry>
842 <entry>r<subscript>6</subscript></entry>
843 <entry>r<subscript>5</subscript></entry>
844 <entry>r<subscript>4</subscript></entry>
845 <entry>r<subscript>3</subscript></entry>
846 <entry>r<subscript>2</subscript></entry>
847 <entry>r<subscript>1</subscript></entry>
848 <entry>r<subscript>0</subscript></entry>
849 </row>
850 </tbody>
851 </tgroup>
852 </table>
853 </section>
854
855 <section>
856 <title>Packed YUV Formats</title>
857
858 <para>Those data formats transfer pixel data as (possibly downsampled) Y, U
859 and V components. The format code is made of the following information.
860 <itemizedlist>
861 <listitem><para>The Y, U and V components order code, as transferred on the
862 bus. Possible values are YUYV, UYVY, YVYU and VYUY.</para></listitem>
863 <listitem><para>The number of bits per pixel component. All components are
864 transferred on the same number of bits. Common values are 8, 10 and 12.</para>
865 </listitem>
866 <listitem><para>The number of bus samples per pixel. Pixels that are wider than
867 the bus width must be transferred in multiple samples. Common values are
868 1, 1.5 (encoded as 1_5) and 2.</para></listitem>
869 <listitem><para>The bus width. When the bus width is larger than the number of
870 bits per pixel component, several components are packed in a single bus
871 sample. The components are ordered as specified by the order code, with
872 components on the left of the code transferred in the high order bits.
873 Common values are 8 and 16.</para>
874 </listitem>
875 </itemizedlist>
876 </para>
877
878 <para>For instance, a format where pixels are encoded as 8-bit YUV values
879 downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the
880 U, Y, V, Y order will be named <constant>V4L2_MBUS_FMT_UYVY8_2X8</constant>.
881 </para>
882
883 <para>The following table lisst existing packet YUV formats.</para>
884
885 <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-yuv8">
886 <title>YUV Formats</title>
887 <tgroup cols="23">
888 <colspec colname="id" align="left" />
889 <colspec colname="code" align="center"/>
890 <colspec colname="bit" />
891 <colspec colnum="4" colname="b19" align="center" />
892 <colspec colnum="5" colname="b18" align="center" />
893 <colspec colnum="6" colname="b17" align="center" />
894 <colspec colnum="7" colname="b16" align="center" />
895 <colspec colnum="8" colname="b15" align="center" />
896 <colspec colnum="9" colname="b14" align="center" />
897 <colspec colnum="10" colname="b13" align="center" />
898 <colspec colnum="11" colname="b12" align="center" />
899 <colspec colnum="12" colname="b11" align="center" />
900 <colspec colnum="13" colname="b10" align="center" />
901 <colspec colnum="14" colname="b09" align="center" />
902 <colspec colnum="15" colname="b08" align="center" />
903 <colspec colnum="16" colname="b07" align="center" />
904 <colspec colnum="17" colname="b06" align="center" />
905 <colspec colnum="18" colname="b05" align="center" />
906 <colspec colnum="19" colname="b04" align="center" />
907 <colspec colnum="20" colname="b03" align="center" />
908 <colspec colnum="21" colname="b02" align="center" />
909 <colspec colnum="22" colname="b01" align="center" />
910 <colspec colnum="23" colname="b00" align="center" />
911 <spanspec namest="b19" nameend="b00" spanname="b0" />
912 <thead>
913 <row>
914 <entry>Identifier</entry>
915 <entry>Code</entry>
916 <entry></entry>
917 <entry spanname="b0">Data organization</entry>
918 </row>
919 <row>
920 <entry></entry>
921 <entry></entry>
922 <entry>Bit</entry>
923 <entry>19</entry>
924 <entry>18</entry>
925 <entry>17</entry>
926 <entry>16</entry>
927 <entry>15</entry>
928 <entry>14</entry>
929 <entry>13</entry>
930 <entry>12</entry>
931 <entry>11</entry>
932 <entry>10</entry>
933 <entry>9</entry>
934 <entry>8</entry>
935 <entry>7</entry>
936 <entry>6</entry>
937 <entry>5</entry>
938 <entry>4</entry>
939 <entry>3</entry>
940 <entry>2</entry>
941 <entry>1</entry>
942 <entry>0</entry>
943 </row>
944 </thead>
945 <tbody valign="top">
946 <row id="V4L2-MBUS-FMT-Y8-1X8">
947 <entry>V4L2_MBUS_FMT_Y8_1X8</entry>
948 <entry>0x2001</entry>
949 <entry></entry>
950 <entry>-</entry>
951 <entry>-</entry>
952 <entry>-</entry>
953 <entry>-</entry>
954 <entry>-</entry>
955 <entry>-</entry>
956 <entry>-</entry>
957 <entry>-</entry>
958 <entry>-</entry>
959 <entry>-</entry>
960 <entry>-</entry>
961 <entry>-</entry>
962 <entry>y<subscript>7</subscript></entry>
963 <entry>y<subscript>6</subscript></entry>
964 <entry>y<subscript>5</subscript></entry>
965 <entry>y<subscript>4</subscript></entry>
966 <entry>y<subscript>3</subscript></entry>
967 <entry>y<subscript>2</subscript></entry>
968 <entry>y<subscript>1</subscript></entry>
969 <entry>y<subscript>0</subscript></entry>
970 </row>
971 <row id="V4L2-MBUS-FMT-UYVY8-1_5X8">
972 <entry>V4L2_MBUS_FMT_UYVY8_1_5X8</entry>
973 <entry>0x2002</entry>
974 <entry></entry>
975 <entry>-</entry>
976 <entry>-</entry>
977 <entry>-</entry>
978 <entry>-</entry>
979 <entry>-</entry>
980 <entry>-</entry>
981 <entry>-</entry>
982 <entry>-</entry>
983 <entry>-</entry>
984 <entry>-</entry>
985 <entry>-</entry>
986 <entry>-</entry>
987 <entry>u<subscript>7</subscript></entry>
988 <entry>u<subscript>6</subscript></entry>
989 <entry>u<subscript>5</subscript></entry>
990 <entry>u<subscript>4</subscript></entry>
991 <entry>u<subscript>3</subscript></entry>
992 <entry>u<subscript>2</subscript></entry>
993 <entry>u<subscript>1</subscript></entry>
994 <entry>u<subscript>0</subscript></entry>
995 </row>
996 <row>
997 <entry></entry>
998 <entry></entry>
999 <entry></entry>
1000 <entry>-</entry>
1001 <entry>-</entry>
1002 <entry>-</entry>
1003 <entry>-</entry>
1004 <entry>-</entry>
1005 <entry>-</entry>
1006 <entry>-</entry>
1007 <entry>-</entry>
1008 <entry>-</entry>
1009 <entry>-</entry>
1010 <entry>-</entry>
1011 <entry>-</entry>
1012 <entry>y<subscript>7</subscript></entry>
1013 <entry>y<subscript>6</subscript></entry>
1014 <entry>y<subscript>5</subscript></entry>
1015 <entry>y<subscript>4</subscript></entry>
1016 <entry>y<subscript>3</subscript></entry>
1017 <entry>y<subscript>2</subscript></entry>
1018 <entry>y<subscript>1</subscript></entry>
1019 <entry>y<subscript>0</subscript></entry>
1020 </row>
1021 <row>
1022 <entry></entry>
1023 <entry></entry>
1024 <entry></entry>
1025 <entry>-</entry>
1026 <entry>-</entry>
1027 <entry>-</entry>
1028 <entry>-</entry>
1029 <entry>-</entry>
1030 <entry>-</entry>
1031 <entry>-</entry>
1032 <entry>-</entry>
1033 <entry>-</entry>
1034 <entry>-</entry>
1035 <entry>-</entry>
1036 <entry>-</entry>
1037 <entry>y<subscript>7</subscript></entry>
1038 <entry>y<subscript>6</subscript></entry>
1039 <entry>y<subscript>5</subscript></entry>
1040 <entry>y<subscript>4</subscript></entry>
1041 <entry>y<subscript>3</subscript></entry>
1042 <entry>y<subscript>2</subscript></entry>
1043 <entry>y<subscript>1</subscript></entry>
1044 <entry>y<subscript>0</subscript></entry>
1045 </row>
1046 <row>
1047 <entry></entry>
1048 <entry></entry>
1049 <entry></entry>
1050 <entry>-</entry>
1051 <entry>-</entry>
1052 <entry>-</entry>
1053 <entry>-</entry>
1054 <entry>-</entry>
1055 <entry>-</entry>
1056 <entry>-</entry>
1057 <entry>-</entry>
1058 <entry>-</entry>
1059 <entry>-</entry>
1060 <entry>-</entry>
1061 <entry>-</entry>
1062 <entry>v<subscript>7</subscript></entry>
1063 <entry>v<subscript>6</subscript></entry>
1064 <entry>v<subscript>5</subscript></entry>
1065 <entry>v<subscript>4</subscript></entry>
1066 <entry>v<subscript>3</subscript></entry>
1067 <entry>v<subscript>2</subscript></entry>
1068 <entry>v<subscript>1</subscript></entry>
1069 <entry>v<subscript>0</subscript></entry>
1070 </row>
1071 <row>
1072 <entry></entry>
1073 <entry></entry>
1074 <entry></entry>
1075 <entry>-</entry>
1076 <entry>-</entry>
1077 <entry>-</entry>
1078 <entry>-</entry>
1079 <entry>-</entry>
1080 <entry>-</entry>
1081 <entry>-</entry>
1082 <entry>-</entry>
1083 <entry>-</entry>
1084 <entry>-</entry>
1085 <entry>-</entry>
1086 <entry>-</entry>
1087 <entry>y<subscript>7</subscript></entry>
1088 <entry>y<subscript>6</subscript></entry>
1089 <entry>y<subscript>5</subscript></entry>
1090 <entry>y<subscript>4</subscript></entry>
1091 <entry>y<subscript>3</subscript></entry>
1092 <entry>y<subscript>2</subscript></entry>
1093 <entry>y<subscript>1</subscript></entry>
1094 <entry>y<subscript>0</subscript></entry>
1095 </row>
1096 <row>
1097 <entry></entry>
1098 <entry></entry>
1099 <entry></entry>
1100 <entry>-</entry>
1101 <entry>-</entry>
1102 <entry>-</entry>
1103 <entry>-</entry>
1104 <entry>-</entry>
1105 <entry>-</entry>
1106 <entry>-</entry>
1107 <entry>-</entry>
1108 <entry>-</entry>
1109 <entry>-</entry>
1110 <entry>-</entry>
1111 <entry>-</entry>
1112 <entry>y<subscript>7</subscript></entry>
1113 <entry>y<subscript>6</subscript></entry>
1114 <entry>y<subscript>5</subscript></entry>
1115 <entry>y<subscript>4</subscript></entry>
1116 <entry>y<subscript>3</subscript></entry>
1117 <entry>y<subscript>2</subscript></entry>
1118 <entry>y<subscript>1</subscript></entry>
1119 <entry>y<subscript>0</subscript></entry>
1120 </row>
1121 <row id="V4L2-MBUS-FMT-VYUY8-1_5X8">
1122 <entry>V4L2_MBUS_FMT_VYUY8_1_5X8</entry>
1123 <entry>0x2003</entry>
1124 <entry></entry>
1125 <entry>-</entry>
1126 <entry>-</entry>
1127 <entry>-</entry>
1128 <entry>-</entry>
1129 <entry>-</entry>
1130 <entry>-</entry>
1131 <entry>-</entry>
1132 <entry>-</entry>
1133 <entry>-</entry>
1134 <entry>-</entry>
1135 <entry>-</entry>
1136 <entry>-</entry>
1137 <entry>v<subscript>7</subscript></entry>
1138 <entry>v<subscript>6</subscript></entry>
1139 <entry>v<subscript>5</subscript></entry>
1140 <entry>v<subscript>4</subscript></entry>
1141 <entry>v<subscript>3</subscript></entry>
1142 <entry>v<subscript>2</subscript></entry>
1143 <entry>v<subscript>1</subscript></entry>
1144 <entry>v<subscript>0</subscript></entry>
1145 </row>
1146 <row>
1147 <entry></entry>
1148 <entry></entry>
1149 <entry></entry>
1150 <entry>-</entry>
1151 <entry>-</entry>
1152 <entry>-</entry>
1153 <entry>-</entry>
1154 <entry>-</entry>
1155 <entry>-</entry>
1156 <entry>-</entry>
1157 <entry>-</entry>
1158 <entry>-</entry>
1159 <entry>-</entry>
1160 <entry>-</entry>
1161 <entry>-</entry>
1162 <entry>y<subscript>7</subscript></entry>
1163 <entry>y<subscript>6</subscript></entry>
1164 <entry>y<subscript>5</subscript></entry>
1165 <entry>y<subscript>4</subscript></entry>
1166 <entry>y<subscript>3</subscript></entry>
1167 <entry>y<subscript>2</subscript></entry>
1168 <entry>y<subscript>1</subscript></entry>
1169 <entry>y<subscript>0</subscript></entry>
1170 </row>
1171 <row>
1172 <entry></entry>
1173 <entry></entry>
1174 <entry></entry>
1175 <entry>-</entry>
1176 <entry>-</entry>
1177 <entry>-</entry>
1178 <entry>-</entry>
1179 <entry>-</entry>
1180 <entry>-</entry>
1181 <entry>-</entry>
1182 <entry>-</entry>
1183 <entry>-</entry>
1184 <entry>-</entry>
1185 <entry>-</entry>
1186 <entry>-</entry>
1187 <entry>y<subscript>7</subscript></entry>
1188 <entry>y<subscript>6</subscript></entry>
1189 <entry>y<subscript>5</subscript></entry>
1190 <entry>y<subscript>4</subscript></entry>
1191 <entry>y<subscript>3</subscript></entry>
1192 <entry>y<subscript>2</subscript></entry>
1193 <entry>y<subscript>1</subscript></entry>
1194 <entry>y<subscript>0</subscript></entry>
1195 </row>
1196 <row>
1197 <entry></entry>
1198 <entry></entry>
1199 <entry></entry>
1200 <entry>-</entry>
1201 <entry>-</entry>
1202 <entry>-</entry>
1203 <entry>-</entry>
1204 <entry>-</entry>
1205 <entry>-</entry>
1206 <entry>-</entry>
1207 <entry>-</entry>
1208 <entry>-</entry>
1209 <entry>-</entry>
1210 <entry>-</entry>
1211 <entry>-</entry>
1212 <entry>u<subscript>7</subscript></entry>
1213 <entry>u<subscript>6</subscript></entry>
1214 <entry>u<subscript>5</subscript></entry>
1215 <entry>u<subscript>4</subscript></entry>
1216 <entry>u<subscript>3</subscript></entry>
1217 <entry>u<subscript>2</subscript></entry>
1218 <entry>u<subscript>1</subscript></entry>
1219 <entry>u<subscript>0</subscript></entry>
1220 </row>
1221 <row>
1222 <entry></entry>
1223 <entry></entry>
1224 <entry></entry>
1225 <entry>-</entry>
1226 <entry>-</entry>
1227 <entry>-</entry>
1228 <entry>-</entry>
1229 <entry>-</entry>
1230 <entry>-</entry>
1231 <entry>-</entry>
1232 <entry>-</entry>
1233 <entry>-</entry>
1234 <entry>-</entry>
1235 <entry>-</entry>
1236 <entry>-</entry>
1237 <entry>y<subscript>7</subscript></entry>
1238 <entry>y<subscript>6</subscript></entry>
1239 <entry>y<subscript>5</subscript></entry>
1240 <entry>y<subscript>4</subscript></entry>
1241 <entry>y<subscript>3</subscript></entry>
1242 <entry>y<subscript>2</subscript></entry>
1243 <entry>y<subscript>1</subscript></entry>
1244 <entry>y<subscript>0</subscript></entry>
1245 </row>
1246 <row>
1247 <entry></entry>
1248 <entry></entry>
1249 <entry></entry>
1250 <entry>-</entry>
1251 <entry>-</entry>
1252 <entry>-</entry>
1253 <entry>-</entry>
1254 <entry>-</entry>
1255 <entry>-</entry>
1256 <entry>-</entry>
1257 <entry>-</entry>
1258 <entry>-</entry>
1259 <entry>-</entry>
1260 <entry>-</entry>
1261 <entry>-</entry>
1262 <entry>y<subscript>7</subscript></entry>
1263 <entry>y<subscript>6</subscript></entry>
1264 <entry>y<subscript>5</subscript></entry>
1265 <entry>y<subscript>4</subscript></entry>
1266 <entry>y<subscript>3</subscript></entry>
1267 <entry>y<subscript>2</subscript></entry>
1268 <entry>y<subscript>1</subscript></entry>
1269 <entry>y<subscript>0</subscript></entry>
1270 </row>
1271 <row id="V4L2-MBUS-FMT-YUYV8-1_5X8">
1272 <entry>V4L2_MBUS_FMT_YUYV8_1_5X8</entry>
1273 <entry>0x2004</entry>
1274 <entry></entry>
1275 <entry>-</entry>
1276 <entry>-</entry>
1277 <entry>-</entry>
1278 <entry>-</entry>
1279 <entry>-</entry>
1280 <entry>-</entry>
1281 <entry>-</entry>
1282 <entry>-</entry>
1283 <entry>-</entry>
1284 <entry>-</entry>
1285 <entry>-</entry>
1286 <entry>-</entry>
1287 <entry>y<subscript>7</subscript></entry>
1288 <entry>y<subscript>6</subscript></entry>
1289 <entry>y<subscript>5</subscript></entry>
1290 <entry>y<subscript>4</subscript></entry>
1291 <entry>y<subscript>3</subscript></entry>
1292 <entry>y<subscript>2</subscript></entry>
1293 <entry>y<subscript>1</subscript></entry>
1294 <entry>y<subscript>0</subscript></entry>
1295 </row>
1296 <row>
1297 <entry></entry>
1298 <entry></entry>
1299 <entry></entry>
1300 <entry>-</entry>
1301 <entry>-</entry>
1302 <entry>-</entry>
1303 <entry>-</entry>
1304 <entry>-</entry>
1305 <entry>-</entry>
1306 <entry>-</entry>
1307 <entry>-</entry>
1308 <entry>-</entry>
1309 <entry>-</entry>
1310 <entry>-</entry>
1311 <entry>-</entry>
1312 <entry>y<subscript>7</subscript></entry>
1313 <entry>y<subscript>6</subscript></entry>
1314 <entry>y<subscript>5</subscript></entry>
1315 <entry>y<subscript>4</subscript></entry>
1316 <entry>y<subscript>3</subscript></entry>
1317 <entry>y<subscript>2</subscript></entry>
1318 <entry>y<subscript>1</subscript></entry>
1319 <entry>y<subscript>0</subscript></entry>
1320 </row>
1321 <row>
1322 <entry></entry>
1323 <entry></entry>
1324 <entry></entry>
1325 <entry>-</entry>
1326 <entry>-</entry>
1327 <entry>-</entry>
1328 <entry>-</entry>
1329 <entry>-</entry>
1330 <entry>-</entry>
1331 <entry>-</entry>
1332 <entry>-</entry>
1333 <entry>-</entry>
1334 <entry>-</entry>
1335 <entry>-</entry>
1336 <entry>-</entry>
1337 <entry>u<subscript>7</subscript></entry>
1338 <entry>u<subscript>6</subscript></entry>
1339 <entry>u<subscript>5</subscript></entry>
1340 <entry>u<subscript>4</subscript></entry>
1341 <entry>u<subscript>3</subscript></entry>
1342 <entry>u<subscript>2</subscript></entry>
1343 <entry>u<subscript>1</subscript></entry>
1344 <entry>u<subscript>0</subscript></entry>
1345 </row>
1346 <row>
1347 <entry></entry>
1348 <entry></entry>
1349 <entry></entry>
1350 <entry>-</entry>
1351 <entry>-</entry>
1352 <entry>-</entry>
1353 <entry>-</entry>
1354 <entry>-</entry>
1355 <entry>-</entry>
1356 <entry>-</entry>
1357 <entry>-</entry>
1358 <entry>-</entry>
1359 <entry>-</entry>
1360 <entry>-</entry>
1361 <entry>-</entry>
1362 <entry>y<subscript>7</subscript></entry>
1363 <entry>y<subscript>6</subscript></entry>
1364 <entry>y<subscript>5</subscript></entry>
1365 <entry>y<subscript>4</subscript></entry>
1366 <entry>y<subscript>3</subscript></entry>
1367 <entry>y<subscript>2</subscript></entry>
1368 <entry>y<subscript>1</subscript></entry>
1369 <entry>y<subscript>0</subscript></entry>
1370 </row>
1371 <row>
1372 <entry></entry>
1373 <entry></entry>
1374 <entry></entry>
1375 <entry>-</entry>
1376 <entry>-</entry>
1377 <entry>-</entry>
1378 <entry>-</entry>
1379 <entry>-</entry>
1380 <entry>-</entry>
1381 <entry>-</entry>
1382 <entry>-</entry>
1383 <entry>-</entry>
1384 <entry>-</entry>
1385 <entry>-</entry>
1386 <entry>-</entry>
1387 <entry>y<subscript>7</subscript></entry>
1388 <entry>y<subscript>6</subscript></entry>
1389 <entry>y<subscript>5</subscript></entry>
1390 <entry>y<subscript>4</subscript></entry>
1391 <entry>y<subscript>3</subscript></entry>
1392 <entry>y<subscript>2</subscript></entry>
1393 <entry>y<subscript>1</subscript></entry>
1394 <entry>y<subscript>0</subscript></entry>
1395 </row>
1396 <row>
1397 <entry></entry>
1398 <entry></entry>
1399 <entry></entry>
1400 <entry>-</entry>
1401 <entry>-</entry>
1402 <entry>-</entry>
1403 <entry>-</entry>
1404 <entry>-</entry>
1405 <entry>-</entry>
1406 <entry>-</entry>
1407 <entry>-</entry>
1408 <entry>-</entry>
1409 <entry>-</entry>
1410 <entry>-</entry>
1411 <entry>-</entry>
1412 <entry>v<subscript>7</subscript></entry>
1413 <entry>v<subscript>6</subscript></entry>
1414 <entry>v<subscript>5</subscript></entry>
1415 <entry>v<subscript>4</subscript></entry>
1416 <entry>v<subscript>3</subscript></entry>
1417 <entry>v<subscript>2</subscript></entry>
1418 <entry>v<subscript>1</subscript></entry>
1419 <entry>v<subscript>0</subscript></entry>
1420 </row>
1421 <row id="V4L2-MBUS-FMT-YVYU8-1_5X8">
1422 <entry>V4L2_MBUS_FMT_YVYU8_1_5X8</entry>
1423 <entry>0x2005</entry>
1424 <entry></entry>
1425 <entry>-</entry>
1426 <entry>-</entry>
1427 <entry>-</entry>
1428 <entry>-</entry>
1429 <entry>-</entry>
1430 <entry>-</entry>
1431 <entry>-</entry>
1432 <entry>-</entry>
1433 <entry>-</entry>
1434 <entry>-</entry>
1435 <entry>-</entry>
1436 <entry>-</entry>
1437 <entry>y<subscript>7</subscript></entry>
1438 <entry>y<subscript>6</subscript></entry>
1439 <entry>y<subscript>5</subscript></entry>
1440 <entry>y<subscript>4</subscript></entry>
1441 <entry>y<subscript>3</subscript></entry>
1442 <entry>y<subscript>2</subscript></entry>
1443 <entry>y<subscript>1</subscript></entry>
1444 <entry>y<subscript>0</subscript></entry>
1445 </row>
1446 <row>
1447 <entry></entry>
1448 <entry></entry>
1449 <entry></entry>
1450 <entry>-</entry>
1451 <entry>-</entry>
1452 <entry>-</entry>
1453 <entry>-</entry>
1454 <entry>-</entry>
1455 <entry>-</entry>
1456 <entry>-</entry>
1457 <entry>-</entry>
1458 <entry>-</entry>
1459 <entry>-</entry>
1460 <entry>-</entry>
1461 <entry>-</entry>
1462 <entry>y<subscript>7</subscript></entry>
1463 <entry>y<subscript>6</subscript></entry>
1464 <entry>y<subscript>5</subscript></entry>
1465 <entry>y<subscript>4</subscript></entry>
1466 <entry>y<subscript>3</subscript></entry>
1467 <entry>y<subscript>2</subscript></entry>
1468 <entry>y<subscript>1</subscript></entry>
1469 <entry>y<subscript>0</subscript></entry>
1470 </row>
1471 <row>
1472 <entry></entry>
1473 <entry></entry>
1474 <entry></entry>
1475 <entry>-</entry>
1476 <entry>-</entry>
1477 <entry>-</entry>
1478 <entry>-</entry>
1479 <entry>-</entry>
1480 <entry>-</entry>
1481 <entry>-</entry>
1482 <entry>-</entry>
1483 <entry>-</entry>
1484 <entry>-</entry>
1485 <entry>-</entry>
1486 <entry>-</entry>
1487 <entry>v<subscript>7</subscript></entry>
1488 <entry>v<subscript>6</subscript></entry>
1489 <entry>v<subscript>5</subscript></entry>
1490 <entry>v<subscript>4</subscript></entry>
1491 <entry>v<subscript>3</subscript></entry>
1492 <entry>v<subscript>2</subscript></entry>
1493 <entry>v<subscript>1</subscript></entry>
1494 <entry>v<subscript>0</subscript></entry>
1495 </row>
1496 <row>
1497 <entry></entry>
1498 <entry></entry>
1499 <entry></entry>
1500 <entry>-</entry>
1501 <entry>-</entry>
1502 <entry>-</entry>
1503 <entry>-</entry>
1504 <entry>-</entry>
1505 <entry>-</entry>
1506 <entry>-</entry>
1507 <entry>-</entry>
1508 <entry>-</entry>
1509 <entry>-</entry>
1510 <entry>-</entry>
1511 <entry>-</entry>
1512 <entry>y<subscript>7</subscript></entry>
1513 <entry>y<subscript>6</subscript></entry>
1514 <entry>y<subscript>5</subscript></entry>
1515 <entry>y<subscript>4</subscript></entry>
1516 <entry>y<subscript>3</subscript></entry>
1517 <entry>y<subscript>2</subscript></entry>
1518 <entry>y<subscript>1</subscript></entry>
1519 <entry>y<subscript>0</subscript></entry>
1520 </row>
1521 <row>
1522 <entry></entry>
1523 <entry></entry>
1524 <entry></entry>
1525 <entry>-</entry>
1526 <entry>-</entry>
1527 <entry>-</entry>
1528 <entry>-</entry>
1529 <entry>-</entry>
1530 <entry>-</entry>
1531 <entry>-</entry>
1532 <entry>-</entry>
1533 <entry>-</entry>
1534 <entry>-</entry>
1535 <entry>-</entry>
1536 <entry>-</entry>
1537 <entry>y<subscript>7</subscript></entry>
1538 <entry>y<subscript>6</subscript></entry>
1539 <entry>y<subscript>5</subscript></entry>
1540 <entry>y<subscript>4</subscript></entry>
1541 <entry>y<subscript>3</subscript></entry>
1542 <entry>y<subscript>2</subscript></entry>
1543 <entry>y<subscript>1</subscript></entry>
1544 <entry>y<subscript>0</subscript></entry>
1545 </row>
1546 <row>
1547 <entry></entry>
1548 <entry></entry>
1549 <entry></entry>
1550 <entry>-</entry>
1551 <entry>-</entry>
1552 <entry>-</entry>
1553 <entry>-</entry>
1554 <entry>-</entry>
1555 <entry>-</entry>
1556 <entry>-</entry>
1557 <entry>-</entry>
1558 <entry>-</entry>
1559 <entry>-</entry>
1560 <entry>-</entry>
1561 <entry>-</entry>
1562 <entry>u<subscript>7</subscript></entry>
1563 <entry>u<subscript>6</subscript></entry>
1564 <entry>u<subscript>5</subscript></entry>
1565 <entry>u<subscript>4</subscript></entry>
1566 <entry>u<subscript>3</subscript></entry>
1567 <entry>u<subscript>2</subscript></entry>
1568 <entry>u<subscript>1</subscript></entry>
1569 <entry>u<subscript>0</subscript></entry>
1570 </row>
1571 <row id="V4L2-MBUS-FMT-UYVY8-2X8">
1572 <entry>V4L2_MBUS_FMT_UYVY8_2X8</entry>
1573 <entry>0x2006</entry>
1574 <entry></entry>
1575 <entry>-</entry>
1576 <entry>-</entry>
1577 <entry>-</entry>
1578 <entry>-</entry>
1579 <entry>-</entry>
1580 <entry>-</entry>
1581 <entry>-</entry>
1582 <entry>-</entry>
1583 <entry>-</entry>
1584 <entry>-</entry>
1585 <entry>-</entry>
1586 <entry>-</entry>
1587 <entry>u<subscript>7</subscript></entry>
1588 <entry>u<subscript>6</subscript></entry>
1589 <entry>u<subscript>5</subscript></entry>
1590 <entry>u<subscript>4</subscript></entry>
1591 <entry>u<subscript>3</subscript></entry>
1592 <entry>u<subscript>2</subscript></entry>
1593 <entry>u<subscript>1</subscript></entry>
1594 <entry>u<subscript>0</subscript></entry>
1595 </row>
1596 <row>
1597 <entry></entry>
1598 <entry></entry>
1599 <entry></entry>
1600 <entry>-</entry>
1601 <entry>-</entry>
1602 <entry>-</entry>
1603 <entry>-</entry>
1604 <entry>-</entry>
1605 <entry>-</entry>
1606 <entry>-</entry>
1607 <entry>-</entry>
1608 <entry>-</entry>
1609 <entry>-</entry>
1610 <entry>-</entry>
1611 <entry>-</entry>
1612 <entry>y<subscript>7</subscript></entry>
1613 <entry>y<subscript>6</subscript></entry>
1614 <entry>y<subscript>5</subscript></entry>
1615 <entry>y<subscript>4</subscript></entry>
1616 <entry>y<subscript>3</subscript></entry>
1617 <entry>y<subscript>2</subscript></entry>
1618 <entry>y<subscript>1</subscript></entry>
1619 <entry>y<subscript>0</subscript></entry>
1620 </row>
1621 <row>
1622 <entry></entry>
1623 <entry></entry>
1624 <entry></entry>
1625 <entry>-</entry>
1626 <entry>-</entry>
1627 <entry>-</entry>
1628 <entry>-</entry>
1629 <entry>-</entry>
1630 <entry>-</entry>
1631 <entry>-</entry>
1632 <entry>-</entry>
1633 <entry>-</entry>
1634 <entry>-</entry>
1635 <entry>-</entry>
1636 <entry>-</entry>
1637 <entry>v<subscript>7</subscript></entry>
1638 <entry>v<subscript>6</subscript></entry>
1639 <entry>v<subscript>5</subscript></entry>
1640 <entry>v<subscript>4</subscript></entry>
1641 <entry>v<subscript>3</subscript></entry>
1642 <entry>v<subscript>2</subscript></entry>
1643 <entry>v<subscript>1</subscript></entry>
1644 <entry>v<subscript>0</subscript></entry>
1645 </row>
1646 <row>
1647 <entry></entry>
1648 <entry></entry>
1649 <entry></entry>
1650 <entry>-</entry>
1651 <entry>-</entry>
1652 <entry>-</entry>
1653 <entry>-</entry>
1654 <entry>-</entry>
1655 <entry>-</entry>
1656 <entry>-</entry>
1657 <entry>-</entry>
1658 <entry>-</entry>
1659 <entry>-</entry>
1660 <entry>-</entry>
1661 <entry>-</entry>
1662 <entry>y<subscript>7</subscript></entry>
1663 <entry>y<subscript>6</subscript></entry>
1664 <entry>y<subscript>5</subscript></entry>
1665 <entry>y<subscript>4</subscript></entry>
1666 <entry>y<subscript>3</subscript></entry>
1667 <entry>y<subscript>2</subscript></entry>
1668 <entry>y<subscript>1</subscript></entry>
1669 <entry>y<subscript>0</subscript></entry>
1670 </row>
1671 <row id="V4L2-MBUS-FMT-VYUY8-2X8">
1672 <entry>V4L2_MBUS_FMT_VYUY8_2X8</entry>
1673 <entry>0x2007</entry>
1674 <entry></entry>
1675 <entry>-</entry>
1676 <entry>-</entry>
1677 <entry>-</entry>
1678 <entry>-</entry>
1679 <entry>-</entry>
1680 <entry>-</entry>
1681 <entry>-</entry>
1682 <entry>-</entry>
1683 <entry>-</entry>
1684 <entry>-</entry>
1685 <entry>-</entry>
1686 <entry>-</entry>
1687 <entry>v<subscript>7</subscript></entry>
1688 <entry>v<subscript>6</subscript></entry>
1689 <entry>v<subscript>5</subscript></entry>
1690 <entry>v<subscript>4</subscript></entry>
1691 <entry>v<subscript>3</subscript></entry>
1692 <entry>v<subscript>2</subscript></entry>
1693 <entry>v<subscript>1</subscript></entry>
1694 <entry>v<subscript>0</subscript></entry>
1695 </row>
1696 <row>
1697 <entry></entry>
1698 <entry></entry>
1699 <entry></entry>
1700 <entry>-</entry>
1701 <entry>-</entry>
1702 <entry>-</entry>
1703 <entry>-</entry>
1704 <entry>-</entry>
1705 <entry>-</entry>
1706 <entry>-</entry>
1707 <entry>-</entry>
1708 <entry>-</entry>
1709 <entry>-</entry>
1710 <entry>-</entry>
1711 <entry>-</entry>
1712 <entry>y<subscript>7</subscript></entry>
1713 <entry>y<subscript>6</subscript></entry>
1714 <entry>y<subscript>5</subscript></entry>
1715 <entry>y<subscript>4</subscript></entry>
1716 <entry>y<subscript>3</subscript></entry>
1717 <entry>y<subscript>2</subscript></entry>
1718 <entry>y<subscript>1</subscript></entry>
1719 <entry>y<subscript>0</subscript></entry>
1720 </row>
1721 <row>
1722 <entry></entry>
1723 <entry></entry>
1724 <entry></entry>
1725 <entry>-</entry>
1726 <entry>-</entry>
1727 <entry>-</entry>
1728 <entry>-</entry>
1729 <entry>-</entry>
1730 <entry>-</entry>
1731 <entry>-</entry>
1732 <entry>-</entry>
1733 <entry>-</entry>
1734 <entry>-</entry>
1735 <entry>-</entry>
1736 <entry>-</entry>
1737 <entry>u<subscript>7</subscript></entry>
1738 <entry>u<subscript>6</subscript></entry>
1739 <entry>u<subscript>5</subscript></entry>
1740 <entry>u<subscript>4</subscript></entry>
1741 <entry>u<subscript>3</subscript></entry>
1742 <entry>u<subscript>2</subscript></entry>
1743 <entry>u<subscript>1</subscript></entry>
1744 <entry>u<subscript>0</subscript></entry>
1745 </row>
1746 <row>
1747 <entry></entry>
1748 <entry></entry>
1749 <entry></entry>
1750 <entry>-</entry>
1751 <entry>-</entry>
1752 <entry>-</entry>
1753 <entry>-</entry>
1754 <entry>-</entry>
1755 <entry>-</entry>
1756 <entry>-</entry>
1757 <entry>-</entry>
1758 <entry>-</entry>
1759 <entry>-</entry>
1760 <entry>-</entry>
1761 <entry>-</entry>
1762 <entry>y<subscript>7</subscript></entry>
1763 <entry>y<subscript>6</subscript></entry>
1764 <entry>y<subscript>5</subscript></entry>
1765 <entry>y<subscript>4</subscript></entry>
1766 <entry>y<subscript>3</subscript></entry>
1767 <entry>y<subscript>2</subscript></entry>
1768 <entry>y<subscript>1</subscript></entry>
1769 <entry>y<subscript>0</subscript></entry>
1770 </row>
1771 <row id="V4L2-MBUS-FMT-YUYV8-2X8">
1772 <entry>V4L2_MBUS_FMT_YUYV8_2X8</entry>
1773 <entry>0x2008</entry>
1774 <entry></entry>
1775 <entry>-</entry>
1776 <entry>-</entry>
1777 <entry>-</entry>
1778 <entry>-</entry>
1779 <entry>-</entry>
1780 <entry>-</entry>
1781 <entry>-</entry>
1782 <entry>-</entry>
1783 <entry>-</entry>
1784 <entry>-</entry>
1785 <entry>-</entry>
1786 <entry>-</entry>
1787 <entry>y<subscript>7</subscript></entry>
1788 <entry>y<subscript>6</subscript></entry>
1789 <entry>y<subscript>5</subscript></entry>
1790 <entry>y<subscript>4</subscript></entry>
1791 <entry>y<subscript>3</subscript></entry>
1792 <entry>y<subscript>2</subscript></entry>
1793 <entry>y<subscript>1</subscript></entry>
1794 <entry>y<subscript>0</subscript></entry>
1795 </row>
1796 <row>
1797 <entry></entry>
1798 <entry></entry>
1799 <entry></entry>
1800 <entry>-</entry>
1801 <entry>-</entry>
1802 <entry>-</entry>
1803 <entry>-</entry>
1804 <entry>-</entry>
1805 <entry>-</entry>
1806 <entry>-</entry>
1807 <entry>-</entry>
1808 <entry>-</entry>
1809 <entry>-</entry>
1810 <entry>-</entry>
1811 <entry>-</entry>
1812 <entry>u<subscript>7</subscript></entry>
1813 <entry>u<subscript>6</subscript></entry>
1814 <entry>u<subscript>5</subscript></entry>
1815 <entry>u<subscript>4</subscript></entry>
1816 <entry>u<subscript>3</subscript></entry>
1817 <entry>u<subscript>2</subscript></entry>
1818 <entry>u<subscript>1</subscript></entry>
1819 <entry>u<subscript>0</subscript></entry>
1820 </row>
1821 <row>
1822 <entry></entry>
1823 <entry></entry>
1824 <entry></entry>
1825 <entry>-</entry>
1826 <entry>-</entry>
1827 <entry>-</entry>
1828 <entry>-</entry>
1829 <entry>-</entry>
1830 <entry>-</entry>
1831 <entry>-</entry>
1832 <entry>-</entry>
1833 <entry>-</entry>
1834 <entry>-</entry>
1835 <entry>-</entry>
1836 <entry>-</entry>
1837 <entry>y<subscript>7</subscript></entry>
1838 <entry>y<subscript>6</subscript></entry>
1839 <entry>y<subscript>5</subscript></entry>
1840 <entry>y<subscript>4</subscript></entry>
1841 <entry>y<subscript>3</subscript></entry>
1842 <entry>y<subscript>2</subscript></entry>
1843 <entry>y<subscript>1</subscript></entry>
1844 <entry>y<subscript>0</subscript></entry>
1845 </row>
1846 <row>
1847 <entry></entry>
1848 <entry></entry>
1849 <entry></entry>
1850 <entry>-</entry>
1851 <entry>-</entry>
1852 <entry>-</entry>
1853 <entry>-</entry>
1854 <entry>-</entry>
1855 <entry>-</entry>
1856 <entry>-</entry>
1857 <entry>-</entry>
1858 <entry>-</entry>
1859 <entry>-</entry>
1860 <entry>-</entry>
1861 <entry>-</entry>
1862 <entry>v<subscript>7</subscript></entry>
1863 <entry>v<subscript>6</subscript></entry>
1864 <entry>v<subscript>5</subscript></entry>
1865 <entry>v<subscript>4</subscript></entry>
1866 <entry>v<subscript>3</subscript></entry>
1867 <entry>v<subscript>2</subscript></entry>
1868 <entry>v<subscript>1</subscript></entry>
1869 <entry>v<subscript>0</subscript></entry>
1870 </row>
1871 <row id="V4L2-MBUS-FMT-YVYU8-2X8">
1872 <entry>V4L2_MBUS_FMT_YVYU8_2X8</entry>
1873 <entry>0x2009</entry>
1874 <entry></entry>
1875 <entry>-</entry>
1876 <entry>-</entry>
1877 <entry>-</entry>
1878 <entry>-</entry>
1879 <entry>-</entry>
1880 <entry>-</entry>
1881 <entry>-</entry>
1882 <entry>-</entry>
1883 <entry>-</entry>
1884 <entry>-</entry>
1885 <entry>-</entry>
1886 <entry>-</entry>
1887 <entry>y<subscript>7</subscript></entry>
1888 <entry>y<subscript>6</subscript></entry>
1889 <entry>y<subscript>5</subscript></entry>
1890 <entry>y<subscript>4</subscript></entry>
1891 <entry>y<subscript>3</subscript></entry>
1892 <entry>y<subscript>2</subscript></entry>
1893 <entry>y<subscript>1</subscript></entry>
1894 <entry>y<subscript>0</subscript></entry>
1895 </row>
1896 <row>
1897 <entry></entry>
1898 <entry></entry>
1899 <entry></entry>
1900 <entry>-</entry>
1901 <entry>-</entry>
1902 <entry>-</entry>
1903 <entry>-</entry>
1904 <entry>-</entry>
1905 <entry>-</entry>
1906 <entry>-</entry>
1907 <entry>-</entry>
1908 <entry>-</entry>
1909 <entry>-</entry>
1910 <entry>-</entry>
1911 <entry>-</entry>
1912 <entry>v<subscript>7</subscript></entry>
1913 <entry>v<subscript>6</subscript></entry>
1914 <entry>v<subscript>5</subscript></entry>
1915 <entry>v<subscript>4</subscript></entry>
1916 <entry>v<subscript>3</subscript></entry>
1917 <entry>v<subscript>2</subscript></entry>
1918 <entry>v<subscript>1</subscript></entry>
1919 <entry>v<subscript>0</subscript></entry>
1920 </row>
1921 <row>
1922 <entry></entry>
1923 <entry></entry>
1924 <entry></entry>
1925 <entry>-</entry>
1926 <entry>-</entry>
1927 <entry>-</entry>
1928 <entry>-</entry>
1929 <entry>-</entry>
1930 <entry>-</entry>
1931 <entry>-</entry>
1932 <entry>-</entry>
1933 <entry>-</entry>
1934 <entry>-</entry>
1935 <entry>-</entry>
1936 <entry>-</entry>
1937 <entry>y<subscript>7</subscript></entry>
1938 <entry>y<subscript>6</subscript></entry>
1939 <entry>y<subscript>5</subscript></entry>
1940 <entry>y<subscript>4</subscript></entry>
1941 <entry>y<subscript>3</subscript></entry>
1942 <entry>y<subscript>2</subscript></entry>
1943 <entry>y<subscript>1</subscript></entry>
1944 <entry>y<subscript>0</subscript></entry>
1945 </row>
1946 <row>
1947 <entry></entry>
1948 <entry></entry>
1949 <entry></entry>
1950 <entry>-</entry>
1951 <entry>-</entry>
1952 <entry>-</entry>
1953 <entry>-</entry>
1954 <entry>-</entry>
1955 <entry>-</entry>
1956 <entry>-</entry>
1957 <entry>-</entry>
1958 <entry>-</entry>
1959 <entry>-</entry>
1960 <entry>-</entry>
1961 <entry>-</entry>
1962 <entry>u<subscript>7</subscript></entry>
1963 <entry>u<subscript>6</subscript></entry>
1964 <entry>u<subscript>5</subscript></entry>
1965 <entry>u<subscript>4</subscript></entry>
1966 <entry>u<subscript>3</subscript></entry>
1967 <entry>u<subscript>2</subscript></entry>
1968 <entry>u<subscript>1</subscript></entry>
1969 <entry>u<subscript>0</subscript></entry>
1970 </row>
1971 <row id="V4L2-MBUS-FMT-Y10-1X10">
1972 <entry>V4L2_MBUS_FMT_Y10_1X10</entry>
1973 <entry>0x200a</entry>
1974 <entry></entry>
1975 <entry>-</entry>
1976 <entry>-</entry>
1977 <entry>-</entry>
1978 <entry>-</entry>
1979 <entry>-</entry>
1980 <entry>-</entry>
1981 <entry>-</entry>
1982 <entry>-</entry>
1983 <entry>-</entry>
1984 <entry>-</entry>
1985 <entry>y<subscript>9</subscript></entry>
1986 <entry>y<subscript>8</subscript></entry>
1987 <entry>y<subscript>7</subscript></entry>
1988 <entry>y<subscript>6</subscript></entry>
1989 <entry>y<subscript>5</subscript></entry>
1990 <entry>y<subscript>4</subscript></entry>
1991 <entry>y<subscript>3</subscript></entry>
1992 <entry>y<subscript>2</subscript></entry>
1993 <entry>y<subscript>1</subscript></entry>
1994 <entry>y<subscript>0</subscript></entry>
1995 </row>
1996 <row id="V4L2-MBUS-FMT-YUYV10-2X10">
1997 <entry>V4L2_MBUS_FMT_YUYV10_2X10</entry>
1998 <entry>0x200b</entry>
1999 <entry></entry>
2000 <entry>-</entry>
2001 <entry>-</entry>
2002 <entry>-</entry>
2003 <entry>-</entry>
2004 <entry>-</entry>
2005 <entry>-</entry>
2006 <entry>-</entry>
2007 <entry>-</entry>
2008 <entry>-</entry>
2009 <entry>-</entry>
2010 <entry>y<subscript>9</subscript></entry>
2011 <entry>y<subscript>8</subscript></entry>
2012 <entry>y<subscript>7</subscript></entry>
2013 <entry>y<subscript>6</subscript></entry>
2014 <entry>y<subscript>5</subscript></entry>
2015 <entry>y<subscript>4</subscript></entry>
2016 <entry>y<subscript>3</subscript></entry>
2017 <entry>y<subscript>2</subscript></entry>
2018 <entry>y<subscript>1</subscript></entry>
2019 <entry>y<subscript>0</subscript></entry>
2020 </row>
2021 <row>
2022 <entry></entry>
2023 <entry></entry>
2024 <entry></entry>
2025 <entry>-</entry>
2026 <entry>-</entry>
2027 <entry>-</entry>
2028 <entry>-</entry>
2029 <entry>-</entry>
2030 <entry>-</entry>
2031 <entry>-</entry>
2032 <entry>-</entry>
2033 <entry>-</entry>
2034 <entry>-</entry>
2035 <entry>u<subscript>9</subscript></entry>
2036 <entry>u<subscript>8</subscript></entry>
2037 <entry>u<subscript>7</subscript></entry>
2038 <entry>u<subscript>6</subscript></entry>
2039 <entry>u<subscript>5</subscript></entry>
2040 <entry>u<subscript>4</subscript></entry>
2041 <entry>u<subscript>3</subscript></entry>
2042 <entry>u<subscript>2</subscript></entry>
2043 <entry>u<subscript>1</subscript></entry>
2044 <entry>u<subscript>0</subscript></entry>
2045 </row>
2046 <row>
2047 <entry></entry>
2048 <entry></entry>
2049 <entry></entry>
2050 <entry>-</entry>
2051 <entry>-</entry>
2052 <entry>-</entry>
2053 <entry>-</entry>
2054 <entry>-</entry>
2055 <entry>-</entry>
2056 <entry>-</entry>
2057 <entry>-</entry>
2058 <entry>-</entry>
2059 <entry>-</entry>
2060 <entry>y<subscript>9</subscript></entry>
2061 <entry>y<subscript>8</subscript></entry>
2062 <entry>y<subscript>7</subscript></entry>
2063 <entry>y<subscript>6</subscript></entry>
2064 <entry>y<subscript>5</subscript></entry>
2065 <entry>y<subscript>4</subscript></entry>
2066 <entry>y<subscript>3</subscript></entry>
2067 <entry>y<subscript>2</subscript></entry>
2068 <entry>y<subscript>1</subscript></entry>
2069 <entry>y<subscript>0</subscript></entry>
2070 </row>
2071 <row>
2072 <entry></entry>
2073 <entry></entry>
2074 <entry></entry>
2075 <entry>-</entry>
2076 <entry>-</entry>
2077 <entry>-</entry>
2078 <entry>-</entry>
2079 <entry>-</entry>
2080 <entry>-</entry>
2081 <entry>-</entry>
2082 <entry>-</entry>
2083 <entry>-</entry>
2084 <entry>-</entry>
2085 <entry>v<subscript>9</subscript></entry>
2086 <entry>v<subscript>8</subscript></entry>
2087 <entry>v<subscript>7</subscript></entry>
2088 <entry>v<subscript>6</subscript></entry>
2089 <entry>v<subscript>5</subscript></entry>
2090 <entry>v<subscript>4</subscript></entry>
2091 <entry>v<subscript>3</subscript></entry>
2092 <entry>v<subscript>2</subscript></entry>
2093 <entry>v<subscript>1</subscript></entry>
2094 <entry>v<subscript>0</subscript></entry>
2095 </row>
2096 <row id="V4L2-MBUS-FMT-YVYU10-2X10">
2097 <entry>V4L2_MBUS_FMT_YVYU10_2X10</entry>
2098 <entry>0x200c</entry>
2099 <entry></entry>
2100 <entry>-</entry>
2101 <entry>-</entry>
2102 <entry>-</entry>
2103 <entry>-</entry>
2104 <entry>-</entry>
2105 <entry>-</entry>
2106 <entry>-</entry>
2107 <entry>-</entry>
2108 <entry>-</entry>
2109 <entry>-</entry>
2110 <entry>y<subscript>9</subscript></entry>
2111 <entry>y<subscript>8</subscript></entry>
2112 <entry>y<subscript>7</subscript></entry>
2113 <entry>y<subscript>6</subscript></entry>
2114 <entry>y<subscript>5</subscript></entry>
2115 <entry>y<subscript>4</subscript></entry>
2116 <entry>y<subscript>3</subscript></entry>
2117 <entry>y<subscript>2</subscript></entry>
2118 <entry>y<subscript>1</subscript></entry>
2119 <entry>y<subscript>0</subscript></entry>
2120 </row>
2121 <row>
2122 <entry></entry>
2123 <entry></entry>
2124 <entry></entry>
2125 <entry>-</entry>
2126 <entry>-</entry>
2127 <entry>-</entry>
2128 <entry>-</entry>
2129 <entry>-</entry>
2130 <entry>-</entry>
2131 <entry>-</entry>
2132 <entry>-</entry>
2133 <entry>-</entry>
2134 <entry>-</entry>
2135 <entry>v<subscript>9</subscript></entry>
2136 <entry>v<subscript>8</subscript></entry>
2137 <entry>v<subscript>7</subscript></entry>
2138 <entry>v<subscript>6</subscript></entry>
2139 <entry>v<subscript>5</subscript></entry>
2140 <entry>v<subscript>4</subscript></entry>
2141 <entry>v<subscript>3</subscript></entry>
2142 <entry>v<subscript>2</subscript></entry>
2143 <entry>v<subscript>1</subscript></entry>
2144 <entry>v<subscript>0</subscript></entry>
2145 </row>
2146 <row>
2147 <entry></entry>
2148 <entry></entry>
2149 <entry></entry>
2150 <entry>-</entry>
2151 <entry>-</entry>
2152 <entry>-</entry>
2153 <entry>-</entry>
2154 <entry>-</entry>
2155 <entry>-</entry>
2156 <entry>-</entry>
2157 <entry>-</entry>
2158 <entry>-</entry>
2159 <entry>-</entry>
2160 <entry>y<subscript>9</subscript></entry>
2161 <entry>y<subscript>8</subscript></entry>
2162 <entry>y<subscript>7</subscript></entry>
2163 <entry>y<subscript>6</subscript></entry>
2164 <entry>y<subscript>5</subscript></entry>
2165 <entry>y<subscript>4</subscript></entry>
2166 <entry>y<subscript>3</subscript></entry>
2167 <entry>y<subscript>2</subscript></entry>
2168 <entry>y<subscript>1</subscript></entry>
2169 <entry>y<subscript>0</subscript></entry>
2170 </row>
2171 <row>
2172 <entry></entry>
2173 <entry></entry>
2174 <entry></entry>
2175 <entry>-</entry>
2176 <entry>-</entry>
2177 <entry>-</entry>
2178 <entry>-</entry>
2179 <entry>-</entry>
2180 <entry>-</entry>
2181 <entry>-</entry>
2182 <entry>-</entry>
2183 <entry>-</entry>
2184 <entry>-</entry>
2185 <entry>u<subscript>9</subscript></entry>
2186 <entry>u<subscript>8</subscript></entry>
2187 <entry>u<subscript>7</subscript></entry>
2188 <entry>u<subscript>6</subscript></entry>
2189 <entry>u<subscript>5</subscript></entry>
2190 <entry>u<subscript>4</subscript></entry>
2191 <entry>u<subscript>3</subscript></entry>
2192 <entry>u<subscript>2</subscript></entry>
2193 <entry>u<subscript>1</subscript></entry>
2194 <entry>u<subscript>0</subscript></entry>
2195 </row>
2196 <row id="V4L2-MBUS-FMT-Y12-1X12">
2197 <entry>V4L2_MBUS_FMT_Y12_1X12</entry>
2198 <entry>0x2013</entry>
2199 <entry></entry>
2200 <entry>-</entry>
2201 <entry>-</entry>
2202 <entry>-</entry>
2203 <entry>-</entry>
2204 <entry>-</entry>
2205 <entry>-</entry>
2206 <entry>-</entry>
2207 <entry>-</entry>
2208 <entry>y<subscript>11</subscript></entry>
2209 <entry>y<subscript>10</subscript></entry>
2210 <entry>y<subscript>9</subscript></entry>
2211 <entry>y<subscript>8</subscript></entry>
2212 <entry>y<subscript>7</subscript></entry>
2213 <entry>y<subscript>6</subscript></entry>
2214 <entry>y<subscript>5</subscript></entry>
2215 <entry>y<subscript>4</subscript></entry>
2216 <entry>y<subscript>3</subscript></entry>
2217 <entry>y<subscript>2</subscript></entry>
2218 <entry>y<subscript>1</subscript></entry>
2219 <entry>y<subscript>0</subscript></entry>
2220 </row>
2221 <row id="V4L2-MBUS-FMT-UYVY8-1X16">
2222 <entry>V4L2_MBUS_FMT_UYVY8_1X16</entry>
2223 <entry>0x200f</entry>
2224 <entry></entry>
2225 <entry>-</entry>
2226 <entry>-</entry>
2227 <entry>-</entry>
2228 <entry>-</entry>
2229 <entry>u<subscript>7</subscript></entry>
2230 <entry>u<subscript>6</subscript></entry>
2231 <entry>u<subscript>5</subscript></entry>
2232 <entry>u<subscript>4</subscript></entry>
2233 <entry>u<subscript>3</subscript></entry>
2234 <entry>u<subscript>2</subscript></entry>
2235 <entry>u<subscript>1</subscript></entry>
2236 <entry>u<subscript>0</subscript></entry>
2237 <entry>y<subscript>7</subscript></entry>
2238 <entry>y<subscript>6</subscript></entry>
2239 <entry>y<subscript>5</subscript></entry>
2240 <entry>y<subscript>4</subscript></entry>
2241 <entry>y<subscript>3</subscript></entry>
2242 <entry>y<subscript>2</subscript></entry>
2243 <entry>y<subscript>1</subscript></entry>
2244 <entry>y<subscript>0</subscript></entry>
2245 </row>
2246 <row>
2247 <entry></entry>
2248 <entry></entry>
2249 <entry></entry>
2250 <entry>-</entry>
2251 <entry>-</entry>
2252 <entry>-</entry>
2253 <entry>-</entry>
2254 <entry>v<subscript>7</subscript></entry>
2255 <entry>v<subscript>6</subscript></entry>
2256 <entry>v<subscript>5</subscript></entry>
2257 <entry>v<subscript>4</subscript></entry>
2258 <entry>v<subscript>3</subscript></entry>
2259 <entry>v<subscript>2</subscript></entry>
2260 <entry>v<subscript>1</subscript></entry>
2261 <entry>v<subscript>0</subscript></entry>
2262 <entry>y<subscript>7</subscript></entry>
2263 <entry>y<subscript>6</subscript></entry>
2264 <entry>y<subscript>5</subscript></entry>
2265 <entry>y<subscript>4</subscript></entry>
2266 <entry>y<subscript>3</subscript></entry>
2267 <entry>y<subscript>2</subscript></entry>
2268 <entry>y<subscript>1</subscript></entry>
2269 <entry>y<subscript>0</subscript></entry>
2270 </row>
2271 <row id="V4L2-MBUS-FMT-VYUY8-1X16">
2272 <entry>V4L2_MBUS_FMT_VYUY8_1X16</entry>
2273 <entry>0x2010</entry>
2274 <entry></entry>
2275 <entry>-</entry>
2276 <entry>-</entry>
2277 <entry>-</entry>
2278 <entry>-</entry>
2279 <entry>v<subscript>7</subscript></entry>
2280 <entry>v<subscript>6</subscript></entry>
2281 <entry>v<subscript>5</subscript></entry>
2282 <entry>v<subscript>4</subscript></entry>
2283 <entry>v<subscript>3</subscript></entry>
2284 <entry>v<subscript>2</subscript></entry>
2285 <entry>v<subscript>1</subscript></entry>
2286 <entry>v<subscript>0</subscript></entry>
2287 <entry>y<subscript>7</subscript></entry>
2288 <entry>y<subscript>6</subscript></entry>
2289 <entry>y<subscript>5</subscript></entry>
2290 <entry>y<subscript>4</subscript></entry>
2291 <entry>y<subscript>3</subscript></entry>
2292 <entry>y<subscript>2</subscript></entry>
2293 <entry>y<subscript>1</subscript></entry>
2294 <entry>y<subscript>0</subscript></entry>
2295 </row>
2296 <row>
2297 <entry></entry>
2298 <entry></entry>
2299 <entry></entry>
2300 <entry>-</entry>
2301 <entry>-</entry>
2302 <entry>-</entry>
2303 <entry>-</entry>
2304 <entry>u<subscript>7</subscript></entry>
2305 <entry>u<subscript>6</subscript></entry>
2306 <entry>u<subscript>5</subscript></entry>
2307 <entry>u<subscript>4</subscript></entry>
2308 <entry>u<subscript>3</subscript></entry>
2309 <entry>u<subscript>2</subscript></entry>
2310 <entry>u<subscript>1</subscript></entry>
2311 <entry>u<subscript>0</subscript></entry>
2312 <entry>y<subscript>7</subscript></entry>
2313 <entry>y<subscript>6</subscript></entry>
2314 <entry>y<subscript>5</subscript></entry>
2315 <entry>y<subscript>4</subscript></entry>
2316 <entry>y<subscript>3</subscript></entry>
2317 <entry>y<subscript>2</subscript></entry>
2318 <entry>y<subscript>1</subscript></entry>
2319 <entry>y<subscript>0</subscript></entry>
2320 </row>
2321 <row id="V4L2-MBUS-FMT-YUYV8-1X16">
2322 <entry>V4L2_MBUS_FMT_YUYV8_1X16</entry>
2323 <entry>0x2011</entry>
2324 <entry></entry>
2325 <entry>-</entry>
2326 <entry>-</entry>
2327 <entry>-</entry>
2328 <entry>-</entry>
2329 <entry>y<subscript>7</subscript></entry>
2330 <entry>y<subscript>6</subscript></entry>
2331 <entry>y<subscript>5</subscript></entry>
2332 <entry>y<subscript>4</subscript></entry>
2333 <entry>y<subscript>3</subscript></entry>
2334 <entry>y<subscript>2</subscript></entry>
2335 <entry>y<subscript>1</subscript></entry>
2336 <entry>y<subscript>0</subscript></entry>
2337 <entry>u<subscript>7</subscript></entry>
2338 <entry>u<subscript>6</subscript></entry>
2339 <entry>u<subscript>5</subscript></entry>
2340 <entry>u<subscript>4</subscript></entry>
2341 <entry>u<subscript>3</subscript></entry>
2342 <entry>u<subscript>2</subscript></entry>
2343 <entry>u<subscript>1</subscript></entry>
2344 <entry>u<subscript>0</subscript></entry>
2345 </row>
2346 <row>
2347 <entry></entry>
2348 <entry></entry>
2349 <entry></entry>
2350 <entry>-</entry>
2351 <entry>-</entry>
2352 <entry>-</entry>
2353 <entry>-</entry>
2354 <entry>y<subscript>7</subscript></entry>
2355 <entry>y<subscript>6</subscript></entry>
2356 <entry>y<subscript>5</subscript></entry>
2357 <entry>y<subscript>4</subscript></entry>
2358 <entry>y<subscript>3</subscript></entry>
2359 <entry>y<subscript>2</subscript></entry>
2360 <entry>y<subscript>1</subscript></entry>
2361 <entry>y<subscript>0</subscript></entry>
2362 <entry>v<subscript>7</subscript></entry>
2363 <entry>v<subscript>6</subscript></entry>
2364 <entry>v<subscript>5</subscript></entry>
2365 <entry>v<subscript>4</subscript></entry>
2366 <entry>v<subscript>3</subscript></entry>
2367 <entry>v<subscript>2</subscript></entry>
2368 <entry>v<subscript>1</subscript></entry>
2369 <entry>v<subscript>0</subscript></entry>
2370 </row>
2371 <row id="V4L2-MBUS-FMT-YVYU8-1X16">
2372 <entry>V4L2_MBUS_FMT_YVYU8_1X16</entry>
2373 <entry>0x2012</entry>
2374 <entry></entry>
2375 <entry>-</entry>
2376 <entry>-</entry>
2377 <entry>-</entry>
2378 <entry>-</entry>
2379 <entry>y<subscript>7</subscript></entry>
2380 <entry>y<subscript>6</subscript></entry>
2381 <entry>y<subscript>5</subscript></entry>
2382 <entry>y<subscript>4</subscript></entry>
2383 <entry>y<subscript>3</subscript></entry>
2384 <entry>y<subscript>2</subscript></entry>
2385 <entry>y<subscript>1</subscript></entry>
2386 <entry>y<subscript>0</subscript></entry>
2387 <entry>v<subscript>7</subscript></entry>
2388 <entry>v<subscript>6</subscript></entry>
2389 <entry>v<subscript>5</subscript></entry>
2390 <entry>v<subscript>4</subscript></entry>
2391 <entry>v<subscript>3</subscript></entry>
2392 <entry>v<subscript>2</subscript></entry>
2393 <entry>v<subscript>1</subscript></entry>
2394 <entry>v<subscript>0</subscript></entry>
2395 </row>
2396 <row>
2397 <entry></entry>
2398 <entry></entry>
2399 <entry></entry>
2400 <entry>-</entry>
2401 <entry>-</entry>
2402 <entry>-</entry>
2403 <entry>-</entry>
2404 <entry>y<subscript>7</subscript></entry>
2405 <entry>y<subscript>6</subscript></entry>
2406 <entry>y<subscript>5</subscript></entry>
2407 <entry>y<subscript>4</subscript></entry>
2408 <entry>y<subscript>3</subscript></entry>
2409 <entry>y<subscript>2</subscript></entry>
2410 <entry>y<subscript>1</subscript></entry>
2411 <entry>y<subscript>0</subscript></entry>
2412 <entry>u<subscript>7</subscript></entry>
2413 <entry>u<subscript>6</subscript></entry>
2414 <entry>u<subscript>5</subscript></entry>
2415 <entry>u<subscript>4</subscript></entry>
2416 <entry>u<subscript>3</subscript></entry>
2417 <entry>u<subscript>2</subscript></entry>
2418 <entry>u<subscript>1</subscript></entry>
2419 <entry>u<subscript>0</subscript></entry>
2420 </row>
2421 <row id="V4L2-MBUS-FMT-YUYV10-1X20">
2422 <entry>V4L2_MBUS_FMT_YUYV10_1X20</entry>
2423 <entry>0x200d</entry>
2424 <entry></entry>
2425 <entry>y<subscript>9</subscript></entry>
2426 <entry>y<subscript>8</subscript></entry>
2427 <entry>y<subscript>7</subscript></entry>
2428 <entry>y<subscript>6</subscript></entry>
2429 <entry>y<subscript>5</subscript></entry>
2430 <entry>y<subscript>4</subscript></entry>
2431 <entry>y<subscript>3</subscript></entry>
2432 <entry>y<subscript>2</subscript></entry>
2433 <entry>y<subscript>1</subscript></entry>
2434 <entry>y<subscript>0</subscript></entry>
2435 <entry>u<subscript>9</subscript></entry>
2436 <entry>u<subscript>8</subscript></entry>
2437 <entry>u<subscript>7</subscript></entry>
2438 <entry>u<subscript>6</subscript></entry>
2439 <entry>u<subscript>5</subscript></entry>
2440 <entry>u<subscript>4</subscript></entry>
2441 <entry>u<subscript>3</subscript></entry>
2442 <entry>u<subscript>2</subscript></entry>
2443 <entry>u<subscript>1</subscript></entry>
2444 <entry>u<subscript>0</subscript></entry>
2445 </row>
2446 <row>
2447 <entry></entry>
2448 <entry></entry>
2449 <entry></entry>
2450 <entry>y<subscript>9</subscript></entry>
2451 <entry>y<subscript>8</subscript></entry>
2452 <entry>y<subscript>7</subscript></entry>
2453 <entry>y<subscript>6</subscript></entry>
2454 <entry>y<subscript>5</subscript></entry>
2455 <entry>y<subscript>4</subscript></entry>
2456 <entry>y<subscript>3</subscript></entry>
2457 <entry>y<subscript>2</subscript></entry>
2458 <entry>y<subscript>1</subscript></entry>
2459 <entry>y<subscript>0</subscript></entry>
2460 <entry>v<subscript>9</subscript></entry>
2461 <entry>v<subscript>8</subscript></entry>
2462 <entry>v<subscript>7</subscript></entry>
2463 <entry>v<subscript>6</subscript></entry>
2464 <entry>v<subscript>5</subscript></entry>
2465 <entry>v<subscript>4</subscript></entry>
2466 <entry>v<subscript>3</subscript></entry>
2467 <entry>v<subscript>2</subscript></entry>
2468 <entry>v<subscript>1</subscript></entry>
2469 <entry>v<subscript>0</subscript></entry>
2470 </row>
2471 <row id="V4L2-MBUS-FMT-YVYU10-1X20">
2472 <entry>V4L2_MBUS_FMT_YVYU10_1X20</entry>
2473 <entry>0x200e</entry>
2474 <entry></entry>
2475 <entry>y<subscript>9</subscript></entry>
2476 <entry>y<subscript>8</subscript></entry>
2477 <entry>y<subscript>7</subscript></entry>
2478 <entry>y<subscript>6</subscript></entry>
2479 <entry>y<subscript>5</subscript></entry>
2480 <entry>y<subscript>4</subscript></entry>
2481 <entry>y<subscript>3</subscript></entry>
2482 <entry>y<subscript>2</subscript></entry>
2483 <entry>y<subscript>1</subscript></entry>
2484 <entry>y<subscript>0</subscript></entry>
2485 <entry>v<subscript>9</subscript></entry>
2486 <entry>v<subscript>8</subscript></entry>
2487 <entry>v<subscript>7</subscript></entry>
2488 <entry>v<subscript>6</subscript></entry>
2489 <entry>v<subscript>5</subscript></entry>
2490 <entry>v<subscript>4</subscript></entry>
2491 <entry>v<subscript>3</subscript></entry>
2492 <entry>v<subscript>2</subscript></entry>
2493 <entry>v<subscript>1</subscript></entry>
2494 <entry>v<subscript>0</subscript></entry>
2495 </row>
2496 <row>
2497 <entry></entry>
2498 <entry></entry>
2499 <entry></entry>
2500 <entry>y<subscript>9</subscript></entry>
2501 <entry>y<subscript>8</subscript></entry>
2502 <entry>y<subscript>7</subscript></entry>
2503 <entry>y<subscript>6</subscript></entry>
2504 <entry>y<subscript>5</subscript></entry>
2505 <entry>y<subscript>4</subscript></entry>
2506 <entry>y<subscript>3</subscript></entry>
2507 <entry>y<subscript>2</subscript></entry>
2508 <entry>y<subscript>1</subscript></entry>
2509 <entry>y<subscript>0</subscript></entry>
2510 <entry>u<subscript>9</subscript></entry>
2511 <entry>u<subscript>8</subscript></entry>
2512 <entry>u<subscript>7</subscript></entry>
2513 <entry>u<subscript>6</subscript></entry>
2514 <entry>u<subscript>5</subscript></entry>
2515 <entry>u<subscript>4</subscript></entry>
2516 <entry>u<subscript>3</subscript></entry>
2517 <entry>u<subscript>2</subscript></entry>
2518 <entry>u<subscript>1</subscript></entry>
2519 <entry>u<subscript>0</subscript></entry>
2520 </row>
2521 </tbody>
2522 </tgroup>
2523 </table>
2524 </section>
2525
2526 <section>
2527 <title>JPEG Compressed Formats</title>
2528
2529 <para>Those data formats consist of an ordered sequence of 8-bit bytes
2530 obtained from JPEG compression process. Additionally to the
2531 <constant>_JPEG</constant> prefix the format code is made of
2532 the following information.
2533 <itemizedlist>
2534 <listitem><para>The number of bus samples per entropy encoded byte.</para></listitem>
2535 <listitem><para>The bus width.</para></listitem>
2536 </itemizedlist>
2537 </para>
2538
2539 <para>For instance, for a JPEG baseline process and an 8-bit bus width
2540 the format will be named <constant>V4L2_MBUS_FMT_JPEG_1X8</constant>.
2541 </para>
2542
2543 <para>The following table lists existing JPEG compressed formats.</para>
2544
2545 <table pgwide="0" frame="none" id="v4l2-mbus-pixelcode-jpeg">
2546 <title>JPEG Formats</title>
2547 <tgroup cols="3">
2548 <colspec colname="id" align="left" />
2549 <colspec colname="code" align="left"/>
2550 <colspec colname="remarks" align="left"/>
2551 <thead>
2552 <row>
2553 <entry>Identifier</entry>
2554 <entry>Code</entry>
2555 <entry>Remarks</entry>
2556 </row>
2557 </thead>
2558 <tbody valign="top">
2559 <row id="V4L2-MBUS-FMT-JPEG-1X8">
2560 <entry>V4L2_MBUS_FMT_JPEG_1X8</entry>
2561 <entry>0x4001</entry>
2562 <entry>Besides of its usage for the parallel bus this format is
2563 recommended for transmission of JPEG data over MIPI CSI bus
2564 using the User Defined 8-bit Data types.
2565 </entry>
2566 </row>
2567 </tbody>
2568 </tgroup>
2569 </table>
2570 </section>
2571 </section>
2572</section>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
new file mode 100644
index 000000000000..a7fd76d0dac1
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -0,0 +1,539 @@
1 <partinfo>
2 <authorgroup>
3 <author>
4 <firstname>Michael</firstname>
5 <surname>Schimek</surname>
6 <othername role="mi">H</othername>
7 <affiliation>
8 <address>
9 <email>mschimek@gmx.at</email>
10 </address>
11 </affiliation>
12 </author>
13
14 <author>
15 <firstname>Bill</firstname>
16 <surname>Dirks</surname>
17 <!-- Commented until Bill opts in to be spammed.
18 <affiliation>
19 <address>
20 <email>bill@thedirks.org</email>
21 </address>
22 </affiliation> -->
23 <contrib>Original author of the V4L2 API and
24documentation.</contrib>
25 </author>
26
27 <author>
28 <firstname>Hans</firstname>
29 <surname>Verkuil</surname>
30 <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
31the extended control ioctls and major parts of the sliced VBI
32API.</contrib>
33 <affiliation>
34 <address>
35 <email>hverkuil@xs4all.nl</email>
36 </address>
37 </affiliation>
38 </author>
39
40 <author>
41 <firstname>Martin</firstname>
42 <surname>Rubli</surname>
43 <!--
44 <affiliation>
45 <address>
46 <email>martin_rubli@logitech.com</email>
47 </address>
48 </affiliation> -->
49 <contrib>Designed and documented the VIDIOC_ENUM_FRAMESIZES
50and VIDIOC_ENUM_FRAMEINTERVALS ioctls.</contrib>
51 </author>
52
53 <author>
54 <firstname>Andy</firstname>
55 <surname>Walls</surname>
56 <contrib>Documented the fielded V4L2_MPEG_STREAM_VBI_FMT_IVTV
57MPEG stream embedded, sliced VBI data format in this specification.
58</contrib>
59 <affiliation>
60 <address>
61 <email>awalls@md.metrocast.net</email>
62 </address>
63 </affiliation>
64 </author>
65
66 <author>
67 <firstname>Mauro</firstname>
68 <surname>Carvalho Chehab</surname>
69 <contrib>Documented libv4l, designed and added v4l2grab example,
70Remote Controller chapter.</contrib>
71 <affiliation>
72 <address>
73 <email>mchehab@redhat.com</email>
74 </address>
75 </affiliation>
76 </author>
77
78 <author>
79 <firstname>Muralidharan</firstname>
80 <surname>Karicheri</surname>
81 <contrib>Documented the Digital Video timings API.</contrib>
82 <affiliation>
83 <address>
84 <email>m-karicheri2@ti.com</email>
85 </address>
86 </affiliation>
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>
99 </authorgroup>
100
101 <copyright>
102 <year>1999</year>
103 <year>2000</year>
104 <year>2001</year>
105 <year>2002</year>
106 <year>2003</year>
107 <year>2004</year>
108 <year>2005</year>
109 <year>2006</year>
110 <year>2007</year>
111 <year>2008</year>
112 <year>2009</year>
113 <year>2010</year>
114 <year>2011</year>
115 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
116Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
117 Pawel Osciak</holder>
118 </copyright>
119 <legalnotice>
120 <para>Except when explicitly stated as GPL, programming examples within
121 this part can be used and distributed without restrictions.</para>
122 </legalnotice>
123 <revhistory>
124 <!-- Put document revisions here, newest first. -->
125 <!-- API revisions (changes and additions of defines, enums,
126structs, ioctls) must be noted in more detail in the history chapter
127(compat.xml), along with the possible impact on existing drivers and
128applications. -->
129
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>
138 <revnumber>2.6.37</revnumber>
139 <date>2010-08-06</date>
140 <authorinitials>hv</authorinitials>
141 <revremark>Removed obsolete vtx (videotext) API.</revremark>
142 </revision>
143
144 <revision>
145 <revnumber>2.6.33</revnumber>
146 <date>2009-12-03</date>
147 <authorinitials>mk</authorinitials>
148 <revremark>Added documentation for the Digital Video timings API.</revremark>
149 </revision>
150
151 <revision>
152 <revnumber>2.6.32</revnumber>
153 <date>2009-08-31</date>
154 <authorinitials>mcc</authorinitials>
155 <revremark>Now, revisions will match the kernel version where
156the V4L2 API changes will be used by the Linux Kernel.
157Also added Remote Controller chapter.</revremark>
158 </revision>
159
160 <revision>
161 <revnumber>0.29</revnumber>
162 <date>2009-08-26</date>
163 <authorinitials>ev</authorinitials>
164 <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
165 </revision>
166
167 <revision>
168 <revnumber>0.28</revnumber>
169 <date>2009-08-26</date>
170 <authorinitials>gl</authorinitials>
171 <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
172 </revision>
173
174 <revision>
175 <revnumber>0.27</revnumber>
176 <date>2009-08-15</date>
177 <authorinitials>mcc</authorinitials>
178 <revremark>Added libv4l and Remote Controller documentation;
179added v4l2grab and keytable application examples.</revremark>
180 </revision>
181
182 <revision>
183 <revnumber>0.26</revnumber>
184 <date>2009-07-23</date>
185 <authorinitials>hv</authorinitials>
186 <revremark>Finalized the RDS capture API. Added modulator and RDS encoder
187capabilities. Added support for string controls.</revremark>
188 </revision>
189
190 <revision>
191 <revnumber>0.25</revnumber>
192 <date>2009-01-18</date>
193 <authorinitials>hv</authorinitials>
194 <revremark>Added pixel formats VYUY, NV16 and NV61, and changed
195the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
196Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
197V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark>
198 </revision>
199
200 <revision>
201 <revnumber>0.24</revnumber>
202 <date>2008-03-04</date>
203 <authorinitials>mhs</authorinitials>
204 <revremark>Added pixel formats Y16 and SBGGR16, new controls
205and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
206 </revision>
207
208 <revision>
209 <revnumber>0.23</revnumber>
210 <date>2007-08-30</date>
211 <authorinitials>mhs</authorinitials>
212 <revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
213Clarified the byte order of packed pixel formats.</revremark>
214 </revision>
215
216 <revision>
217 <revnumber>0.22</revnumber>
218 <date>2007-08-29</date>
219 <authorinitials>mhs</authorinitials>
220 <revremark>Added the Video Output Overlay interface, new MPEG
221controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
222VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
223VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
224Clarifications in the cropping chapter, about RGB pixel formats, the
225mmap(), poll(), select(), read() and write() functions. Typographical
226fixes.</revremark>
227 </revision>
228
229 <revision>
230 <revnumber>0.21</revnumber>
231 <date>2006-12-19</date>
232 <authorinitials>mhs</authorinitials>
233 <revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
234 </revision>
235
236 <revision>
237 <revnumber>0.20</revnumber>
238 <date>2006-11-24</date>
239 <authorinitials>mhs</authorinitials>
240 <revremark>Clarified the purpose of the audioset field in
241struct v4l2_input and v4l2_output.</revremark>
242 </revision>
243
244 <revision>
245 <revnumber>0.19</revnumber>
246 <date>2006-10-19</date>
247 <authorinitials>mhs</authorinitials>
248 <revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
249 </revision>
250
251 <revision>
252 <revnumber>0.18</revnumber>
253 <date>2006-10-18</date>
254 <authorinitials>mhs</authorinitials>
255 <revremark>Added the description of extended controls by Hans
256Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
257 </revision>
258
259 <revision>
260 <revnumber>0.17</revnumber>
261 <date>2006-10-12</date>
262 <authorinitials>mhs</authorinitials>
263 <revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
264 </revision>
265
266 <revision>
267 <revnumber>0.16</revnumber>
268 <date>2006-10-08</date>
269 <authorinitials>mhs</authorinitials>
270 <revremark>VIDIOC_ENUM_FRAMESIZES and
271VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
272 </revision>
273
274 <revision>
275 <revnumber>0.15</revnumber>
276 <date>2006-09-23</date>
277 <authorinitials>mhs</authorinitials>
278 <revremark>Cleaned up the bibliography, added BT.653 and
279BT.1119. capture.c/start_capturing() for user pointer I/O did not
280initialize the buffer index. Documented the V4L MPEG and MJPEG
281VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
282formats. See the history chapter for API changes.</revremark>
283 </revision>
284
285 <revision>
286 <revnumber>0.14</revnumber>
287 <date>2006-09-14</date>
288 <authorinitials>mr</authorinitials>
289 <revremark>Added VIDIOC_ENUM_FRAMESIZES and
290VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
291digital devices.</revremark>
292 </revision>
293
294 <revision>
295 <revnumber>0.13</revnumber>
296 <date>2006-04-07</date>
297 <authorinitials>mhs</authorinitials>
298 <revremark>Corrected the description of struct v4l2_window
299clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
300defines.</revremark>
301 </revision>
302
303 <revision>
304 <revnumber>0.12</revnumber>
305 <date>2006-02-03</date>
306 <authorinitials>mhs</authorinitials>
307 <revremark>Corrected the description of struct
308v4l2_captureparm and v4l2_outputparm.</revremark>
309 </revision>
310
311 <revision>
312 <revnumber>0.11</revnumber>
313 <date>2006-01-27</date>
314 <authorinitials>mhs</authorinitials>
315 <revremark>Improved the description of struct
316v4l2_tuner.</revremark>
317 </revision>
318
319 <revision>
320 <revnumber>0.10</revnumber>
321 <date>2006-01-10</date>
322 <authorinitials>mhs</authorinitials>
323 <revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
324clarifications.</revremark>
325 </revision>
326
327 <revision>
328 <revnumber>0.9</revnumber>
329 <date>2005-11-27</date>
330 <authorinitials>mhs</authorinitials>
331 <revremark>Improved the 525 line numbering diagram. Hans
332Verkuil and I rewrote the sliced VBI section. He also contributed a
333VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
334selection example. Various updates.</revremark>
335 </revision>
336
337 <revision>
338 <revnumber>0.8</revnumber>
339 <date>2004-10-04</date>
340 <authorinitials>mhs</authorinitials>
341 <revremark>Somehow a piece of junk slipped into the capture
342example, removed.</revremark>
343 </revision>
344
345 <revision>
346 <revnumber>0.7</revnumber>
347 <date>2004-09-19</date>
348 <authorinitials>mhs</authorinitials>
349 <revremark>Fixed video standard selection, control
350enumeration, downscaling and aspect example. Added read and user
351pointer i/o to video capture example.</revremark>
352 </revision>
353
354 <revision>
355 <revnumber>0.6</revnumber>
356 <date>2004-08-01</date>
357 <authorinitials>mhs</authorinitials>
358 <revremark>v4l2_buffer changes, added video capture example,
359various corrections.</revremark>
360 </revision>
361
362 <revision>
363 <revnumber>0.5</revnumber>
364 <date>2003-11-05</date>
365 <authorinitials>mhs</authorinitials>
366 <revremark>Pixel format erratum.</revremark>
367 </revision>
368
369 <revision>
370 <revnumber>0.4</revnumber>
371 <date>2003-09-17</date>
372 <authorinitials>mhs</authorinitials>
373 <revremark>Corrected source and Makefile to generate a PDF.
374SGML fixes. Added latest API changes. Closed gaps in the history
375chapter.</revremark>
376 </revision>
377
378 <revision>
379 <revnumber>0.3</revnumber>
380 <date>2003-02-05</date>
381 <authorinitials>mhs</authorinitials>
382 <revremark>Another draft, more corrections.</revremark>
383 </revision>
384
385 <revision>
386 <revnumber>0.2</revnumber>
387 <date>2003-01-15</date>
388 <authorinitials>mhs</authorinitials>
389 <revremark>Second draft, with corrections pointed out by Gerd
390Knorr.</revremark>
391 </revision>
392
393 <revision>
394 <revnumber>0.1</revnumber>
395 <date>2002-12-01</date>
396 <authorinitials>mhs</authorinitials>
397 <revremark>First draft, based on documentation by Bill Dirks
398and discussions on the V4L mailing list.</revremark>
399 </revision>
400 </revhistory>
401</partinfo>
402
403<title>Video for Linux Two API Specification</title>
404 <subtitle>Revision 2.6.39</subtitle>
405
406 <chapter id="common">
407 &sub-common;
408 </chapter>
409
410 <chapter id="pixfmt">
411 &sub-pixfmt;
412 </chapter>
413
414 <chapter id="io">
415 &sub-io;
416 </chapter>
417
418 <chapter id="devices">
419 <title>Interfaces</title>
420
421 <section id="capture"> &sub-dev-capture; </section>
422 <section id="overlay"> &sub-dev-overlay; </section>
423 <section id="output"> &sub-dev-output; </section>
424 <section id="osd"> &sub-dev-osd; </section>
425 <section id="codec"> &sub-dev-codec; </section>
426 <section id="effect"> &sub-dev-effect; </section>
427 <section id="raw-vbi"> &sub-dev-raw-vbi; </section>
428 <section id="sliced"> &sub-dev-sliced-vbi; </section>
429 <section id="ttx"> &sub-dev-teletext; </section>
430 <section id="radio"> &sub-dev-radio; </section>
431 <section id="rds"> &sub-dev-rds; </section>
432 <section id="event"> &sub-dev-event; </section>
433 <section id="subdev"> &sub-dev-subdev; </section>
434 </chapter>
435
436 <chapter id="driver">
437 &sub-driver;
438 </chapter>
439
440 <chapter id="libv4l">
441 &sub-libv4l;
442 </chapter>
443
444 <chapter id="compat">
445 &sub-compat;
446 </chapter>
447
448 <appendix id="user-func">
449 <title>Function Reference</title>
450
451 <!-- Keep this alphabetically sorted. -->
452
453 &sub-close;
454 &sub-ioctl;
455 <!-- All ioctls go here. -->
456 &sub-cropcap;
457 &sub-dbg-g-chip-ident;
458 &sub-dbg-g-register;
459 &sub-dqevent;
460 &sub-encoder-cmd;
461 &sub-enumaudio;
462 &sub-enumaudioout;
463 &sub-enum-dv-presets;
464 &sub-enum-fmt;
465 &sub-enum-framesizes;
466 &sub-enum-frameintervals;
467 &sub-enuminput;
468 &sub-enumoutput;
469 &sub-enumstd;
470 &sub-g-audio;
471 &sub-g-audioout;
472 &sub-g-crop;
473 &sub-g-ctrl;
474 &sub-g-dv-preset;
475 &sub-g-dv-timings;
476 &sub-g-enc-index;
477 &sub-g-ext-ctrls;
478 &sub-g-fbuf;
479 &sub-g-fmt;
480 &sub-g-frequency;
481 &sub-g-input;
482 &sub-g-jpegcomp;
483 &sub-g-modulator;
484 &sub-g-output;
485 &sub-g-parm;
486 &sub-g-priority;
487 &sub-g-sliced-vbi-cap;
488 &sub-g-std;
489 &sub-g-tuner;
490 &sub-log-status;
491 &sub-overlay;
492 &sub-qbuf;
493 &sub-querybuf;
494 &sub-querycap;
495 &sub-queryctrl;
496 &sub-query-dv-preset;
497 &sub-querystd;
498 &sub-reqbufs;
499 &sub-s-hw-freq-seek;
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;
507 &sub-subscribe-event;
508 <!-- End of ioctls. -->
509 &sub-mmap;
510 &sub-munmap;
511 &sub-open;
512 &sub-poll;
513 &sub-read;
514 &sub-select;
515 &sub-write;
516 </appendix>
517
518 <appendix id="videodev">
519 <title>Video For Linux Two Header File</title>
520 &sub-videodev2-h;
521 </appendix>
522
523 <appendix id="capture-example">
524 <title>Video Capture Example</title>
525 &sub-capture-c;
526 </appendix>
527
528 <appendix id="v4l2grab-example">
529 <title>Video Grabber example using libv4l</title>
530 <para>This program demonstrates how to grab V4L2 images in ppm format by
531using libv4l handlers. The advantage is that this grabber can potentially work
532with any V4L2 driver.</para>
533 &sub-v4l2grab-c;
534 </appendix>
535
536 &sub-media-indices;
537
538 &sub-biblio;
539
diff --git a/Documentation/DocBook/media/v4l/v4l2grab.c.xml b/Documentation/DocBook/media/v4l/v4l2grab.c.xml
new file mode 100644
index 000000000000..bed12e40be27
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/v4l2grab.c.xml
@@ -0,0 +1,164 @@
1<programlisting>
2/* V4L2 video picture grabber
3 Copyright (C) 2009 Mauro Carvalho Chehab &lt;mchehab@infradead.org&gt;
4
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation version 2 of the License.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13 */
14
15#include &lt;stdio.h&gt;
16#include &lt;stdlib.h&gt;
17#include &lt;string.h&gt;
18#include &lt;fcntl.h&gt;
19#include &lt;errno.h&gt;
20#include &lt;sys/ioctl.h&gt;
21#include &lt;sys/types.h&gt;
22#include &lt;sys/time.h&gt;
23#include &lt;sys/mman.h&gt;
24#include &lt;linux/videodev2.h&gt;
25#include "../libv4l/include/libv4l2.h"
26
27#define CLEAR(x) memset(&amp;(x), 0, sizeof(x))
28
29struct buffer {
30 void *start;
31 size_t length;
32};
33
34static void xioctl(int fh, int request, void *arg)
35{
36 int r;
37
38 do {
39 r = v4l2_ioctl(fh, request, arg);
40 } while (r == -1 &amp;&amp; ((errno == EINTR) || (errno == EAGAIN)));
41
42 if (r == -1) {
43 fprintf(stderr, "error %d, %s\n", errno, strerror(errno));
44 exit(EXIT_FAILURE);
45 }
46}
47
48int main(int argc, char **argv)
49{
50 struct <link linkend="v4l2-format">v4l2_format</link> fmt;
51 struct <link linkend="v4l2-buffer">v4l2_buffer</link> buf;
52 struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> req;
53 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
54 fd_set fds;
55 struct timeval tv;
56 int r, fd = -1;
57 unsigned int i, n_buffers;
58 char *dev_name = "/dev/video0";
59 char out_name[256];
60 FILE *fout;
61 struct buffer *buffers;
62
63 fd = v4l2_open(dev_name, O_RDWR | O_NONBLOCK, 0);
64 if (fd &lt; 0) {
65 perror("Cannot open device");
66 exit(EXIT_FAILURE);
67 }
68
69 CLEAR(fmt);
70 fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
71 fmt.fmt.pix.width = 640;
72 fmt.fmt.pix.height = 480;
73 fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_RGB24;
74 fmt.fmt.pix.field = V4L2_FIELD_INTERLACED;
75 xioctl(fd, VIDIOC_S_FMT, &amp;fmt);
76 if (fmt.fmt.pix.pixelformat != V4L2_PIX_FMT_RGB24) {
77 printf("Libv4l didn't accept RGB24 format. Can't proceed.\n");
78 exit(EXIT_FAILURE);
79 }
80 if ((fmt.fmt.pix.width != 640) || (fmt.fmt.pix.height != 480))
81 printf("Warning: driver is sending image at %dx%d\n",
82 fmt.fmt.pix.width, fmt.fmt.pix.height);
83
84 CLEAR(req);
85 req.count = 2;
86 req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
87 req.memory = V4L2_MEMORY_MMAP;
88 xioctl(fd, VIDIOC_REQBUFS, &amp;req);
89
90 buffers = calloc(req.count, sizeof(*buffers));
91 for (n_buffers = 0; n_buffers &lt; req.count; ++n_buffers) {
92 CLEAR(buf);
93
94 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
95 buf.memory = V4L2_MEMORY_MMAP;
96 buf.index = n_buffers;
97
98 xioctl(fd, VIDIOC_QUERYBUF, &amp;buf);
99
100 buffers[n_buffers].length = buf.length;
101 buffers[n_buffers].start = v4l2_mmap(NULL, buf.length,
102 PROT_READ | PROT_WRITE, MAP_SHARED,
103 fd, buf.m.offset);
104
105 if (MAP_FAILED == buffers[n_buffers].start) {
106 perror("mmap");
107 exit(EXIT_FAILURE);
108 }
109 }
110
111 for (i = 0; i &lt; n_buffers; ++i) {
112 CLEAR(buf);
113 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
114 buf.memory = V4L2_MEMORY_MMAP;
115 buf.index = i;
116 xioctl(fd, VIDIOC_QBUF, &amp;buf);
117 }
118 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
119
120 xioctl(fd, VIDIOC_STREAMON, &amp;type);
121 for (i = 0; i &lt; 20; i++) {
122 do {
123 FD_ZERO(&amp;fds);
124 FD_SET(fd, &amp;fds);
125
126 /* Timeout. */
127 tv.tv_sec = 2;
128 tv.tv_usec = 0;
129
130 r = select(fd + 1, &amp;fds, NULL, NULL, &amp;tv);
131 } while ((r == -1 &amp;&amp; (errno = EINTR)));
132 if (r == -1) {
133 perror("select");
134 return errno;
135 }
136
137 CLEAR(buf);
138 buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
139 buf.memory = V4L2_MEMORY_MMAP;
140 xioctl(fd, VIDIOC_DQBUF, &amp;buf);
141
142 sprintf(out_name, "out%03d.ppm", i);
143 fout = fopen(out_name, "w");
144 if (!fout) {
145 perror("Cannot open image");
146 exit(EXIT_FAILURE);
147 }
148 fprintf(fout, "P6\n%d %d 255\n",
149 fmt.fmt.pix.width, fmt.fmt.pix.height);
150 fwrite(buffers[buf.index].start, buf.bytesused, 1, fout);
151 fclose(fout);
152
153 xioctl(fd, VIDIOC_QBUF, &amp;buf);
154 }
155
156 type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
157 xioctl(fd, VIDIOC_STREAMOFF, &amp;type);
158 for (i = 0; i &lt; n_buffers; ++i)
159 v4l2_munmap(buffers[i].start, buffers[i].length);
160 v4l2_close(fd);
161
162 return 0;
163}
164</programlisting>
diff --git a/Documentation/DocBook/media/v4l/vbi_525.gif b/Documentation/DocBook/media/v4l/vbi_525.gif
new file mode 100644
index 000000000000..5580b690d504
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vbi_525.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vbi_525.pdf b/Documentation/DocBook/media/v4l/vbi_525.pdf
new file mode 100644
index 000000000000..9e72c25b208d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vbi_525.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vbi_625.gif b/Documentation/DocBook/media/v4l/vbi_625.gif
new file mode 100644
index 000000000000..34e3251983c4
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vbi_625.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vbi_625.pdf b/Documentation/DocBook/media/v4l/vbi_625.pdf
new file mode 100644
index 000000000000..765235e33a4d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vbi_625.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vbi_hsync.gif b/Documentation/DocBook/media/v4l/vbi_hsync.gif
new file mode 100644
index 000000000000..b02434d3b356
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vbi_hsync.gif
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vbi_hsync.pdf b/Documentation/DocBook/media/v4l/vbi_hsync.pdf
new file mode 100644
index 000000000000..200b668189bf
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vbi_hsync.pdf
Binary files differ
diff --git a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml
new file mode 100644
index 000000000000..816e90e283c5
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml
@@ -0,0 +1,174 @@
1<refentry id="vidioc-cropcap">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_CROPCAP</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_CROPCAP</refname>
9 <refpurpose>Information about the video cropping and scaling abilities</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_cropcap
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_CROPCAP</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>Applications use this function to query the cropping
53limits, the pixel aspect of images and to calculate scale factors.
54They set the <structfield>type</structfield> field of a v4l2_cropcap
55structure to the respective buffer (stream) type and call the
56<constant>VIDIOC_CROPCAP</constant> ioctl with a pointer to this
57structure. Drivers fill the rest of the structure. The results are
58constant except when switching the video standard. Remember this
59switch can occur implicit when switching the video input or
60output.</para>
61
62 <table pgwide="1" frame="none" id="v4l2-cropcap">
63 <title>struct <structname>v4l2_cropcap</structname></title>
64 <tgroup cols="3">
65 &cs-str;
66 <tbody valign="top">
67 <row>
68 <entry>&v4l2-buf-type;</entry>
69 <entry><structfield>type</structfield></entry>
70 <entry>Type of the data stream, set by the application.
71Only these types are valid here:
72<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
73<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
74<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
75defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
76and higher.</entry>
77 </row>
78 <row>
79 <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
80 <entry><structfield>bounds</structfield></entry>
81 <entry>Defines the window within capturing or output is
82possible, this may exclude for example the horizontal and vertical
83blanking areas. The cropping rectangle cannot exceed these limits.
84Width and height are defined in pixels, the driver writer is free to
85choose origin and units of the coordinate system in the analog
86domain.</entry>
87 </row>
88 <row>
89 <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry>
90 <entry><structfield>defrect</structfield></entry>
91 <entry>Default cropping rectangle, it shall cover the
92"whole picture". Assuming pixel aspect 1/1 this could be for example a
93640&nbsp;&times;&nbsp;480 rectangle for NTSC, a
94768&nbsp;&times;&nbsp;576 rectangle for PAL and SECAM centered over
95the active picture area. The same co-ordinate system as for
96 <structfield>bounds</structfield> is used.</entry>
97 </row>
98 <row>
99 <entry>&v4l2-fract;</entry>
100 <entry><structfield>pixelaspect</structfield></entry>
101 <entry><para>This is the pixel aspect (y / x) when no
102scaling is applied, the ratio of the actual sampling
103frequency and the frequency required to get square
104pixels.</para><para>When cropping coordinates refer to square pixels,
105the driver sets <structfield>pixelaspect</structfield> to 1/1. Other
106common values are 54/59 for PAL and SECAM, 11/10 for NTSC sampled
107according to [<xref linkend="itu601" />].</para></entry>
108 </row>
109 </tbody>
110 </tgroup>
111 </table>
112
113 <!-- NB this table is duplicated in the overlay chapter. -->
114
115 <table pgwide="1" frame="none" id="v4l2-rect-crop">
116 <title>struct <structname>v4l2_rect</structname></title>
117 <tgroup cols="3">
118 &cs-str;
119 <tbody valign="top">
120 <row>
121 <entry>__s32</entry>
122 <entry><structfield>left</structfield></entry>
123 <entry>Horizontal offset of the top, left corner of the
124rectangle, in pixels.</entry>
125 </row>
126 <row>
127 <entry>__s32</entry>
128 <entry><structfield>top</structfield></entry>
129 <entry>Vertical offset of the top, left corner of the
130rectangle, in pixels.</entry>
131 </row>
132 <row>
133 <entry>__s32</entry>
134 <entry><structfield>width</structfield></entry>
135 <entry>Width of the rectangle, in pixels.</entry>
136 </row>
137 <row>
138 <entry>__s32</entry>
139 <entry><structfield>height</structfield></entry>
140 <entry>Height of the rectangle, in pixels. Width
141and height cannot be negative, the fields are signed for
142hysterical reasons. <!-- video4linux-list@redhat.com
143on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5" -->
144</entry>
145 </row>
146 </tbody>
147 </tgroup>
148 </table>
149 </refsect1>
150
151 <refsect1>
152 &return-value;
153
154 <variablelist>
155 <varlistentry>
156 <term><errorcode>EINVAL</errorcode></term>
157 <listitem>
158 <para>The &v4l2-cropcap; <structfield>type</structfield> is
159invalid or the ioctl is not supported. This is not permitted for
160video capture, output and overlay devices, which must support
161<constant>VIDIOC_CROPCAP</constant>.</para>
162 </listitem>
163 </varlistentry>
164 </variablelist>
165 </refsect1>
166</refentry>
167
168<!--
169Local Variables:
170mode: sgml
171sgml-parent-document: "v4l2.sgml"
172indent-tabs-mode: nil
173End:
174-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml
new file mode 100644
index 000000000000..4a09e203af0f
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-chip-ident.xml
@@ -0,0 +1,275 @@
1<refentry id="vidioc-dbg-g-chip-ident">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_DBG_G_CHIP_IDENT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_DBG_G_CHIP_IDENT</refname>
9 <refpurpose>Identify the chips on a TV card</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_dbg_chip_ident
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_DBG_G_CHIP_IDENT</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
55 <para>This is an <link
56linkend="experimental">experimental</link> interface and may change in
57the future.</para>
58 </note>
59
60 <para>For driver debugging purposes this ioctl allows test
61applications to query the driver about the chips present on the TV
62card. Regular applications must not use it. When you found a chip
63specific bug, please contact the linux-media mailing list (&v4l-ml;)
64so it can be fixed.</para>
65
66 <para>To query the driver applications must initialize the
67<structfield>match.type</structfield> and
68<structfield>match.addr</structfield> or <structfield>match.name</structfield>
69fields of a &v4l2-dbg-chip-ident;
70and call <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> with a pointer to
71this structure. On success the driver stores information about the
72selected chip in the <structfield>ident</structfield> and
73<structfield>revision</structfield> fields. On failure the structure
74remains unchanged.</para>
75
76 <para>When <structfield>match.type</structfield> is
77<constant>V4L2_CHIP_MATCH_HOST</constant>,
78<structfield>match.addr</structfield> selects the nth non-&i2c; chip
79on the TV card. You can enumerate all chips by starting at zero and
80incrementing <structfield>match.addr</structfield> by one until
81<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.
82The number zero always selects the host chip, &eg; the chip connected
83to the PCI or USB bus.</para>
84
85 <para>When <structfield>match.type</structfield> is
86<constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>,
87<structfield>match.name</structfield> contains the I2C driver name.
88For instance
89<constant>"saa7127"</constant> will match any chip
90supported by the saa7127 driver, regardless of its &i2c; bus address.
91When multiple chips supported by the same driver are present, the
92ioctl will return <constant>V4L2_IDENT_AMBIGUOUS</constant> in the
93<structfield>ident</structfield> field.</para>
94
95 <para>When <structfield>match.type</structfield> is
96<constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>,
97<structfield>match.addr</structfield> selects a chip by its 7 bit
98&i2c; bus address.</para>
99
100 <para>When <structfield>match.type</structfield> is
101<constant>V4L2_CHIP_MATCH_AC97</constant>,
102<structfield>match.addr</structfield> selects the nth AC97 chip
103on the TV card. You can enumerate all chips by starting at zero and
104incrementing <structfield>match.addr</structfield> by one until
105<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> fails with an &EINVAL;.</para>
106
107 <para>On success, the <structfield>ident</structfield> field will
108contain a chip ID from the Linux
109<filename>media/v4l2-chip-ident.h</filename> header file, and the
110<structfield>revision</structfield> field will contain a driver
111specific value, or zero if no particular revision is associated with
112this chip.</para>
113
114 <para>When the driver could not identify the selected chip,
115<structfield>ident</structfield> will contain
116<constant>V4L2_IDENT_UNKNOWN</constant>. When no chip matched
117the ioctl will succeed but the
118<structfield>ident</structfield> field will contain
119<constant>V4L2_IDENT_NONE</constant>. If multiple chips matched,
120<structfield>ident</structfield> will contain
121<constant>V4L2_IDENT_AMBIGUOUS</constant>. In all these cases the
122<structfield>revision</structfield> field remains unchanged.</para>
123
124 <para>This ioctl is optional, not all drivers may support it. It
125was introduced in Linux 2.6.21, but the API was changed to the
126one described here in 2.6.29.</para>
127
128 <para>We recommended the <application>v4l2-dbg</application>
129utility over calling this ioctl directly. It is available from the
130LinuxTV v4l-dvb repository; see <ulink
131url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
132access instructions.</para>
133
134 <!-- Note for convenience vidioc-dbg-g-register.sgml
135 contains a duplicate of this table. -->
136 <table pgwide="1" frame="none" id="ident-v4l2-dbg-match">
137 <title>struct <structname>v4l2_dbg_match</structname></title>
138 <tgroup cols="4">
139 &cs-ustr;
140 <tbody valign="top">
141 <row>
142 <entry>__u32</entry>
143 <entry><structfield>type</structfield></entry>
144 <entry>See <xref linkend="ident-chip-match-types" /> for a list of
145possible types.</entry>
146 </row>
147 <row>
148 <entry>union</entry>
149 <entry>(anonymous)</entry>
150 </row>
151 <row>
152 <entry></entry>
153 <entry>__u32</entry>
154 <entry><structfield>addr</structfield></entry>
155 <entry>Match a chip by this number, interpreted according
156to the <structfield>type</structfield> field.</entry>
157 </row>
158 <row>
159 <entry></entry>
160 <entry>char</entry>
161 <entry><structfield>name[32]</structfield></entry>
162 <entry>Match a chip by this name, interpreted according
163to the <structfield>type</structfield> field.</entry>
164 </row>
165 </tbody>
166 </tgroup>
167 </table>
168
169 <table pgwide="1" frame="none" id="v4l2-dbg-chip-ident">
170 <title>struct <structname>v4l2_dbg_chip_ident</structname></title>
171 <tgroup cols="3">
172 &cs-str;
173 <tbody valign="top">
174 <row>
175 <entry>struct v4l2_dbg_match</entry>
176 <entry><structfield>match</structfield></entry>
177 <entry>How to match the chip, see <xref linkend="ident-v4l2-dbg-match" />.</entry>
178 </row>
179 <row>
180 <entry>__u32</entry>
181 <entry><structfield>ident</structfield></entry>
182 <entry>A chip identifier as defined in the Linux
183<filename>media/v4l2-chip-ident.h</filename> header file, or one of
184the values from <xref linkend="chip-ids" />.</entry>
185 </row>
186 <row>
187 <entry>__u32</entry>
188 <entry><structfield>revision</structfield></entry>
189 <entry>A chip revision, chip and driver specific.</entry>
190 </row>
191 </tbody>
192 </tgroup>
193 </table>
194
195 <!-- Note for convenience vidioc-dbg-g-register.sgml
196 contains a duplicate of this table. -->
197 <table pgwide="1" frame="none" id="ident-chip-match-types">
198 <title>Chip Match Types</title>
199 <tgroup cols="3">
200 &cs-def;
201 <tbody valign="top">
202 <row>
203 <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry>
204 <entry>0</entry>
205 <entry>Match the nth chip on the card, zero for the
206 host chip. Does not match &i2c; chips.</entry>
207 </row>
208 <row>
209 <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
210 <entry>1</entry>
211 <entry>Match an &i2c; chip by its driver name.</entry>
212 </row>
213 <row>
214 <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
215 <entry>2</entry>
216 <entry>Match a chip by its 7 bit &i2c; bus address.</entry>
217 </row>
218 <row>
219 <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
220 <entry>3</entry>
221 <entry>Match the nth anciliary AC97 chip.</entry>
222 </row>
223 </tbody>
224 </tgroup>
225 </table>
226
227 <!-- This is an anonymous enum in media/v4l2-chip-ident.h. -->
228 <table pgwide="1" frame="none" id="chip-ids">
229 <title>Chip Identifiers</title>
230 <tgroup cols="3">
231 &cs-def;
232 <tbody valign="top">
233 <row>
234 <entry><constant>V4L2_IDENT_NONE</constant></entry>
235 <entry>0</entry>
236 <entry>No chip matched.</entry>
237 </row>
238 <row>
239 <entry><constant>V4L2_IDENT_AMBIGUOUS</constant></entry>
240 <entry>1</entry>
241 <entry>Multiple chips matched.</entry>
242 </row>
243 <row>
244 <entry><constant>V4L2_IDENT_UNKNOWN</constant></entry>
245 <entry>2</entry>
246 <entry>A chip is present at this address, but the driver
247could not identify it.</entry>
248 </row>
249 </tbody>
250 </tgroup>
251 </table>
252 </refsect1>
253
254 <refsect1>
255 &return-value;
256
257 <variablelist>
258 <varlistentry>
259 <term><errorcode>EINVAL</errorcode></term>
260 <listitem>
261 <para>The driver does not support this ioctl, or the
262<structfield>match_type</structfield> is invalid.</para>
263 </listitem>
264 </varlistentry>
265 </variablelist>
266 </refsect1>
267</refentry>
268
269<!--
270Local Variables:
271mode: sgml
272sgml-parent-document: "v4l2.sgml"
273indent-tabs-mode: nil
274End:
275-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
new file mode 100644
index 000000000000..980c7f3e2fd6
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-dbg-g-register.xml
@@ -0,0 +1,275 @@
1<refentry id="vidioc-dbg-g-register">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_DBG_G_REGISTER</refname>
9 <refname>VIDIOC_DBG_S_REGISTER</refname>
10 <refpurpose>Read or write hardware registers</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_dbg_register *<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_dbg_register
28*<parameter>argp</parameter></paramdef>
29 </funcprototype>
30 </funcsynopsis>
31 </refsynopsisdiv>
32
33 <refsect1>
34 <title>Arguments</title>
35
36 <variablelist>
37 <varlistentry>
38 <term><parameter>fd</parameter></term>
39 <listitem>
40 <para>&fd;</para>
41 </listitem>
42 </varlistentry>
43 <varlistentry>
44 <term><parameter>request</parameter></term>
45 <listitem>
46 <para>VIDIOC_DBG_G_REGISTER, VIDIOC_DBG_S_REGISTER</para>
47 </listitem>
48 </varlistentry>
49 <varlistentry>
50 <term><parameter>argp</parameter></term>
51 <listitem>
52 <para></para>
53 </listitem>
54 </varlistentry>
55 </variablelist>
56 </refsect1>
57
58 <refsect1>
59 <title>Description</title>
60
61 <note>
62 <title>Experimental</title>
63
64 <para>This is an <link linkend="experimental">experimental</link>
65interface and may change in the future.</para>
66 </note>
67
68 <para>For driver debugging purposes these ioctls allow test
69applications to access hardware registers directly. Regular
70applications must not use them.</para>
71
72 <para>Since writing or even reading registers can jeopardize the
73system security, its stability and damage the hardware, both ioctls
74require superuser privileges. Additionally the Linux kernel must be
75compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant> option
76to enable these ioctls.</para>
77
78 <para>To write a register applications must initialize all fields
79of a &v4l2-dbg-register; and call
80<constant>VIDIOC_DBG_S_REGISTER</constant> with a pointer to this
81structure. The <structfield>match.type</structfield> and
82<structfield>match.addr</structfield> or <structfield>match.name</structfield>
83fields select a chip on the TV
84card, the <structfield>reg</structfield> field specifies a register
85number and the <structfield>val</structfield> field the value to be
86written into the register.</para>
87
88 <para>To read a register applications must initialize the
89<structfield>match.type</structfield>,
90<structfield>match.chip</structfield> or <structfield>match.name</structfield> and
91<structfield>reg</structfield> fields, and call
92<constant>VIDIOC_DBG_G_REGISTER</constant> with a pointer to this
93structure. On success the driver stores the register value in the
94<structfield>val</structfield> field. On failure the structure remains
95unchanged.</para>
96
97 <para>When <structfield>match.type</structfield> is
98<constant>V4L2_CHIP_MATCH_HOST</constant>,
99<structfield>match.addr</structfield> selects the nth non-&i2c; chip
100on the TV card. The number zero always selects the host chip, &eg; the
101chip connected to the PCI or USB bus. You can find out which chips are
102present with the &VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
103
104 <para>When <structfield>match.type</structfield> is
105<constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant>,
106<structfield>match.name</structfield> contains the I2C driver name.
107For instance
108<constant>"saa7127"</constant> will match any chip
109supported by the saa7127 driver, regardless of its &i2c; bus address.
110When multiple chips supported by the same driver are present, the
111effect of these ioctls is undefined. Again with the
112&VIDIOC-DBG-G-CHIP-IDENT; ioctl you can find out which &i2c; chips are
113present.</para>
114
115 <para>When <structfield>match.type</structfield> is
116<constant>V4L2_CHIP_MATCH_I2C_ADDR</constant>,
117<structfield>match.addr</structfield> selects a chip by its 7 bit &i2c;
118bus address.</para>
119
120 <para>When <structfield>match.type</structfield> is
121<constant>V4L2_CHIP_MATCH_AC97</constant>,
122<structfield>match.addr</structfield> selects the nth AC97 chip
123on the TV card.</para>
124
125 <note>
126 <title>Success not guaranteed</title>
127
128 <para>Due to a flaw in the Linux &i2c; bus driver these ioctls may
129return successfully without actually reading or writing a register. To
130catch the most likely failure we recommend a &VIDIOC-DBG-G-CHIP-IDENT;
131call confirming the presence of the selected &i2c; chip.</para>
132 </note>
133
134 <para>These ioctls are optional, not all drivers may support them.
135However when a driver supports these ioctls it must also support
136&VIDIOC-DBG-G-CHIP-IDENT;. Conversely it may support
137<constant>VIDIOC_DBG_G_CHIP_IDENT</constant> but not these ioctls.</para>
138
139 <para><constant>VIDIOC_DBG_G_REGISTER</constant> and
140<constant>VIDIOC_DBG_S_REGISTER</constant> were introduced in Linux
1412.6.21, but their API was changed to the one described here in kernel 2.6.29.</para>
142
143 <para>We recommended the <application>v4l2-dbg</application>
144utility over calling these ioctls directly. It is available from the
145LinuxTV v4l-dvb repository; see <ulink
146url="http://linuxtv.org/repo/">http://linuxtv.org/repo/</ulink> for
147access instructions.</para>
148
149 <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml
150 contains a duplicate of this table. -->
151 <table pgwide="1" frame="none" id="v4l2-dbg-match">
152 <title>struct <structname>v4l2_dbg_match</structname></title>
153 <tgroup cols="4">
154 &cs-ustr;
155 <tbody valign="top">
156 <row>
157 <entry>__u32</entry>
158 <entry><structfield>type</structfield></entry>
159 <entry>See <xref linkend="ident-chip-match-types" /> for a list of
160possible types.</entry>
161 </row>
162 <row>
163 <entry>union</entry>
164 <entry>(anonymous)</entry>
165 </row>
166 <row>
167 <entry></entry>
168 <entry>__u32</entry>
169 <entry><structfield>addr</structfield></entry>
170 <entry>Match a chip by this number, interpreted according
171to the <structfield>type</structfield> field.</entry>
172 </row>
173 <row>
174 <entry></entry>
175 <entry>char</entry>
176 <entry><structfield>name[32]</structfield></entry>
177 <entry>Match a chip by this name, interpreted according
178to the <structfield>type</structfield> field.</entry>
179 </row>
180 </tbody>
181 </tgroup>
182 </table>
183
184
185 <table pgwide="1" frame="none" id="v4l2-dbg-register">
186 <title>struct <structname>v4l2_dbg_register</structname></title>
187 <tgroup cols="4">
188 <colspec colname="c1" />
189 <colspec colname="c2" />
190 <colspec colname="c4" />
191 <tbody valign="top">
192 <row>
193 <entry>struct v4l2_dbg_match</entry>
194 <entry><structfield>match</structfield></entry>
195 <entry>How to match the chip, see <xref linkend="v4l2-dbg-match" />.</entry>
196 </row>
197 <row>
198 <entry>__u64</entry>
199 <entry><structfield>reg</structfield></entry>
200 <entry>A register number.</entry>
201 </row>
202 <row>
203 <entry>__u64</entry>
204 <entry><structfield>val</structfield></entry>
205 <entry>The value read from, or to be written into the
206register.</entry>
207 </row>
208 </tbody>
209 </tgroup>
210 </table>
211
212 <!-- Note for convenience vidioc-dbg-g-chip-ident.sgml
213 contains a duplicate of this table. -->
214 <table pgwide="1" frame="none" id="chip-match-types">
215 <title>Chip Match Types</title>
216 <tgroup cols="3">
217 &cs-def;
218 <tbody valign="top">
219 <row>
220 <entry><constant>V4L2_CHIP_MATCH_HOST</constant></entry>
221 <entry>0</entry>
222 <entry>Match the nth chip on the card, zero for the
223 host chip. Does not match &i2c; chips.</entry>
224 </row>
225 <row>
226 <entry><constant>V4L2_CHIP_MATCH_I2C_DRIVER</constant></entry>
227 <entry>1</entry>
228 <entry>Match an &i2c; chip by its driver name.</entry>
229 </row>
230 <row>
231 <entry><constant>V4L2_CHIP_MATCH_I2C_ADDR</constant></entry>
232 <entry>2</entry>
233 <entry>Match a chip by its 7 bit &i2c; bus address.</entry>
234 </row>
235 <row>
236 <entry><constant>V4L2_CHIP_MATCH_AC97</constant></entry>
237 <entry>3</entry>
238 <entry>Match the nth anciliary AC97 chip.</entry>
239 </row>
240 </tbody>
241 </tgroup>
242 </table>
243 </refsect1>
244
245 <refsect1>
246 &return-value;
247
248 <variablelist>
249 <varlistentry>
250 <term><errorcode>EINVAL</errorcode></term>
251 <listitem>
252 <para>The driver does not support this ioctl, or the kernel
253was not compiled with the <constant>CONFIG_VIDEO_ADV_DEBUG</constant>
254option, or the <structfield>match_type</structfield> is invalid, or the
255selected chip or register does not exist.</para>
256 </listitem>
257 </varlistentry>
258 <varlistentry>
259 <term><errorcode>EPERM</errorcode></term>
260 <listitem>
261 <para>Insufficient permissions. Root privileges are required
262to execute these ioctls.</para>
263 </listitem>
264 </varlistentry>
265 </variablelist>
266 </refsect1>
267</refentry>
268
269<!--
270Local Variables:
271mode: sgml
272sgml-parent-document: "v4l2.sgml"
273indent-tabs-mode: nil
274End:
275-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
new file mode 100644
index 000000000000..4e0a7cc30812
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -0,0 +1,131 @@
1<refentry id="vidioc-dqevent">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_DQEVENT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_DQEVENT</refname>
9 <refpurpose>Dequeue event</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_event
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_DQEVENT</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>Dequeue an event from a video device. No input is required
53 for this ioctl. All the fields of the &v4l2-event; structure are
54 filled by the driver. The file handle will also receive exceptions
55 which the application may get by e.g. using the select system
56 call.</para>
57
58 <table frame="none" pgwide="1" id="v4l2-event">
59 <title>struct <structname>v4l2_event</structname></title>
60 <tgroup cols="4">
61 &cs-str;
62 <tbody valign="top">
63 <row>
64 <entry>__u32</entry>
65 <entry><structfield>type</structfield></entry>
66 <entry></entry>
67 <entry>Type of the event.</entry>
68 </row>
69 <row>
70 <entry>union</entry>
71 <entry><structfield>u</structfield></entry>
72 <entry></entry>
73 <entry></entry>
74 </row>
75 <row>
76 <entry></entry>
77 <entry>&v4l2-event-vsync;</entry>
78 <entry><structfield>vsync</structfield></entry>
79 <entry>Event data for event V4L2_EVENT_VSYNC.
80 </entry>
81 </row>
82 <row>
83 <entry></entry>
84 <entry>__u8</entry>
85 <entry><structfield>data</structfield>[64]</entry>
86 <entry>Event data. Defined by the event type. The union
87 should be used to define easily accessible type for
88 events.</entry>
89 </row>
90 <row>
91 <entry>__u32</entry>
92 <entry><structfield>pending</structfield></entry>
93 <entry></entry>
94 <entry>Number of pending events excluding this one.</entry>
95 </row>
96 <row>
97 <entry>__u32</entry>
98 <entry><structfield>sequence</structfield></entry>
99 <entry></entry>
100 <entry>Event sequence number. The sequence number is
101 incremented for every subscribed event that takes place.
102 If sequence numbers are not contiguous it means that
103 events have been lost.
104 </entry>
105 </row>
106 <row>
107 <entry>struct timespec</entry>
108 <entry><structfield>timestamp</structfield></entry>
109 <entry></entry>
110 <entry>Event timestamp.</entry>
111 </row>
112 <row>
113 <entry>__u32</entry>
114 <entry><structfield>reserved</structfield>[9]</entry>
115 <entry></entry>
116 <entry>Reserved for future extensions. Drivers must set
117 the array to zero.</entry>
118 </row>
119 </tbody>
120 </tgroup>
121 </table>
122
123 </refsect1>
124</refentry>
125<!--
126Local Variables:
127mode: sgml
128sgml-parent-document: "v4l2.sgml"
129indent-tabs-mode: nil
130End:
131-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
new file mode 100644
index 000000000000..b0dde943825c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml
@@ -0,0 +1,204 @@
1<refentry id="vidioc-encoder-cmd">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENCODER_CMD</refname>
9 <refname>VIDIOC_TRY_ENCODER_CMD</refname>
10 <refpurpose>Execute an encoder command</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_encoder_cmd *<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_ENCODER_CMD, VIDIOC_TRY_ENCODER_CMD</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
55 <para>This is an <link linkend="experimental">experimental</link>
56interface and may change in the future.</para>
57 </note>
58
59 <para>These ioctls control an audio/video (usually MPEG-) encoder.
60<constant>VIDIOC_ENCODER_CMD</constant> sends a command to the
61encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to
62try a command without actually executing it.</para>
63
64 <para>To send a command applications must initialize all fields of a
65 &v4l2-encoder-cmd; and call
66 <constant>VIDIOC_ENCODER_CMD</constant> or
67 <constant>VIDIOC_TRY_ENCODER_CMD</constant> with a pointer to this
68 structure.</para>
69
70 <para>The <structfield>cmd</structfield> field must contain the
71command code. The <structfield>flags</structfield> field is currently
72only used by the STOP command and contains one bit: If the
73<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
74encoding will continue until the end of the current <wordasword>Group
75Of Pictures</wordasword>, otherwise it will stop immediately.</para>
76
77 <para>A <function>read</function>() call sends a START command to
78the encoder if it has not been started yet. After a STOP command,
79<function>read</function>() calls will read the remaining data
80buffered by the driver. When the buffer is empty,
81<function>read</function>() will return zero and the next
82<function>read</function>() call will restart the encoder.</para>
83
84 <para>A <function>close</function>() call sends an immediate STOP
85to the encoder, and all buffered data is discarded.</para>
86
87 <para>These ioctls are optional, not all drivers may support
88them. They were introduced in Linux 2.6.21.</para>
89
90 <table pgwide="1" frame="none" id="v4l2-encoder-cmd">
91 <title>struct <structname>v4l2_encoder_cmd</structname></title>
92 <tgroup cols="3">
93 &cs-str;
94 <tbody valign="top">
95 <row>
96 <entry>__u32</entry>
97 <entry><structfield>cmd</structfield></entry>
98 <entry>The encoder command, see <xref linkend="encoder-cmds" />.</entry>
99 </row>
100 <row>
101 <entry>__u32</entry>
102 <entry><structfield>flags</structfield></entry>
103 <entry>Flags to go with the command, see <xref
104 linkend="encoder-flags" />. If no flags are defined for
105this command, drivers and applications must set this field to
106zero.</entry>
107 </row>
108 <row>
109 <entry>__u32</entry>
110 <entry><structfield>data</structfield>[8]</entry>
111 <entry>Reserved for future extensions. Drivers and
112applications must set the array to zero.</entry>
113 </row>
114 </tbody>
115 </tgroup>
116 </table>
117
118 <table pgwide="1" frame="none" id="encoder-cmds">
119 <title>Encoder Commands</title>
120 <tgroup cols="3">
121 &cs-def;
122 <tbody valign="top">
123 <row>
124 <entry><constant>V4L2_ENC_CMD_START</constant></entry>
125 <entry>0</entry>
126 <entry>Start the encoder. When the encoder is already
127running or paused, this command does nothing. No flags are defined for
128this command.</entry>
129 </row>
130 <row>
131 <entry><constant>V4L2_ENC_CMD_STOP</constant></entry>
132 <entry>1</entry>
133 <entry>Stop the encoder. When the
134<constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant> flag is set,
135encoding will continue until the end of the current <wordasword>Group
136Of Pictures</wordasword>, otherwise encoding will stop immediately.
137When the encoder is already stopped, this command does
138nothing.</entry>
139 </row>
140 <row>
141 <entry><constant>V4L2_ENC_CMD_PAUSE</constant></entry>
142 <entry>2</entry>
143 <entry>Pause the encoder. When the encoder has not been
144started yet, the driver will return an &EPERM;. When the encoder is
145already paused, this command does nothing. No flags are defined for
146this command.</entry>
147 </row>
148 <row>
149 <entry><constant>V4L2_ENC_CMD_RESUME</constant></entry>
150 <entry>3</entry>
151 <entry>Resume encoding after a PAUSE command. When the
152encoder has not been started yet, the driver will return an &EPERM;.
153When the encoder is already running, this command does nothing. No
154flags are defined for this command.</entry>
155 </row>
156 </tbody>
157 </tgroup>
158 </table>
159
160 <table pgwide="1" frame="none" id="encoder-flags">
161 <title>Encoder Command Flags</title>
162 <tgroup cols="3">
163 &cs-def;
164 <tbody valign="top">
165 <row>
166 <entry><constant>V4L2_ENC_CMD_STOP_AT_GOP_END</constant></entry>
167 <entry>0x0001</entry>
168 <entry>Stop encoding at the end of the current <wordasword>Group Of
169Pictures</wordasword>, rather than immediately.</entry>
170 </row>
171 </tbody>
172 </tgroup>
173 </table>
174 </refsect1>
175
176 <refsect1>
177 &return-value;
178
179 <variablelist>
180 <varlistentry>
181 <term><errorcode>EINVAL</errorcode></term>
182 <listitem>
183 <para>The driver does not support this ioctl, or the
184<structfield>cmd</structfield> field is invalid.</para>
185 </listitem>
186 </varlistentry>
187 <varlistentry>
188 <term><errorcode>EPERM</errorcode></term>
189 <listitem>
190 <para>The application sent a PAUSE or RESUME command when
191the encoder was not running.</para>
192 </listitem>
193 </varlistentry>
194 </variablelist>
195 </refsect1>
196</refentry>
197
198<!--
199Local Variables:
200mode: sgml
201sgml-parent-document: "v4l2.sgml"
202indent-tabs-mode: nil
203End:
204-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml
new file mode 100644
index 000000000000..1d31427edd1b
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml
@@ -0,0 +1,238 @@
1<refentry id="vidioc-enum-dv-presets">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUM_DV_PRESETS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUM_DV_PRESETS</refname>
9 <refpurpose>Enumerate supported Digital Video presets</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_dv_enum_preset *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_ENUM_DV_PRESETS</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>To query the attributes of a DV preset, applications initialize the
52<structfield>index</structfield> field and zero the reserved array of &v4l2-dv-enum-preset;
53and call the <constant>VIDIOC_ENUM_DV_PRESETS</constant> ioctl with a pointer to this
54structure. Drivers fill the rest of the structure or return an
55&EINVAL; when the index is out of bounds. To enumerate all DV Presets supported,
56applications shall begin at index zero, incrementing by one until the
57driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a
58different set of DV presets after switching the video input or
59output.</para>
60
61 <table pgwide="1" frame="none" id="v4l2-dv-enum-preset">
62 <title>struct <structname>v4l2_dv_enum_presets</structname></title>
63 <tgroup cols="3">
64 &cs-str;
65 <tbody valign="top">
66 <row>
67 <entry>__u32</entry>
68 <entry><structfield>index</structfield></entry>
69 <entry>Number of the DV preset, set by the
70application.</entry>
71 </row>
72 <row>
73 <entry>__u32</entry>
74 <entry><structfield>preset</structfield></entry>
75 <entry>This field identifies one of the DV preset values listed in <xref linkend="v4l2-dv-presets-vals"/>.</entry>
76 </row>
77 <row>
78 <entry>__u8</entry>
79 <entry><structfield>name</structfield>[24]</entry>
80 <entry>Name of the preset, a NUL-terminated ASCII string, for example: "720P-60", "1080I-60". This information is
81intended for the user.</entry>
82 </row>
83 <row>
84 <entry>__u32</entry>
85 <entry><structfield>width</structfield></entry>
86 <entry>Width of the active video in pixels for the DV preset.</entry>
87 </row>
88 <row>
89 <entry>__u32</entry>
90 <entry><structfield>height</structfield></entry>
91 <entry>Height of the active video in lines for the DV preset.</entry>
92 </row>
93 <row>
94 <entry>__u32</entry>
95 <entry><structfield>reserved</structfield>[4]</entry>
96 <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
97 </row>
98 </tbody>
99 </tgroup>
100 </table>
101
102 <table pgwide="1" frame="none" id="v4l2-dv-presets-vals">
103 <title>struct <structname>DV Presets</structname></title>
104 <tgroup cols="3">
105 &cs-str;
106 <tbody valign="top">
107 <row>
108 <entry>Preset</entry>
109 <entry>Preset value</entry>
110 <entry>Description</entry>
111 </row>
112 <row>
113 <entry></entry>
114 <entry></entry>
115 <entry></entry>
116 </row>
117 <row>
118 <entry>V4L2_DV_INVALID</entry>
119 <entry>0</entry>
120 <entry>Invalid preset value.</entry>
121 </row>
122 <row>
123 <entry>V4L2_DV_480P59_94</entry>
124 <entry>1</entry>
125 <entry>720x480 progressive video at 59.94 fps as per BT.1362.</entry>
126 </row>
127 <row>
128 <entry>V4L2_DV_576P50</entry>
129 <entry>2</entry>
130 <entry>720x576 progressive video at 50 fps as per BT.1362.</entry>
131 </row>
132 <row>
133 <entry>V4L2_DV_720P24</entry>
134 <entry>3</entry>
135 <entry>1280x720 progressive video at 24 fps as per SMPTE 296M.</entry>
136 </row>
137 <row>
138 <entry>V4L2_DV_720P25</entry>
139 <entry>4</entry>
140 <entry>1280x720 progressive video at 25 fps as per SMPTE 296M.</entry>
141 </row>
142 <row>
143 <entry>V4L2_DV_720P30</entry>
144 <entry>5</entry>
145 <entry>1280x720 progressive video at 30 fps as per SMPTE 296M.</entry>
146 </row>
147 <row>
148 <entry>V4L2_DV_720P50</entry>
149 <entry>6</entry>
150 <entry>1280x720 progressive video at 50 fps as per SMPTE 296M.</entry>
151 </row>
152 <row>
153 <entry>V4L2_DV_720P59_94</entry>
154 <entry>7</entry>
155 <entry>1280x720 progressive video at 59.94 fps as per SMPTE 274M.</entry>
156 </row>
157 <row>
158 <entry>V4L2_DV_720P60</entry>
159 <entry>8</entry>
160 <entry>1280x720 progressive video at 60 fps as per SMPTE 274M/296M.</entry>
161 </row>
162 <row>
163 <entry>V4L2_DV_1080I29_97</entry>
164 <entry>9</entry>
165 <entry>1920x1080 interlaced video at 29.97 fps as per BT.1120/SMPTE 274M.</entry>
166 </row>
167 <row>
168 <entry>V4L2_DV_1080I30</entry>
169 <entry>10</entry>
170 <entry>1920x1080 interlaced video at 30 fps as per BT.1120/SMPTE 274M.</entry>
171 </row>
172 <row>
173 <entry>V4L2_DV_1080I25</entry>
174 <entry>11</entry>
175 <entry>1920x1080 interlaced video at 25 fps as per BT.1120.</entry>
176 </row>
177 <row>
178 <entry>V4L2_DV_1080I50</entry>
179 <entry>12</entry>
180 <entry>1920x1080 interlaced video at 50 fps as per SMPTE 296M.</entry>
181 </row>
182 <row>
183 <entry>V4L2_DV_1080I60</entry>
184 <entry>13</entry>
185 <entry>1920x1080 interlaced video at 60 fps as per SMPTE 296M.</entry>
186 </row>
187 <row>
188 <entry>V4L2_DV_1080P24</entry>
189 <entry>14</entry>
190 <entry>1920x1080 progressive video at 24 fps as per SMPTE 296M.</entry>
191 </row>
192 <row>
193 <entry>V4L2_DV_1080P25</entry>
194 <entry>15</entry>
195 <entry>1920x1080 progressive video at 25 fps as per SMPTE 296M.</entry>
196 </row>
197 <row>
198 <entry>V4L2_DV_1080P30</entry>
199 <entry>16</entry>
200 <entry>1920x1080 progressive video at 30 fps as per SMPTE 296M.</entry>
201 </row>
202 <row>
203 <entry>V4L2_DV_1080P50</entry>
204 <entry>17</entry>
205 <entry>1920x1080 progressive video at 50 fps as per BT.1120.</entry>
206 </row>
207 <row>
208 <entry>V4L2_DV_1080P60</entry>
209 <entry>18</entry>
210 <entry>1920x1080 progressive video at 60 fps as per BT.1120.</entry>
211 </row>
212 </tbody>
213 </tgroup>
214 </table>
215 </refsect1>
216
217 <refsect1>
218 &return-value;
219
220 <variablelist>
221 <varlistentry>
222 <term><errorcode>EINVAL</errorcode></term>
223 <listitem>
224 <para>The &v4l2-dv-enum-preset; <structfield>index</structfield>
225is out of bounds.</para>
226 </listitem>
227 </varlistentry>
228 </variablelist>
229 </refsect1>
230</refentry>
231
232<!--
233Local Variables:
234mode: sgml
235sgml-parent-document: "v4l2.sgml"
236indent-tabs-mode: nil
237End:
238-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
new file mode 100644
index 000000000000..71d373b6d36a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml
@@ -0,0 +1,166 @@
1<refentry id="vidioc-enum-fmt">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUM_FMT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUM_FMT</refname>
9 <refpurpose>Enumerate image 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_fmtdesc
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_ENUM_FMT</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 image formats applications initialize the
53<structfield>type</structfield> and <structfield>index</structfield>
54field of &v4l2-fmtdesc; and call the
55<constant>VIDIOC_ENUM_FMT</constant> ioctl with a pointer to this
56structure. Drivers fill the rest of the structure or return an
57&EINVAL;. All formats are enumerable by beginning at index zero and
58incrementing by one until <errorcode>EINVAL</errorcode> is
59returned.</para>
60
61 <table pgwide="1" frame="none" id="v4l2-fmtdesc">
62 <title>struct <structname>v4l2_fmtdesc</structname></title>
63 <tgroup cols="3">
64 &cs-str;
65 <tbody valign="top">
66 <row>
67 <entry>__u32</entry>
68 <entry><structfield>index</structfield></entry>
69 <entry>Number of the format in the enumeration, set by
70the application. This is in no way related to the <structfield>
71pixelformat</structfield> field.</entry>
72 </row>
73 <row>
74 <entry>&v4l2-buf-type;</entry>
75 <entry><structfield>type</structfield></entry>
76 <entry>Type of the data stream, set by the application.
77Only these types are valid here:
78<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
79<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>,
80<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
81<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>,
82<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
83defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
84and higher.</entry>
85 </row>
86 <row>
87 <entry>__u32</entry>
88 <entry><structfield>flags</structfield></entry>
89 <entry>See <xref linkend="fmtdesc-flags" /></entry>
90 </row>
91 <row>
92 <entry>__u8</entry>
93 <entry><structfield>description</structfield>[32]</entry>
94 <entry>Description of the format, a NUL-terminated ASCII
95string. This information is intended for the user, for example: "YUV
964:2:2".</entry>
97 </row>
98 <row>
99 <entry>__u32</entry>
100 <entry><structfield>pixelformat</structfield></entry>
101 <entry>The image format identifier. This is a
102four character code as computed by the v4l2_fourcc()
103macro:</entry>
104 </row>
105 <row>
106 <entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
107#define v4l2_fourcc(a,b,c,d) (((__u32)(a)&lt;&lt;0)|((__u32)(b)&lt;&lt;8)|((__u32)(c)&lt;&lt;16)|((__u32)(d)&lt;&lt;24))
108</programlisting></para><para>Several image formats are already
109defined by this specification in <xref linkend="pixfmt" />. Note these
110codes are not the same as those used in the Windows world.</para></entry>
111 </row>
112 <row>
113 <entry>__u32</entry>
114 <entry><structfield>reserved</structfield>[4]</entry>
115 <entry>Reserved for future extensions. Drivers must set
116the array to zero.</entry>
117 </row>
118 </tbody>
119 </tgroup>
120 </table>
121
122 <table pgwide="1" frame="none" id="fmtdesc-flags">
123 <title>Image Format Description Flags</title>
124 <tgroup cols="3">
125 &cs-def;
126 <tbody valign="top">
127 <row>
128 <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry>
129 <entry>0x0001</entry>
130 <entry>This is a compressed format.</entry>
131 </row>
132 <row>
133 <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry>
134 <entry>0x0002</entry>
135 <entry>This format is not native to the device but emulated
136through software (usually libv4l2), where possible try to use a native format
137instead for better performance.</entry>
138 </row>
139 </tbody>
140 </tgroup>
141 </table>
142 </refsect1>
143
144 <refsect1>
145 &return-value;
146
147 <variablelist>
148 <varlistentry>
149 <term><errorcode>EINVAL</errorcode></term>
150 <listitem>
151 <para>The &v4l2-fmtdesc; <structfield>type</structfield>
152is not supported or the <structfield>index</structfield> is out of
153bounds.</para>
154 </listitem>
155 </varlistentry>
156 </variablelist>
157 </refsect1>
158</refentry>
159
160<!--
161Local Variables:
162mode: sgml
163sgml-parent-document: "v4l2.sgml"
164indent-tabs-mode: nil
165End:
166-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml b/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
new file mode 100644
index 000000000000..3c216e113a54
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-frameintervals.xml
@@ -0,0 +1,270 @@
1<refentry id="vidioc-enum-frameintervals">
2
3 <refmeta>
4 <refentrytitle>ioctl VIDIOC_ENUM_FRAMEINTERVALS</refentrytitle>
5 &manvol;
6 </refmeta>
7
8 <refnamediv>
9 <refname>VIDIOC_ENUM_FRAMEINTERVALS</refname>
10 <refpurpose>Enumerate frame intervals</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_frmivalenum *<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_ENUM_FRAMEINTERVALS</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para>Pointer to a &v4l2-frmivalenum; structure that
44contains a pixel format and size and receives a frame interval.</para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <para>This ioctl allows applications to enumerate all frame
54intervals that the device supports for the given pixel format and
55frame size.</para>
56 <para>The supported pixel formats and frame sizes can be obtained
57by using the &VIDIOC-ENUM-FMT; and &VIDIOC-ENUM-FRAMESIZES;
58functions.</para>
59 <para>The return value and the content of the
60<structfield>v4l2_frmivalenum.type</structfield> field depend on the
61type of frame intervals the device supports. Here are the semantics of
62the function for the different cases:</para>
63 <itemizedlist>
64 <listitem>
65 <para><emphasis role="bold">Discrete:</emphasis> The function
66returns success if the given index value (zero-based) is valid. The
67application should increase the index by one for each call until
68<constant>EINVAL</constant> is returned. The `v4l2_frmivalenum.type`
69field is set to `V4L2_FRMIVAL_TYPE_DISCRETE` by the driver. Of the
70union only the `discrete` member is valid.</para>
71 </listitem>
72 <listitem>
73 <para><emphasis role="bold">Step-wise:</emphasis> The function
74returns success if the given index value is zero and
75<constant>EINVAL</constant> for any other index value. The
76<structfield>v4l2_frmivalenum.type</structfield> field is set to
77<constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant> by the driver. Of the
78union only the <structfield>stepwise</structfield> member is
79valid.</para>
80 </listitem>
81 <listitem>
82 <para><emphasis role="bold">Continuous:</emphasis> This is a
83special case of the step-wise type above. The function returns success
84if the given index value is zero and <constant>EINVAL</constant> for
85any other index value. The
86<structfield>v4l2_frmivalenum.type</structfield> field is set to
87<constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant> by the driver. Of
88the union only the <structfield>stepwise</structfield> member is valid
89and the <structfield>step</structfield> value is set to 1.</para>
90 </listitem>
91 </itemizedlist>
92
93 <para>When the application calls the function with index zero, it
94must check the <structfield>type</structfield> field to determine the
95type of frame interval enumeration the device supports. Only for the
96<constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant> type does it make
97sense to increase the index value to receive more frame
98intervals.</para>
99 <para>Note that the order in which the frame intervals are
100returned has no special meaning. In particular does it not say
101anything about potential default frame intervals.</para>
102 <para>Applications can assume that the enumeration data does not
103change without any interaction from the application itself. This means
104that the enumeration data is consistent if the application does not
105perform any other ioctl calls while it runs the frame interval
106enumeration.</para>
107 </refsect1>
108
109 <refsect1>
110 <title>Notes</title>
111
112 <itemizedlist>
113 <listitem>
114 <para><emphasis role="bold">Frame intervals and frame
115rates:</emphasis> The V4L2 API uses frame intervals instead of frame
116rates. Given the frame interval the frame rate can be computed as
117follows:<screen>frame_rate = 1 / frame_interval</screen></para>
118 </listitem>
119 </itemizedlist>
120
121 </refsect1>
122
123 <refsect1>
124 <title>Structs</title>
125
126 <para>In the structs below, <emphasis>IN</emphasis> denotes a
127value that has to be filled in by the application,
128<emphasis>OUT</emphasis> denotes values that the driver fills in. The
129application should zero out all members except for the
130<emphasis>IN</emphasis> fields.</para>
131
132 <table pgwide="1" frame="none" id="v4l2-frmival-stepwise">
133 <title>struct <structname>v4l2_frmival_stepwise</structname></title>
134 <tgroup cols="3">
135 &cs-str;
136 <tbody valign="top">
137 <row>
138 <entry>&v4l2-fract;</entry>
139 <entry><structfield>min</structfield></entry>
140 <entry>Minimum frame interval [s].</entry>
141 </row>
142 <row>
143 <entry>&v4l2-fract;</entry>
144 <entry><structfield>max</structfield></entry>
145 <entry>Maximum frame interval [s].</entry>
146 </row>
147 <row>
148 <entry>&v4l2-fract;</entry>
149 <entry><structfield>step</structfield></entry>
150 <entry>Frame interval step size [s].</entry>
151 </row>
152 </tbody>
153 </tgroup>
154 </table>
155
156 <table pgwide="1" frame="none" id="v4l2-frmivalenum">
157 <title>struct <structname>v4l2_frmivalenum</structname></title>
158 <tgroup cols="4">
159 <colspec colname="c1" />
160 <colspec colname="c2" />
161 <colspec colname="c3" />
162 <colspec colname="c4" />
163 <tbody valign="top">
164 <row>
165 <entry>__u32</entry>
166 <entry><structfield>index</structfield></entry>
167 <entry></entry>
168 <entry>IN: Index of the given frame interval in the
169enumeration.</entry>
170 </row>
171 <row>
172 <entry>__u32</entry>
173 <entry><structfield>pixel_format</structfield></entry>
174 <entry></entry>
175 <entry>IN: Pixel format for which the frame intervals are
176enumerated.</entry>
177 </row>
178 <row>
179 <entry>__u32</entry>
180 <entry><structfield>width</structfield></entry>
181 <entry></entry>
182 <entry>IN: Frame width for which the frame intervals are
183enumerated.</entry>
184 </row>
185 <row>
186 <entry>__u32</entry>
187 <entry><structfield>height</structfield></entry>
188 <entry></entry>
189 <entry>IN: Frame height for which the frame intervals are
190enumerated.</entry>
191 </row>
192 <row>
193 <entry>__u32</entry>
194 <entry><structfield>type</structfield></entry>
195 <entry></entry>
196 <entry>OUT: Frame interval type the device supports.</entry>
197 </row>
198 <row>
199 <entry>union</entry>
200 <entry></entry>
201 <entry></entry>
202 <entry>OUT: Frame interval with the given index.</entry>
203 </row>
204 <row>
205 <entry></entry>
206 <entry>&v4l2-fract;</entry>
207 <entry><structfield>discrete</structfield></entry>
208 <entry>Frame interval [s].</entry>
209 </row>
210 <row>
211 <entry></entry>
212 <entry>&v4l2-frmival-stepwise;</entry>
213 <entry><structfield>stepwise</structfield></entry>
214 <entry></entry>
215 </row>
216 <row>
217 <entry>__u32</entry>
218 <entry><structfield>reserved[2]</structfield></entry>
219 <entry></entry>
220 <entry>Reserved space for future use.</entry>
221 </row>
222 </tbody>
223 </tgroup>
224 </table>
225 </refsect1>
226
227 <refsect1>
228 <title>Enums</title>
229
230 <table pgwide="1" frame="none" id="v4l2-frmivaltypes">
231 <title>enum <structname>v4l2_frmivaltypes</structname></title>
232 <tgroup cols="3">
233 &cs-def;
234 <tbody valign="top">
235 <row>
236 <entry><constant>V4L2_FRMIVAL_TYPE_DISCRETE</constant></entry>
237 <entry>1</entry>
238 <entry>Discrete frame interval.</entry>
239 </row>
240 <row>
241 <entry><constant>V4L2_FRMIVAL_TYPE_CONTINUOUS</constant></entry>
242 <entry>2</entry>
243 <entry>Continuous frame interval.</entry>
244 </row>
245 <row>
246 <entry><constant>V4L2_FRMIVAL_TYPE_STEPWISE</constant></entry>
247 <entry>3</entry>
248 <entry>Step-wise defined frame interval.</entry>
249 </row>
250 </tbody>
251 </tgroup>
252 </table>
253 </refsect1>
254
255 <refsect1>
256 &return-value;
257
258 <para>See the description section above for a list of return
259values that <varname>errno</varname> can have.</para>
260 </refsect1>
261
262</refentry>
263
264<!--
265Local Variables:
266mode: sgml
267sgml-parent-document: "v4l2.sgml"
268indent-tabs-mode: nil
269End:
270-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
new file mode 100644
index 000000000000..6afa4542c818
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml
@@ -0,0 +1,282 @@
1<refentry id="vidioc-enum-framesizes">
2
3 <refmeta>
4 <refentrytitle>ioctl VIDIOC_ENUM_FRAMESIZES</refentrytitle>
5 &manvol;
6 </refmeta>
7
8 <refnamediv>
9 <refname>VIDIOC_ENUM_FRAMESIZES</refname>
10 <refpurpose>Enumerate frame sizes</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_frmsizeenum *<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_ENUM_FRAMESIZES</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para>Pointer to a &v4l2-frmsizeenum; that contains an index
44and pixel format and receives a frame width and height.</para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <note>
54 <title>Experimental</title>
55
56 <para>This is an <link linkend="experimental">experimental</link>
57interface and may change in the future.</para>
58 </note>
59
60 <para>This ioctl allows applications to enumerate all frame sizes
61(&ie; width and height in pixels) that the device supports for the
62given pixel format.</para>
63 <para>The supported pixel formats can be obtained by using the
64&VIDIOC-ENUM-FMT; function.</para>
65 <para>The return value and the content of the
66<structfield>v4l2_frmsizeenum.type</structfield> field depend on the
67type of frame sizes the device supports. Here are the semantics of the
68function for the different cases:</para>
69
70 <itemizedlist>
71 <listitem>
72 <para><emphasis role="bold">Discrete:</emphasis> The function
73returns success if the given index value (zero-based) is valid. The
74application should increase the index by one for each call until
75<constant>EINVAL</constant> is returned. The
76<structfield>v4l2_frmsizeenum.type</structfield> field is set to
77<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> by the driver. Of the
78union only the <structfield>discrete</structfield> member is
79valid.</para>
80 </listitem>
81 <listitem>
82 <para><emphasis role="bold">Step-wise:</emphasis> The function
83returns success if the given index value is zero and
84<constant>EINVAL</constant> for any other index value. The
85<structfield>v4l2_frmsizeenum.type</structfield> field is set to
86<constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant> by the driver. Of the
87union only the <structfield>stepwise</structfield> member is
88valid.</para>
89 </listitem>
90 <listitem>
91 <para><emphasis role="bold">Continuous:</emphasis> This is a
92special case of the step-wise type above. The function returns success
93if the given index value is zero and <constant>EINVAL</constant> for
94any other index value. The
95<structfield>v4l2_frmsizeenum.type</structfield> field is set to
96<constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant> by the driver. Of
97the union only the <structfield>stepwise</structfield> member is valid
98and the <structfield>step_width</structfield> and
99<structfield>step_height</structfield> values are set to 1.</para>
100 </listitem>
101 </itemizedlist>
102
103 <para>When the application calls the function with index zero, it
104must check the <structfield>type</structfield> field to determine the
105type of frame size enumeration the device supports. Only for the
106<constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant> type does it make
107sense to increase the index value to receive more frame sizes.</para>
108 <para>Note that the order in which the frame sizes are returned
109has no special meaning. In particular does it not say anything about
110potential default format sizes.</para>
111 <para>Applications can assume that the enumeration data does not
112change without any interaction from the application itself. This means
113that the enumeration data is consistent if the application does not
114perform any other ioctl calls while it runs the frame size
115enumeration.</para>
116 </refsect1>
117
118 <refsect1>
119 <title>Structs</title>
120
121 <para>In the structs below, <emphasis>IN</emphasis> denotes a
122value that has to be filled in by the application,
123<emphasis>OUT</emphasis> denotes values that the driver fills in. The
124application should zero out all members except for the
125<emphasis>IN</emphasis> fields.</para>
126
127 <table pgwide="1" frame="none" id="v4l2-frmsize-discrete">
128 <title>struct <structname>v4l2_frmsize_discrete</structname></title>
129 <tgroup cols="3">
130 &cs-str;
131 <tbody valign="top">
132 <row>
133 <entry>__u32</entry>
134 <entry><structfield>width</structfield></entry>
135 <entry>Width of the frame [pixel].</entry>
136 </row>
137 <row>
138 <entry>__u32</entry>
139 <entry><structfield>height</structfield></entry>
140 <entry>Height of the frame [pixel].</entry>
141 </row>
142 </tbody>
143 </tgroup>
144 </table>
145
146 <table pgwide="1" frame="none" id="v4l2-frmsize-stepwise">
147 <title>struct <structname>v4l2_frmsize_stepwise</structname></title>
148 <tgroup cols="3">
149 &cs-str;
150 <tbody valign="top">
151 <row>
152 <entry>__u32</entry>
153 <entry><structfield>min_width</structfield></entry>
154 <entry>Minimum frame width [pixel].</entry>
155 </row>
156 <row>
157 <entry>__u32</entry>
158 <entry><structfield>max_width</structfield></entry>
159 <entry>Maximum frame width [pixel].</entry>
160 </row>
161 <row>
162 <entry>__u32</entry>
163 <entry><structfield>step_width</structfield></entry>
164 <entry>Frame width step size [pixel].</entry>
165 </row>
166 <row>
167 <entry>__u32</entry>
168 <entry><structfield>min_height</structfield></entry>
169 <entry>Minimum frame height [pixel].</entry>
170 </row>
171 <row>
172 <entry>__u32</entry>
173 <entry><structfield>max_height</structfield></entry>
174 <entry>Maximum frame height [pixel].</entry>
175 </row>
176 <row>
177 <entry>__u32</entry>
178 <entry><structfield>step_height</structfield></entry>
179 <entry>Frame height step size [pixel].</entry>
180 </row>
181 </tbody>
182 </tgroup>
183 </table>
184
185 <table pgwide="1" frame="none" id="v4l2-frmsizeenum">
186 <title>struct <structname>v4l2_frmsizeenum</structname></title>
187 <tgroup cols="4">
188 <colspec colname="c1" />
189 <colspec colname="c2" />
190 <colspec colname="c3" />
191 <colspec colname="c4" />
192 <tbody valign="top">
193 <row>
194 <entry>__u32</entry>
195 <entry><structfield>index</structfield></entry>
196 <entry></entry>
197 <entry>IN: Index of the given frame size in the enumeration.</entry>
198 </row>
199 <row>
200 <entry>__u32</entry>
201 <entry><structfield>pixel_format</structfield></entry>
202 <entry></entry>
203 <entry>IN: Pixel format for which the frame sizes are enumerated.</entry>
204 </row>
205 <row>
206 <entry>__u32</entry>
207 <entry><structfield>type</structfield></entry>
208 <entry></entry>
209 <entry>OUT: Frame size type the device supports.</entry>
210 </row>
211 <row>
212 <entry>union</entry>
213 <entry></entry>
214 <entry></entry>
215 <entry>OUT: Frame size with the given index.</entry>
216 </row>
217 <row>
218 <entry></entry>
219 <entry>&v4l2-frmsize-discrete;</entry>
220 <entry><structfield>discrete</structfield></entry>
221 <entry></entry>
222 </row>
223 <row>
224 <entry></entry>
225 <entry>&v4l2-frmsize-stepwise;</entry>
226 <entry><structfield>stepwise</structfield></entry>
227 <entry></entry>
228 </row>
229 <row>
230 <entry>__u32</entry>
231 <entry><structfield>reserved[2]</structfield></entry>
232 <entry></entry>
233 <entry>Reserved space for future use.</entry>
234 </row>
235 </tbody>
236 </tgroup>
237 </table>
238 </refsect1>
239
240 <refsect1>
241 <title>Enums</title>
242
243 <table pgwide="1" frame="none" id="v4l2-frmsizetypes">
244 <title>enum <structname>v4l2_frmsizetypes</structname></title>
245 <tgroup cols="3">
246 &cs-def;
247 <tbody valign="top">
248 <row>
249 <entry><constant>V4L2_FRMSIZE_TYPE_DISCRETE</constant></entry>
250 <entry>1</entry>
251 <entry>Discrete frame size.</entry>
252 </row>
253 <row>
254 <entry><constant>V4L2_FRMSIZE_TYPE_CONTINUOUS</constant></entry>
255 <entry>2</entry>
256 <entry>Continuous frame size.</entry>
257 </row>
258 <row>
259 <entry><constant>V4L2_FRMSIZE_TYPE_STEPWISE</constant></entry>
260 <entry>3</entry>
261 <entry>Step-wise defined frame size.</entry>
262 </row>
263 </tbody>
264 </tgroup>
265 </table>
266 </refsect1>
267
268 <refsect1>
269 &return-value;
270
271 <para>See the description section above for a list of return
272values that <varname>errno</varname> can have.</para>
273 </refsect1>
274</refentry>
275
276<!--
277Local Variables:
278mode: sgml
279sgml-parent-document: "v4l2.sgml"
280indent-tabs-mode: nil
281End:
282-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml b/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml
new file mode 100644
index 000000000000..9ae8f2d3a96f
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enumaudio.xml
@@ -0,0 +1,86 @@
1<refentry id="vidioc-enumaudio">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUMAUDIO</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUMAUDIO</refname>
9 <refpurpose>Enumerate audio inputs</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_audio *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_ENUMAUDIO</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>To query the attributes of an audio input applications
52initialize the <structfield>index</structfield> field and zero out the
53<structfield>reserved</structfield> array of a &v4l2-audio;
54and call the <constant>VIDIOC_ENUMAUDIO</constant> ioctl with a pointer
55to this structure. Drivers fill the rest of the structure or return an
56&EINVAL; when the index is out of bounds. To enumerate all audio
57inputs applications shall begin at index zero, incrementing by one
58until the driver returns <errorcode>EINVAL</errorcode>.</para>
59
60 <para>See <xref linkend="vidioc-g-audio" /> for a description of
61&v4l2-audio;.</para>
62 </refsect1>
63
64 <refsect1>
65 &return-value;
66
67 <variablelist>
68 <varlistentry>
69 <term><errorcode>EINVAL</errorcode></term>
70 <listitem>
71 <para>The number of the audio input is out of bounds, or
72there are no audio inputs at all and this ioctl is not
73supported.</para>
74 </listitem>
75 </varlistentry>
76 </variablelist>
77 </refsect1>
78</refentry>
79
80<!--
81Local Variables:
82mode: sgml
83sgml-parent-document: "v4l2.sgml"
84indent-tabs-mode: nil
85End:
86-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml b/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml
new file mode 100644
index 000000000000..d3d7c0ab17b8
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enumaudioout.xml
@@ -0,0 +1,89 @@
1<refentry id="vidioc-enumaudioout">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUMAUDOUT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUMAUDOUT</refname>
9 <refpurpose>Enumerate audio outputs</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_audioout *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_ENUMAUDOUT</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>To query the attributes of an audio output applications
52initialize the <structfield>index</structfield> field and zero out the
53<structfield>reserved</structfield> array of a &v4l2-audioout; and
54call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
55to this structure. Drivers fill the rest of the structure or return an
56&EINVAL; when the index is out of bounds. To enumerate all audio
57outputs applications shall begin at index zero, incrementing by one
58until the driver returns <errorcode>EINVAL</errorcode>.</para>
59
60 <para>Note connectors on a TV card to loop back the received audio
61signal to a sound card are not audio outputs in this sense.</para>
62
63 <para>See <xref linkend="vidioc-g-audioout" /> for a description of
64&v4l2-audioout;.</para>
65 </refsect1>
66
67 <refsect1>
68 &return-value;
69
70 <variablelist>
71 <varlistentry>
72 <term><errorcode>EINVAL</errorcode></term>
73 <listitem>
74 <para>The number of the audio output is out of bounds, or
75there are no audio outputs at all and this ioctl is not
76supported.</para>
77 </listitem>
78 </varlistentry>
79 </variablelist>
80 </refsect1>
81</refentry>
82
83<!--
84Local Variables:
85mode: sgml
86sgml-parent-document: "v4l2.sgml"
87indent-tabs-mode: nil
88End:
89-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
new file mode 100644
index 000000000000..476fe1d2bba0
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
@@ -0,0 +1,321 @@
1<refentry id="vidioc-enuminput">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUMINPUT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUMINPUT</refname>
9 <refpurpose>Enumerate video inputs</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_input
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_ENUMINPUT</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 query the attributes of a video input applications
53initialize the <structfield>index</structfield> field of &v4l2-input;
54and call the <constant>VIDIOC_ENUMINPUT</constant> ioctl with a
55pointer to this structure. Drivers fill the rest of the structure or
56return an &EINVAL; when the index is out of bounds. To enumerate all
57inputs applications shall begin at index zero, incrementing by one
58until the driver returns <errorcode>EINVAL</errorcode>.</para>
59
60 <table frame="none" pgwide="1" id="v4l2-input">
61 <title>struct <structname>v4l2_input</structname></title>
62 <tgroup cols="3">
63 &cs-str;
64 <tbody valign="top">
65 <row>
66 <entry>__u32</entry>
67 <entry><structfield>index</structfield></entry>
68 <entry>Identifies the input, set by the
69application.</entry>
70 </row>
71 <row>
72 <entry>__u8</entry>
73 <entry><structfield>name</structfield>[32]</entry>
74 <entry>Name of the video input, a NUL-terminated ASCII
75string, for example: "Vin (Composite 2)". This information is intended
76for the user, preferably the connector label on the device itself.</entry>
77 </row>
78 <row>
79 <entry>__u32</entry>
80 <entry><structfield>type</structfield></entry>
81 <entry>Type of the input, see <xref
82 linkend="input-type" />.</entry>
83 </row>
84 <row>
85 <entry>__u32</entry>
86 <entry><structfield>audioset</structfield></entry>
87 <entry><para>Drivers can enumerate up to 32 video and
88audio inputs. This field shows which audio inputs were selectable as
89audio source if this was the currently selected video input. It is a
90bit mask. The LSB corresponds to audio input 0, the MSB to input 31.
91Any number of bits can be set, or none.</para><para>When the driver
92does not enumerate audio inputs no bits must be set. Applications
93shall not interpret this as lack of audio support. Some drivers
94automatically select audio sources and do not enumerate them since
95there is no choice anyway.</para><para>For details on audio inputs and
96how to select the current input see <xref
97 linkend="audio" />.</para></entry>
98 </row>
99 <row>
100 <entry>__u32</entry>
101 <entry><structfield>tuner</structfield></entry>
102 <entry>Capture devices can have zero or more tuners (RF
103demodulators). When the <structfield>type</structfield> is set to
104<constant>V4L2_INPUT_TYPE_TUNER</constant> this is an RF connector and
105this field identifies the tuner. It corresponds to
106&v4l2-tuner; field <structfield>index</structfield>. For details on
107tuners see <xref linkend="tuner" />.</entry>
108 </row>
109 <row>
110 <entry>&v4l2-std-id;</entry>
111 <entry><structfield>std</structfield></entry>
112 <entry>Every video input supports one or more different
113video standards. This field is a set of all supported standards. For
114details on video standards and how to switch see <xref
115linkend="standard" />.</entry>
116 </row>
117 <row>
118 <entry>__u32</entry>
119 <entry><structfield>status</structfield></entry>
120 <entry>This field provides status information about the
121input. See <xref linkend="input-status" /> for flags.
122With the exception of the sensor orientation bits <structfield>status</structfield> is only valid when this is the
123current input.</entry>
124 </row>
125 <row>
126 <entry>__u32</entry>
127 <entry><structfield>capabilities</structfield></entry>
128 <entry>This field provides capabilities for the
129input. See <xref linkend="input-capabilities" /> for flags.</entry>
130 </row>
131 <row>
132 <entry>__u32</entry>
133 <entry><structfield>reserved</structfield>[3]</entry>
134 <entry>Reserved for future extensions. Drivers must set
135the array to zero.</entry>
136 </row>
137 </tbody>
138 </tgroup>
139 </table>
140
141 <table frame="none" pgwide="1" id="input-type">
142 <title>Input Types</title>
143 <tgroup cols="3">
144 &cs-def;
145 <tbody valign="top">
146 <row>
147 <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
148 <entry>1</entry>
149 <entry>This input uses a tuner (RF demodulator).</entry>
150 </row>
151 <row>
152 <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
153 <entry>2</entry>
154 <entry>Analog baseband input, for example CVBS /
155Composite Video, S-Video, RGB.</entry>
156 </row>
157 </tbody>
158 </tgroup>
159 </table>
160
161 <!-- Status flags based on proposal by Mark McClelland,
162video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re:
163v4l2 api". "Why are some of them inverted? So that the driver doesn't
164have to lie about the status in cases where it can't tell one way or
165the other. Plus, a status of zero would generally mean that everything
166is OK." -->
167
168 <table frame="none" pgwide="1" id="input-status">
169 <title>Input Status Flags</title>
170 <tgroup cols="3">
171 <colspec colname="c1" />
172 <colspec colname="c2" align="center" />
173 <colspec colname="c3" />
174 <spanspec namest="c1" nameend="c3" spanname="hspan"
175 align="left" />
176 <tbody valign="top">
177 <row>
178 <entry spanname="hspan">General</entry>
179 </row>
180 <row>
181 <entry><constant>V4L2_IN_ST_NO_POWER</constant></entry>
182 <entry>0x00000001</entry>
183 <entry>Attached device is off.</entry>
184 </row>
185 <row>
186 <entry><constant>V4L2_IN_ST_NO_SIGNAL</constant></entry>
187 <entry>0x00000002</entry>
188 <entry></entry>
189 </row>
190 <row>
191 <entry><constant>V4L2_IN_ST_NO_COLOR</constant></entry>
192 <entry>0x00000004</entry>
193 <entry>The hardware supports color decoding, but does not
194detect color modulation in the signal.</entry>
195 </row>
196 <row>
197 <entry spanname="hspan">Sensor Orientation</entry>
198 </row>
199 <row>
200 <entry><constant>V4L2_IN_ST_HFLIP</constant></entry>
201 <entry>0x00000010</entry>
202 <entry>The input is connected to a device that produces a signal
203that is flipped horizontally and does not correct this before passing the
204signal to userspace.</entry>
205 </row>
206 <row>
207 <entry><constant>V4L2_IN_ST_VFLIP</constant></entry>
208 <entry>0x00000020</entry>
209 <entry>The input is connected to a device that produces a signal
210that is flipped vertically and does not correct this before passing the
211signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry>
212 </row>
213 <row>
214 <entry spanname="hspan">Analog Video</entry>
215 </row>
216 <row>
217 <entry><constant>V4L2_IN_ST_NO_H_LOCK</constant></entry>
218 <entry>0x00000100</entry>
219 <entry>No horizontal sync lock.</entry>
220 </row>
221 <row>
222 <entry><constant>V4L2_IN_ST_COLOR_KILL</constant></entry>
223 <entry>0x00000200</entry>
224 <entry>A color killer circuit automatically disables color
225decoding when it detects no color modulation. When this flag is set
226the color killer is enabled <emphasis>and</emphasis> has shut off
227color decoding.</entry>
228 </row>
229 <row>
230 <entry spanname="hspan">Digital Video</entry>
231 </row>
232 <row>
233 <entry><constant>V4L2_IN_ST_NO_SYNC</constant></entry>
234 <entry>0x00010000</entry>
235 <entry>No synchronization lock.</entry>
236 </row>
237 <row>
238 <entry><constant>V4L2_IN_ST_NO_EQU</constant></entry>
239 <entry>0x00020000</entry>
240 <entry>No equalizer lock.</entry>
241 </row>
242 <row>
243 <entry><constant>V4L2_IN_ST_NO_CARRIER</constant></entry>
244 <entry>0x00040000</entry>
245 <entry>Carrier recovery failed.</entry>
246 </row>
247 <row>
248 <entry spanname="hspan">VCR and Set-Top Box</entry>
249 </row>
250 <row>
251 <entry><constant>V4L2_IN_ST_MACROVISION</constant></entry>
252 <entry>0x01000000</entry>
253 <entry>Macrovision is an analog copy prevention system
254mangling the video signal to confuse video recorders. When this
255flag is set Macrovision has been detected.</entry>
256 </row>
257 <row>
258 <entry><constant>V4L2_IN_ST_NO_ACCESS</constant></entry>
259 <entry>0x02000000</entry>
260 <entry>Conditional access denied.</entry>
261 </row>
262 <row>
263 <entry><constant>V4L2_IN_ST_VTR</constant></entry>
264 <entry>0x04000000</entry>
265 <entry>VTR time constant. [?]</entry>
266 </row>
267 </tbody>
268 </tgroup>
269 </table>
270
271 <!-- Capability flags based on video timings RFC by Muralidharan
272Karicheri, titled RFC (v1.2): V4L - Support for video timings at the
273input/output interface to linux-media@vger.kernel.org on 19 Oct 2009.
274 -->
275 <table frame="none" pgwide="1" id="input-capabilities">
276 <title>Input capabilities</title>
277 <tgroup cols="3">
278 &cs-def;
279 <tbody valign="top">
280 <row>
281 <entry><constant>V4L2_IN_CAP_PRESETS</constant></entry>
282 <entry>0x00000001</entry>
283 <entry>This input supports setting DV presets by using VIDIOC_S_DV_PRESET.</entry>
284 </row>
285 <row>
286 <entry><constant>V4L2_IN_CAP_CUSTOM_TIMINGS</constant></entry>
287 <entry>0x00000002</entry>
288 <entry>This input supports setting custom video timings by using VIDIOC_S_DV_TIMINGS.</entry>
289 </row>
290 <row>
291 <entry><constant>V4L2_IN_CAP_STD</constant></entry>
292 <entry>0x00000004</entry>
293 <entry>This input supports setting the TV standard by using VIDIOC_S_STD.</entry>
294 </row>
295 </tbody>
296 </tgroup>
297 </table>
298 </refsect1>
299
300 <refsect1>
301 &return-value;
302
303 <variablelist>
304 <varlistentry>
305 <term><errorcode>EINVAL</errorcode></term>
306 <listitem>
307 <para>The &v4l2-input; <structfield>index</structfield> is
308out of bounds.</para>
309 </listitem>
310 </varlistentry>
311 </variablelist>
312 </refsect1>
313</refentry>
314
315<!--
316Local Variables:
317mode: sgml
318sgml-parent-document: "v4l2.sgml"
319indent-tabs-mode: nil
320End:
321-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml
new file mode 100644
index 000000000000..a281d26a195f
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml
@@ -0,0 +1,206 @@
1<refentry id="vidioc-enumoutput">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUMOUTPUT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUMOUTPUT</refname>
9 <refpurpose>Enumerate video outputs</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_output *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_ENUMOUTPUT</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>To query the attributes of a video outputs applications
52initialize the <structfield>index</structfield> field of &v4l2-output;
53and call the <constant>VIDIOC_ENUMOUTPUT</constant> ioctl with a
54pointer to this structure. Drivers fill the rest of the structure or
55return an &EINVAL; when the index is out of bounds. To enumerate all
56outputs applications shall begin at index zero, incrementing by one
57until the driver returns <errorcode>EINVAL</errorcode>.</para>
58
59 <table frame="none" pgwide="1" id="v4l2-output">
60 <title>struct <structname>v4l2_output</structname></title>
61 <tgroup cols="3">
62 &cs-str;
63 <tbody valign="top">
64 <row>
65 <entry>__u32</entry>
66 <entry><structfield>index</structfield></entry>
67 <entry>Identifies the output, set by the
68application.</entry>
69 </row>
70 <row>
71 <entry>__u8</entry>
72 <entry><structfield>name</structfield>[32]</entry>
73 <entry>Name of the video output, a NUL-terminated ASCII
74string, for example: "Vout". This information is intended for the
75user, preferably the connector label on the device itself.</entry>
76 </row>
77 <row>
78 <entry>__u32</entry>
79 <entry><structfield>type</structfield></entry>
80 <entry>Type of the output, see <xref
81 linkend="output-type" />.</entry>
82 </row>
83 <row>
84 <entry>__u32</entry>
85 <entry><structfield>audioset</structfield></entry>
86 <entry><para>Drivers can enumerate up to 32 video and
87audio outputs. This field shows which audio outputs were
88selectable as the current output if this was the currently selected
89video output. It is a bit mask. The LSB corresponds to audio output 0,
90the MSB to output 31. Any number of bits can be set, or
91none.</para><para>When the driver does not enumerate audio outputs no
92bits must be set. Applications shall not interpret this as lack of
93audio support. Drivers may automatically select audio outputs without
94enumerating them.</para><para>For details on audio outputs and how to
95select the current output see <xref linkend="audio" />.</para></entry>
96 </row>
97 <row>
98 <entry>__u32</entry>
99 <entry><structfield>modulator</structfield></entry>
100 <entry>Output devices can have zero or more RF modulators.
101When the <structfield>type</structfield> is
102<constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> this is an RF
103connector and this field identifies the modulator. It corresponds to
104&v4l2-modulator; field <structfield>index</structfield>. For details
105on modulators see <xref linkend="tuner" />.</entry>
106 </row>
107 <row>
108 <entry>&v4l2-std-id;</entry>
109 <entry><structfield>std</structfield></entry>
110 <entry>Every video output supports one or more different
111video standards. This field is a set of all supported standards. For
112details on video standards and how to switch see <xref
113 linkend="standard" />.</entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>capabilities</structfield></entry>
118 <entry>This field provides capabilities for the
119output. See <xref linkend="output-capabilities" /> for flags.</entry>
120 </row>
121 <row>
122 <entry>__u32</entry>
123 <entry><structfield>reserved</structfield>[3]</entry>
124 <entry>Reserved for future extensions. Drivers must set
125the array to zero.</entry>
126 </row>
127 </tbody>
128 </tgroup>
129 </table>
130
131 <table frame="none" pgwide="1" id="output-type">
132 <title>Output Type</title>
133 <tgroup cols="3">
134 &cs-def;
135 <tbody valign="top">
136 <row>
137 <entry><constant>V4L2_OUTPUT_TYPE_MODULATOR</constant></entry>
138 <entry>1</entry>
139 <entry>This output is an analog TV modulator.</entry>
140 </row>
141 <row>
142 <entry><constant>V4L2_OUTPUT_TYPE_ANALOG</constant></entry>
143 <entry>2</entry>
144 <entry>Analog baseband output, for example Composite /
145CVBS, S-Video, RGB.</entry>
146 </row>
147 <row>
148 <entry><constant>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</constant></entry>
149 <entry>3</entry>
150 <entry>[?]</entry>
151 </row>
152 </tbody>
153 </tgroup>
154 </table>
155
156 <!-- Capabilities flags based on video timings RFC by Muralidharan
157Karicheri, titled RFC (v1.2): V4L - Support for video timings at the
158input/output interface to linux-media@vger.kernel.org on 19 Oct 2009.
159 -->
160 <table frame="none" pgwide="1" id="output-capabilities">
161 <title>Output capabilities</title>
162 <tgroup cols="3">
163 &cs-def;
164 <tbody valign="top">
165 <row>
166 <entry><constant>V4L2_OUT_CAP_PRESETS</constant></entry>
167 <entry>0x00000001</entry>
168 <entry>This output supports setting DV presets by using VIDIOC_S_DV_PRESET.</entry>
169 </row>
170 <row>
171 <entry><constant>V4L2_OUT_CAP_CUSTOM_TIMINGS</constant></entry>
172 <entry>0x00000002</entry>
173 <entry>This output supports setting custom video timings by using VIDIOC_S_DV_TIMINGS.</entry>
174 </row>
175 <row>
176 <entry><constant>V4L2_OUT_CAP_STD</constant></entry>
177 <entry>0x00000004</entry>
178 <entry>This output supports setting the TV standard by using VIDIOC_S_STD.</entry>
179 </row>
180 </tbody>
181 </tgroup>
182 </table>
183
184 </refsect1>
185 <refsect1>
186 &return-value;
187
188 <variablelist>
189 <varlistentry>
190 <term><errorcode>EINVAL</errorcode></term>
191 <listitem>
192 <para>The &v4l2-output; <structfield>index</structfield>
193is out of bounds.</para>
194 </listitem>
195 </varlistentry>
196 </variablelist>
197 </refsect1>
198</refentry>
199
200<!--
201Local Variables:
202mode: sgml
203sgml-parent-document: "v4l2.sgml"
204indent-tabs-mode: nil
205End:
206-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml
new file mode 100644
index 000000000000..95803fe2c8e4
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml
@@ -0,0 +1,391 @@
1<refentry id="vidioc-enumstd">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUMSTD</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUMSTD</refname>
9 <refpurpose>Enumerate supported video standards</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_standard *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_ENUMSTD</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>To query the attributes of a video standard,
52especially a custom (driver defined) one, applications initialize the
53<structfield>index</structfield> field of &v4l2-standard; and call the
54<constant>VIDIOC_ENUMSTD</constant> ioctl with a pointer to this
55structure. Drivers fill the rest of the structure or return an
56&EINVAL; when the index is out of bounds. To enumerate all standards
57applications shall begin at index zero, incrementing by one until the
58driver returns <errorcode>EINVAL</errorcode>. Drivers may enumerate a
59different set of standards after switching the video input or
60output.<footnote>
61 <para>The supported standards may overlap and we need an
62unambiguous set to find the current standard returned by
63<constant>VIDIOC_G_STD</constant>.</para>
64 </footnote></para>
65
66 <table pgwide="1" frame="none" id="v4l2-standard">
67 <title>struct <structname>v4l2_standard</structname></title>
68 <tgroup cols="3">
69 &cs-str;
70 <tbody valign="top">
71 <row>
72 <entry>__u32</entry>
73 <entry><structfield>index</structfield></entry>
74 <entry>Number of the video standard, set by the
75application.</entry>
76 </row>
77 <row>
78 <entry>&v4l2-std-id;</entry>
79 <entry><structfield>id</structfield></entry>
80 <entry>The bits in this field identify the standard as
81one of the common standards listed in <xref linkend="v4l2-std-id" />,
82or if bits 32 to 63 are set as custom standards. Multiple bits can be
83set if the hardware does not distinguish between these standards,
84however separate indices do not indicate the opposite. The
85<structfield>id</structfield> must be unique. No other enumerated
86<structname>v4l2_standard</structname> structure, for this input or
87output anyway, can contain the same set of bits.</entry>
88 </row>
89 <row>
90 <entry>__u8</entry>
91 <entry><structfield>name</structfield>[24]</entry>
92 <entry>Name of the standard, a NUL-terminated ASCII
93string, for example: "PAL-B/G", "NTSC Japan". This information is
94intended for the user.</entry>
95 </row>
96 <row>
97 <entry>&v4l2-fract;</entry>
98 <entry><structfield>frameperiod</structfield></entry>
99 <entry>The frame period (not field period) is numerator
100/ denominator. For example M/NTSC has a frame period of 1001 /
10130000 seconds.</entry>
102 </row>
103 <row>
104 <entry>__u32</entry>
105 <entry><structfield>framelines</structfield></entry>
106 <entry>Total lines per frame including blanking,
107e.&nbsp;g. 625 for B/PAL.</entry>
108 </row>
109 <row>
110 <entry>__u32</entry>
111 <entry><structfield>reserved</structfield>[4]</entry>
112 <entry>Reserved for future extensions. Drivers must set
113the array to zero.</entry>
114 </row>
115 </tbody>
116 </tgroup>
117 </table>
118
119 <table pgwide="1" frame="none" id="v4l2-fract">
120 <title>struct <structname>v4l2_fract</structname></title>
121 <tgroup cols="3">
122 &cs-str;
123 <tbody valign="top">
124 <row>
125 <entry>__u32</entry>
126 <entry><structfield>numerator</structfield></entry>
127 <entry></entry>
128 </row>
129 <row>
130 <entry>__u32</entry>
131 <entry><structfield>denominator</structfield></entry>
132 <entry></entry>
133 </row>
134 </tbody>
135 </tgroup>
136 </table>
137
138 <table pgwide="1" frame="none" id="v4l2-std-id">
139 <title>typedef <structname>v4l2_std_id</structname></title>
140 <tgroup cols="3">
141 &cs-str;
142 <tbody valign="top">
143 <row>
144 <entry>__u64</entry>
145 <entry><structfield>v4l2_std_id</structfield></entry>
146 <entry>This type is a set, each bit representing another
147video standard as listed below and in <xref
148linkend="video-standards" />. The 32 most significant bits are reserved
149for custom (driver defined) video standards.</entry>
150 </row>
151 </tbody>
152 </tgroup>
153 </table>
154
155 <para><programlisting>
156#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
157#define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
158#define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
159#define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
160#define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
161#define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
162#define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
163#define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
164
165#define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
166#define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
167#define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
168#define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
169</programlisting></para><para><constant>V4L2_STD_PAL_60</constant> is
170a hybrid standard with 525 lines, 60 Hz refresh rate, and PAL color
171modulation with a 4.43 MHz color subcarrier. Some PAL video recorders
172can play back NTSC tapes in this mode for display on a 50/60 Hz agnostic
173PAL TV.</para><para><programlisting>
174#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
175#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
176#define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
177</programlisting></para><para><constant>V4L2_STD_NTSC_443</constant>
178is a hybrid standard with 525 lines, 60 Hz refresh rate, and NTSC
179color modulation with a 4.43 MHz color
180subcarrier.</para><para><programlisting>
181#define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
182
183#define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
184#define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
185#define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
186#define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
187#define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
188#define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
189#define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
190#define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
191
192/* ATSC/HDTV */
193#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
194#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
195</programlisting></para><para><!-- ATSC proposal by Mark McClelland,
196video4linux-list@redhat.com on 17 Oct 2002
197--><constant>V4L2_STD_ATSC_8_VSB</constant> and
198<constant>V4L2_STD_ATSC_16_VSB</constant> are U.S. terrestrial digital
199TV standards. Presently the V4L2 API does not support digital TV. See
200also the Linux DVB API at <ulink
201url="http://linuxtv.org">http://linuxtv.org</ulink>.</para>
202<para><programlisting>
203#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\
204 V4L2_STD_PAL_B1 |\
205 V4L2_STD_PAL_G)
206#define V4L2_STD_B (V4L2_STD_PAL_B |\
207 V4L2_STD_PAL_B1 |\
208 V4L2_STD_SECAM_B)
209#define V4L2_STD_GH (V4L2_STD_PAL_G |\
210 V4L2_STD_PAL_H |\
211 V4L2_STD_SECAM_G |\
212 V4L2_STD_SECAM_H)
213#define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\
214 V4L2_STD_PAL_D1 |\
215 V4L2_STD_PAL_K)
216#define V4L2_STD_PAL (V4L2_STD_PAL_BG |\
217 V4L2_STD_PAL_DK |\
218 V4L2_STD_PAL_H |\
219 V4L2_STD_PAL_I)
220#define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\
221 V4L2_STD_NTSC_M_JP |\
222 V4L2_STD_NTSC_M_KR)
223#define V4L2_STD_MN (V4L2_STD_PAL_M |\
224 V4L2_STD_PAL_N |\
225 V4L2_STD_PAL_Nc |\
226 V4L2_STD_NTSC)
227#define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\
228 V4L2_STD_SECAM_K |\
229 V4L2_STD_SECAM_K1)
230#define V4L2_STD_DK (V4L2_STD_PAL_DK |\
231 V4L2_STD_SECAM_DK)
232
233#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\
234 V4L2_STD_SECAM_G |\
235 V4L2_STD_SECAM_H |\
236 V4L2_STD_SECAM_DK |\
237 V4L2_STD_SECAM_L |\
238 V4L2_STD_SECAM_LC)
239
240#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\
241 V4L2_STD_PAL_60 |\
242 V4L2_STD_NTSC |\
243 V4L2_STD_NTSC_443)
244#define V4L2_STD_625_50 (V4L2_STD_PAL |\
245 V4L2_STD_PAL_N |\
246 V4L2_STD_PAL_Nc |\
247 V4L2_STD_SECAM)
248
249#define V4L2_STD_UNKNOWN 0
250#define V4L2_STD_ALL (V4L2_STD_525_60 |\
251 V4L2_STD_625_50)
252</programlisting></para>
253
254 <table pgwide="1" id="video-standards" orient="land">
255 <title>Video Standards (based on [<xref linkend="itu470" />])</title>
256 <tgroup cols="12" colsep="1" rowsep="1" align="center">
257 <colspec colname="c1" align="left" />
258 <colspec colname="c2" />
259 <colspec colname="c3" />
260 <colspec colname="c4" />
261 <colspec colname="c5" />
262 <colspec colnum="7" colname="c7" />
263 <colspec colnum="9" colname="c9" />
264 <colspec colnum="12" colname="c12" />
265 <spanspec namest="c2" nameend="c3" spanname="m" align="center" />
266 <spanspec namest="c4" nameend="c12" spanname="x" align="center" />
267 <spanspec namest="c5" nameend="c7" spanname="b" align="center" />
268 <spanspec namest="c9" nameend="c12" spanname="s" align="center" />
269 <thead>
270 <row>
271 <entry>Characteristics</entry>
272 <entry><para>M/NTSC<footnote><para>Japan uses a standard
273similar to M/NTSC
274(V4L2_STD_NTSC_M_JP).</para></footnote></para></entry>
275 <entry>M/PAL</entry>
276 <entry><para>N/PAL<footnote><para> The values in
277brackets apply to the combination N/PAL a.k.a.
278N<subscript>C</subscript> used in Argentina
279(V4L2_STD_PAL_Nc).</para></footnote></para></entry>
280 <entry align="center">B, B1, G/PAL</entry>
281 <entry align="center">D, D1, K/PAL</entry>
282 <entry align="center">H/PAL</entry>
283 <entry align="center">I/PAL</entry>
284 <entry align="center">B, G/SECAM</entry>
285 <entry align="center">D, K/SECAM</entry>
286 <entry align="center">K1/SECAM</entry>
287 <entry align="center">L/SECAM</entry>
288 </row>
289 </thead>
290 <tbody valign="top">
291 <row>
292 <entry>Frame lines</entry>
293 <entry spanname="m">525</entry>
294 <entry spanname="x">625</entry>
295 </row>
296 <row>
297 <entry>Frame period (s)</entry>
298 <entry spanname="m">1001/30000</entry>
299 <entry spanname="x">1/25</entry>
300 </row>
301 <row>
302 <entry>Chrominance sub-carrier frequency (Hz)</entry>
303 <entry>3579545 &plusmn;&nbsp;10</entry>
304 <entry>3579611.49 &plusmn;&nbsp;10</entry>
305 <entry>4433618.75 &plusmn;&nbsp;5 (3582056.25
306&plusmn;&nbsp;5)</entry>
307 <entry spanname="b">4433618.75 &plusmn;&nbsp;5</entry>
308 <entry>4433618.75 &plusmn;&nbsp;1</entry>
309 <entry spanname="s">f<subscript>OR</subscript>&nbsp;=
3104406250 &plusmn;&nbsp;2000, f<subscript>OB</subscript>&nbsp;= 4250000
311&plusmn;&nbsp;2000</entry>
312 </row>
313 <row>
314 <entry>Nominal radio-frequency channel bandwidth
315(MHz)</entry>
316 <entry>6</entry>
317 <entry>6</entry>
318 <entry>6</entry>
319 <entry>B: 7; B1, G: 8</entry>
320 <entry>8</entry>
321 <entry>8</entry>
322 <entry>8</entry>
323 <entry>8</entry>
324 <entry>8</entry>
325 <entry>8</entry>
326 <entry>8</entry>
327 </row>
328 <row>
329 <entry>Sound carrier relative to vision carrier
330(MHz)</entry>
331 <entry>+&nbsp;4.5</entry>
332 <entry>+&nbsp;4.5</entry>
333 <entry>+&nbsp;4.5</entry>
334 <entry><para>+&nbsp;5.5 &plusmn;&nbsp;0.001
335<footnote><para>In the Federal Republic of Germany, Austria, Italy,
336the Netherlands, Slovakia and Switzerland a system of two sound
337carriers is used, the frequency of the second carrier being
338242.1875&nbsp;kHz above the frequency of the first sound carrier. For
339stereophonic sound transmissions a similar system is used in
340Australia.</para></footnote> <footnote><para>New Zealand uses a sound
341carrier displaced 5.4996 &plusmn;&nbsp;0.0005 MHz from the vision
342carrier.</para></footnote> <footnote><para>In Denmark, Finland, New
343Zealand, Sweden and Spain a system of two sound carriers is used. In
344Iceland, Norway and Poland the same system is being introduced. The
345second carrier is 5.85&nbsp;MHz above the vision carrier and is DQPSK
346modulated with 728&nbsp;kbit/s sound and data multiplex. (NICAM
347system)</para></footnote> <footnote><para>In the United Kingdom, a
348system of two sound carriers is used. The second sound carrier is
3496.552&nbsp;MHz above the vision carrier and is DQPSK modulated with a
350728&nbsp;kbit/s sound and data multiplex able to carry two sound
351channels. (NICAM system)</para></footnote></para></entry>
352 <entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
353 <entry>+&nbsp;5.5</entry>
354 <entry>+&nbsp;5.9996 &plusmn;&nbsp;0.0005</entry>
355 <entry>+&nbsp;5.5 &plusmn;&nbsp;0.001</entry>
356 <entry>+&nbsp;6.5 &plusmn;&nbsp;0.001</entry>
357 <entry>+&nbsp;6.5</entry>
358 <entry><para>+&nbsp;6.5 <footnote><para>In France, a
359digital carrier 5.85 MHz away from the vision carrier may be used in
360addition to the main sound carrier. It is modulated in differentially
361encoded QPSK with a 728 kbit/s sound and data multiplexer capable of
362carrying two sound channels. (NICAM
363system)</para></footnote></para></entry>
364 </row>
365 </tbody>
366 </tgroup>
367 </table>
368 </refsect1>
369
370 <refsect1>
371 &return-value;
372
373 <variablelist>
374 <varlistentry>
375 <term><errorcode>EINVAL</errorcode></term>
376 <listitem>
377 <para>The &v4l2-standard; <structfield>index</structfield>
378is out of bounds.</para>
379 </listitem>
380 </varlistentry>
381 </variablelist>
382 </refsect1>
383</refentry>
384
385<!--
386Local Variables:
387mode: sgml
388sgml-parent-document: "v4l2.sgml"
389indent-tabs-mode: nil
390End:
391-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-audio.xml b/Documentation/DocBook/media/v4l/vidioc-g-audio.xml
new file mode 100644
index 000000000000..65361a8c2b05
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-audio.xml
@@ -0,0 +1,188 @@
1<refentry id="vidioc-g-audio">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_AUDIO</refname>
9 <refname>VIDIOC_S_AUDIO</refname>
10 <refpurpose>Query or select the current audio input and its
11attributes</refpurpose>
12 </refnamediv>
13
14 <refsynopsisdiv>
15 <funcsynopsis>
16 <funcprototype>
17 <funcdef>int <function>ioctl</function></funcdef>
18 <paramdef>int <parameter>fd</parameter></paramdef>
19 <paramdef>int <parameter>request</parameter></paramdef>
20 <paramdef>struct v4l2_audio *<parameter>argp</parameter></paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 <funcsynopsis>
24 <funcprototype>
25 <funcdef>int <function>ioctl</function></funcdef>
26 <paramdef>int <parameter>fd</parameter></paramdef>
27 <paramdef>int <parameter>request</parameter></paramdef>
28 <paramdef>const struct v4l2_audio *<parameter>argp</parameter></paramdef>
29 </funcprototype>
30 </funcsynopsis>
31 </refsynopsisdiv>
32
33 <refsect1>
34 <title>Arguments</title>
35
36 <variablelist>
37 <varlistentry>
38 <term><parameter>fd</parameter></term>
39 <listitem>
40 <para>&fd;</para>
41 </listitem>
42 </varlistentry>
43 <varlistentry>
44 <term><parameter>request</parameter></term>
45 <listitem>
46 <para>VIDIOC_G_AUDIO, VIDIOC_S_AUDIO</para>
47 </listitem>
48 </varlistentry>
49 <varlistentry>
50 <term><parameter>argp</parameter></term>
51 <listitem>
52 <para></para>
53 </listitem>
54 </varlistentry>
55 </variablelist>
56 </refsect1>
57
58 <refsect1>
59 <title>Description</title>
60
61 <para>To query the current audio input applications zero out the
62<structfield>reserved</structfield> array of a &v4l2-audio;
63and call the <constant>VIDIOC_G_AUDIO</constant> ioctl with a pointer
64to this structure. Drivers fill the rest of the structure or return an
65&EINVAL; when the device has no audio inputs, or none which combine
66with the current video input.</para>
67
68 <para>Audio inputs have one writable property, the audio mode. To
69select the current audio input <emphasis>and</emphasis> change the
70audio mode, applications initialize the
71<structfield>index</structfield> and <structfield>mode</structfield>
72fields, and the
73<structfield>reserved</structfield> array of a
74<structname>v4l2_audio</structname> structure and call the
75<constant>VIDIOC_S_AUDIO</constant> ioctl. Drivers may switch to a
76different audio mode if the request cannot be satisfied. However, this
77is a write-only ioctl, it does not return the actual new audio
78mode.</para>
79
80 <table pgwide="1" frame="none" id="v4l2-audio">
81 <title>struct <structname>v4l2_audio</structname></title>
82 <tgroup cols="3">
83 &cs-str;
84 <tbody valign="top">
85 <row>
86 <entry>__u32</entry>
87 <entry><structfield>index</structfield></entry>
88 <entry>Identifies the audio input, set by the
89driver or application.</entry>
90 </row>
91 <row>
92 <entry>__u8</entry>
93 <entry><structfield>name</structfield>[32]</entry>
94 <entry>Name of the audio input, a NUL-terminated ASCII
95string, for example: "Line In". This information is intended for the
96user, preferably the connector label on the device itself.</entry>
97 </row>
98 <row>
99 <entry>__u32</entry>
100 <entry><structfield>capability</structfield></entry>
101 <entry>Audio capability flags, see <xref
102 linkend="audio-capability" />.</entry>
103 </row>
104 <row>
105 <entry>__u32</entry>
106 <entry><structfield>mode</structfield></entry>
107 <entry>Audio mode flags set by drivers and applications (on
108 <constant>VIDIOC_S_AUDIO</constant> ioctl), see <xref linkend="audio-mode" />.</entry>
109 </row>
110 <row>
111 <entry>__u32</entry>
112 <entry><structfield>reserved</structfield>[2]</entry>
113 <entry>Reserved for future extensions. Drivers and
114applications must set the array to zero.</entry>
115 </row>
116 </tbody>
117 </tgroup>
118 </table>
119
120 <table pgwide="1" frame="none" id="audio-capability">
121 <title>Audio Capability Flags</title>
122 <tgroup cols="3">
123 &cs-def;
124 <tbody valign="top">
125 <row>
126 <entry><constant>V4L2_AUDCAP_STEREO</constant></entry>
127 <entry>0x00001</entry>
128 <entry>This is a stereo input. The flag is intended to
129automatically disable stereo recording etc. when the signal is always
130monaural. The API provides no means to detect if stereo is
131<emphasis>received</emphasis>, unless the audio input belongs to a
132tuner.</entry>
133 </row>
134 <row>
135 <entry><constant>V4L2_AUDCAP_AVL</constant></entry>
136 <entry>0x00002</entry>
137 <entry>Automatic Volume Level mode is supported.</entry>
138 </row>
139 </tbody>
140 </tgroup>
141 </table>
142
143 <table pgwide="1" frame="none" id="audio-mode">
144 <title>Audio Mode Flags</title>
145 <tgroup cols="3">
146 &cs-def;
147 <tbody valign="top">
148 <row>
149 <entry><constant>V4L2_AUDMODE_AVL</constant></entry>
150 <entry>0x00001</entry>
151 <entry>AVL mode is on.</entry>
152 </row>
153 </tbody>
154 </tgroup>
155 </table>
156 </refsect1>
157
158 <refsect1>
159 &return-value;
160
161 <variablelist>
162 <varlistentry>
163 <term><errorcode>EINVAL</errorcode></term>
164 <listitem>
165 <para>No audio inputs combine with the current video input,
166or the number of the selected audio input is out of bounds or it does
167not combine, or there are no audio inputs at all and the ioctl is not
168supported.</para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
172 <term><errorcode>EBUSY</errorcode></term>
173 <listitem>
174 <para>I/O is in progress, the input cannot be
175switched.</para>
176 </listitem>
177 </varlistentry>
178 </variablelist>
179 </refsect1>
180</refentry>
181
182<!--
183Local Variables:
184mode: sgml
185sgml-parent-document: "v4l2.sgml"
186indent-tabs-mode: nil
187End:
188-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml b/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml
new file mode 100644
index 000000000000..3632730c5c6e
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-audioout.xml
@@ -0,0 +1,154 @@
1<refentry id="vidioc-g-audioout">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_AUDOUT, VIDIOC_S_AUDOUT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_AUDOUT</refname>
9 <refname>VIDIOC_S_AUDOUT</refname>
10 <refpurpose>Query or select the current audio output</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_audioout *<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_audioout *<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_G_AUDOUT, VIDIOC_S_AUDOUT</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 <para>To query the current audio output applications zero out the
61<structfield>reserved</structfield> array of a &v4l2-audioout; and
62call the <constant>VIDIOC_G_AUDOUT</constant> ioctl with a pointer
63to this structure. Drivers fill the rest of the structure or return an
64&EINVAL; when the device has no audio inputs, or none which combine
65with the current video output.</para>
66
67 <para>Audio outputs have no writable properties. Nevertheless, to
68select the current audio output applications can initialize the
69<structfield>index</structfield> field and
70<structfield>reserved</structfield> array (which in the future may
71contain writable properties) of a
72<structname>v4l2_audioout</structname> structure and call the
73<constant>VIDIOC_S_AUDOUT</constant> ioctl. Drivers switch to the
74requested output or return the &EINVAL; when the index is out of
75bounds. This is a write-only ioctl, it does not return the current
76audio output attributes as <constant>VIDIOC_G_AUDOUT</constant>
77does.</para>
78
79 <para>Note connectors on a TV card to loop back the received audio
80signal to a sound card are not audio outputs in this sense.</para>
81
82 <table pgwide="1" frame="none" id="v4l2-audioout">
83 <title>struct <structname>v4l2_audioout</structname></title>
84 <tgroup cols="3">
85 &cs-str;
86 <tbody valign="top">
87 <row>
88 <entry>__u32</entry>
89 <entry><structfield>index</structfield></entry>
90 <entry>Identifies the audio output, set by the
91driver or application.</entry>
92 </row>
93 <row>
94 <entry>__u8</entry>
95 <entry><structfield>name</structfield>[32]</entry>
96 <entry>Name of the audio output, a NUL-terminated ASCII
97string, for example: "Line Out". This information is intended for the
98user, preferably the connector label on the device itself.</entry>
99 </row>
100 <row>
101 <entry>__u32</entry>
102 <entry><structfield>capability</structfield></entry>
103 <entry>Audio capability flags, none defined yet. Drivers
104must set this field to zero.</entry>
105 </row>
106 <row>
107 <entry>__u32</entry>
108 <entry><structfield>mode</structfield></entry>
109 <entry>Audio mode, none defined yet. Drivers and
110applications (on <constant>VIDIOC_S_AUDOUT</constant>) must set this
111field to zero.</entry>
112 </row>
113 <row>
114 <entry>__u32</entry>
115 <entry><structfield>reserved</structfield>[2]</entry>
116 <entry>Reserved for future extensions. Drivers and
117applications must set the array to zero.</entry>
118 </row>
119 </tbody>
120 </tgroup>
121 </table>
122 </refsect1>
123
124 <refsect1>
125 &return-value;
126
127 <variablelist>
128 <varlistentry>
129 <term><errorcode>EINVAL</errorcode></term>
130 <listitem>
131 <para>No audio outputs combine with the current video
132output, or the number of the selected audio output is out of bounds or
133it does not combine, or there are no audio outputs at all and the
134ioctl is not supported.</para>
135 </listitem>
136 </varlistentry>
137 <varlistentry>
138 <term><errorcode>EBUSY</errorcode></term>
139 <listitem>
140 <para>I/O is in progress, the output cannot be
141switched.</para>
142 </listitem>
143 </varlistentry>
144 </variablelist>
145 </refsect1>
146</refentry>
147
148<!--
149Local Variables:
150mode: sgml
151sgml-parent-document: "v4l2.sgml"
152indent-tabs-mode: nil
153End:
154-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml
new file mode 100644
index 000000000000..d235b1dedbed
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml
@@ -0,0 +1,143 @@
1<refentry id="vidioc-g-crop">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_CROP</refname>
9 <refname>VIDIOC_S_CROP</refname>
10 <refpurpose>Get or set the current cropping rectangle</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_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_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_G_CROP, VIDIOC_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 <para>To query the cropping rectangle size and position
61applications set the <structfield>type</structfield> field of a
62<structname>v4l2_crop</structname> structure to the respective buffer
63(stream) type and call the <constant>VIDIOC_G_CROP</constant> ioctl
64with a pointer to this structure. The driver fills the rest of the
65structure or returns the &EINVAL; if cropping is not supported.</para>
66
67 <para>To change the cropping rectangle applications initialize the
68<structfield>type</structfield> and &v4l2-rect; substructure named
69<structfield>c</structfield> of a v4l2_crop structure and call the
70<constant>VIDIOC_S_CROP</constant> ioctl with a pointer to this
71structure.</para>
72
73 <para>The driver first adjusts the requested dimensions against
74hardware limits, &ie; the bounds given by the capture/output window,
75and it rounds to the closest possible values of horizontal and
76vertical offset, width and height. In particular the driver must round
77the vertical offset of the cropping rectangle to frame lines modulo
78two, such that the field order cannot be confused.</para>
79
80 <para>Second the driver adjusts the image size (the opposite
81rectangle of the scaling process, source or target depending on the
82data direction) to the closest size possible while maintaining the
83current horizontal and vertical scaling factor.</para>
84
85 <para>Finally the driver programs the hardware with the actual
86cropping and image parameters. <constant>VIDIOC_S_CROP</constant> is a
87write-only ioctl, it does not return the actual parameters. To query
88them applications must call <constant>VIDIOC_G_CROP</constant> and
89&VIDIOC-G-FMT;. When the parameters are unsuitable the application may
90modify the cropping or image parameters and repeat the cycle until
91satisfactory parameters have been negotiated.</para>
92
93 <para>When cropping is not supported then no parameters are
94changed and <constant>VIDIOC_S_CROP</constant> returns the
95&EINVAL;.</para>
96
97 <table pgwide="1" frame="none" id="v4l2-crop">
98 <title>struct <structname>v4l2_crop</structname></title>
99 <tgroup cols="3">
100 &cs-str;
101 <tbody valign="top">
102 <row>
103 <entry>&v4l2-buf-type;</entry>
104 <entry><structfield>type</structfield></entry>
105 <entry>Type of the data stream, set by the application.
106Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>,
107<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
108<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
109defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
110and higher.</entry>
111 </row>
112 <row>
113 <entry>&v4l2-rect;</entry>
114 <entry><structfield>c</structfield></entry>
115 <entry>Cropping rectangle. The same co-ordinate system as
116for &v4l2-cropcap; <structfield>bounds</structfield> is used.</entry>
117 </row>
118 </tbody>
119 </tgroup>
120 </table>
121 </refsect1>
122
123 <refsect1>
124 &return-value;
125
126 <variablelist>
127 <varlistentry>
128 <term><errorcode>EINVAL</errorcode></term>
129 <listitem>
130 <para>Cropping is not supported.</para>
131 </listitem>
132 </varlistentry>
133 </variablelist>
134 </refsect1>
135</refentry>
136
137<!--
138Local Variables:
139mode: sgml
140sgml-parent-document: "v4l2.sgml"
141indent-tabs-mode: nil
142End:
143-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml b/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml
new file mode 100644
index 000000000000..8b5e6ff7f3df
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-ctrl.xml
@@ -0,0 +1,130 @@
1<refentry id="vidioc-g-ctrl">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_CTRL</refname>
9 <refname>VIDIOC_S_CTRL</refname>
10 <refpurpose>Get or set the value of a control</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_control
20*<parameter>argp</parameter></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_G_CTRL, VIDIOC_S_CTRL</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 <para>To get the current value of a control applications
54initialize the <structfield>id</structfield> field of a struct
55<structname>v4l2_control</structname> and call the
56<constant>VIDIOC_G_CTRL</constant> ioctl with a pointer to this
57structure. To change the value of a control applications initialize
58the <structfield>id</structfield> and <structfield>value</structfield>
59fields of a struct <structname>v4l2_control</structname> and call the
60<constant>VIDIOC_S_CTRL</constant> ioctl.</para>
61
62 <para>When the <structfield>id</structfield> is invalid drivers
63return an &EINVAL;. When the <structfield>value</structfield> is out
64of bounds drivers can choose to take the closest valid value or return
65an &ERANGE;, whatever seems more appropriate. However,
66<constant>VIDIOC_S_CTRL</constant> is a write-only ioctl, it does not
67return the actual new value.</para>
68
69 <para>These ioctls work only with user controls. For other
70control classes the &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS; or
71&VIDIOC-TRY-EXT-CTRLS; must be used.</para>
72
73 <table pgwide="1" frame="none" id="v4l2-control">
74 <title>struct <structname>v4l2_control</structname></title>
75 <tgroup cols="3">
76 &cs-str;
77 <tbody valign="top">
78 <row>
79 <entry>__u32</entry>
80 <entry><structfield>id</structfield></entry>
81 <entry>Identifies the control, set by the
82application.</entry>
83 </row>
84 <row>
85 <entry>__s32</entry>
86 <entry><structfield>value</structfield></entry>
87 <entry>New value or current value.</entry>
88 </row>
89 </tbody>
90 </tgroup>
91 </table>
92 </refsect1>
93
94 <refsect1>
95 &return-value;
96
97 <variablelist>
98 <varlistentry>
99 <term><errorcode>EINVAL</errorcode></term>
100 <listitem>
101 <para>The &v4l2-control; <structfield>id</structfield> is
102invalid.</para>
103 </listitem>
104 </varlistentry>
105 <varlistentry>
106 <term><errorcode>ERANGE</errorcode></term>
107 <listitem>
108 <para>The &v4l2-control; <structfield>value</structfield>
109is out of bounds.</para>
110 </listitem>
111 </varlistentry>
112 <varlistentry>
113 <term><errorcode>EBUSY</errorcode></term>
114 <listitem>
115 <para>The control is temporarily not changeable, possibly
116because another applications took over control of the device function
117this control belongs to.</para>
118 </listitem>
119 </varlistentry>
120 </variablelist>
121 </refsect1>
122</refentry>
123
124<!--
125Local Variables:
126mode: sgml
127sgml-parent-document: "v4l2.sgml"
128indent-tabs-mode: nil
129End:
130-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml
new file mode 100644
index 000000000000..d733721a7519
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml
@@ -0,0 +1,110 @@
1<refentry id="vidioc-g-dv-preset">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_DV_PRESET</refname>
9 <refname>VIDIOC_S_DV_PRESET</refname>
10 <refpurpose>Query or select the DV preset of the current input or output</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_dv_preset *<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_G_DV_PRESET, VIDIOC_S_DV_PRESET</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 and select the current DV preset, applications
52use the <constant>VIDIOC_G_DV_PRESET</constant> and <constant>VIDIOC_S_DV_PRESET</constant>
53ioctls which take a pointer to a &v4l2-dv-preset; type as argument.
54Applications must zero the reserved array in &v4l2-dv-preset;.
55<constant>VIDIOC_G_DV_PRESET</constant> returns a dv preset in the field
56<structfield>preset</structfield> of &v4l2-dv-preset;.</para>
57
58 <para><constant>VIDIOC_S_DV_PRESET</constant> accepts a pointer to a &v4l2-dv-preset;
59that has the preset value to be set. Applications must zero the reserved array in &v4l2-dv-preset;.
60If the preset is not supported, it returns an &EINVAL; </para>
61 </refsect1>
62
63 <refsect1>
64 &return-value;
65
66 <variablelist>
67 <varlistentry>
68 <term><errorcode>EINVAL</errorcode></term>
69 <listitem>
70 <para>This ioctl is not supported, or the
71<constant>VIDIOC_S_DV_PRESET</constant>,<constant>VIDIOC_S_DV_PRESET</constant> parameter was unsuitable.</para>
72 </listitem>
73 </varlistentry>
74 <varlistentry>
75 <term><errorcode>EBUSY</errorcode></term>
76 <listitem>
77 <para>The device is busy and therefore can not change the preset.</para>
78 </listitem>
79 </varlistentry>
80 </variablelist>
81
82 <table pgwide="1" frame="none" id="v4l2-dv-preset">
83 <title>struct <structname>v4l2_dv_preset</structname></title>
84 <tgroup cols="3">
85 &cs-str;
86 <tbody valign="top">
87 <row>
88 <entry>__u32</entry>
89 <entry><structfield>preset</structfield></entry>
90 <entry>Preset value to represent the digital video timings</entry>
91 </row>
92 <row>
93 <entry>__u32</entry>
94 <entry><structfield>reserved[4]</structfield></entry>
95 <entry>Reserved fields for future use</entry>
96 </row>
97 </tbody>
98 </tgroup>
99 </table>
100
101 </refsect1>
102</refentry>
103
104<!--
105Local Variables:
106mode: sgml
107sgml-parent-document: "v4l2.sgml"
108indent-tabs-mode: nil
109End:
110-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
new file mode 100644
index 000000000000..d5ec6abf0ce2
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
@@ -0,0 +1,223 @@
1<refentry id="vidioc-g-dv-timings">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_DV_TIMINGS</refname>
9 <refname>VIDIOC_S_DV_TIMINGS</refname>
10 <refpurpose>Get or set custom DV timings for input or output</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_dv_timings *<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_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS</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 set custom DV timings for the input or output, applications use the
52<constant>VIDIOC_S_DV_TIMINGS</constant> ioctl and to get the current custom timings,
53applications use the <constant>VIDIOC_G_DV_TIMINGS</constant> ioctl. The detailed timing
54information is filled in using the structure &v4l2-dv-timings;. These ioctls take
55a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not supported
56or the timing values are not correct, the driver returns &EINVAL;.</para>
57 </refsect1>
58
59 <refsect1>
60 &return-value;
61
62 <variablelist>
63 <varlistentry>
64 <term><errorcode>EINVAL</errorcode></term>
65 <listitem>
66 <para>This ioctl is not supported, or the
67<constant>VIDIOC_S_DV_TIMINGS</constant> parameter was unsuitable.</para>
68 </listitem>
69 </varlistentry>
70 <varlistentry>
71 <term><errorcode>EBUSY</errorcode></term>
72 <listitem>
73 <para>The device is busy and therefore can not change the timings.</para>
74 </listitem>
75 </varlistentry>
76 </variablelist>
77
78 <table pgwide="1" frame="none" id="v4l2-bt-timings">
79 <title>struct <structname>v4l2_bt_timings</structname></title>
80 <tgroup cols="3">
81 &cs-str;
82 <tbody valign="top">
83 <row>
84 <entry>__u32</entry>
85 <entry><structfield>width</structfield></entry>
86 <entry>Width of the active video in pixels</entry>
87 </row>
88 <row>
89 <entry>__u32</entry>
90 <entry><structfield>height</structfield></entry>
91 <entry>Height of the active video in lines</entry>
92 </row>
93 <row>
94 <entry>__u32</entry>
95 <entry><structfield>interlaced</structfield></entry>
96 <entry>Progressive (0) or interlaced (1)</entry>
97 </row>
98 <row>
99 <entry>__u32</entry>
100 <entry><structfield>polarities</structfield></entry>
101 <entry>This is a bit mask that defines polarities of sync signals.
102bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_HSYNC_POS_POL) is for horizontal sync polarity. If the bit is set
103(1) it is positive polarity and if is cleared (0), it is negative polarity.</entry>
104 </row>
105 <row>
106 <entry>__u64</entry>
107 <entry><structfield>pixelclock</structfield></entry>
108 <entry>Pixel clock in Hz. Ex. 74.25MHz->74250000</entry>
109 </row>
110 <row>
111 <entry>__u32</entry>
112 <entry><structfield>hfrontporch</structfield></entry>
113 <entry>Horizontal front porch in pixels</entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>hsync</structfield></entry>
118 <entry>Horizontal sync length in pixels</entry>
119 </row>
120 <row>
121 <entry>__u32</entry>
122 <entry><structfield>hbackporch</structfield></entry>
123 <entry>Horizontal back porch in pixels</entry>
124 </row>
125 <row>
126 <entry>__u32</entry>
127 <entry><structfield>vfrontporch</structfield></entry>
128 <entry>Vertical front porch in lines</entry>
129 </row>
130 <row>
131 <entry>__u32</entry>
132 <entry><structfield>vsync</structfield></entry>
133 <entry>Vertical sync length in lines</entry>
134 </row>
135 <row>
136 <entry>__u32</entry>
137 <entry><structfield>vbackporch</structfield></entry>
138 <entry>Vertical back porch in lines</entry>
139 </row>
140 <row>
141 <entry>__u32</entry>
142 <entry><structfield>il_vfrontporch</structfield></entry>
143 <entry>Vertical front porch in lines for bottom field of interlaced field formats</entry>
144 </row>
145 <row>
146 <entry>__u32</entry>
147 <entry><structfield>il_vsync</structfield></entry>
148 <entry>Vertical sync length in lines for bottom field of interlaced field formats</entry>
149 </row>
150 <row>
151 <entry>__u32</entry>
152 <entry><structfield>il_vbackporch</structfield></entry>
153 <entry>Vertical back porch in lines for bottom field of interlaced field formats</entry>
154 </row>
155 </tbody>
156 </tgroup>
157 </table>
158
159 <table pgwide="1" frame="none" id="v4l2-dv-timings">
160 <title>struct <structname>v4l2_dv_timings</structname></title>
161 <tgroup cols="4">
162 &cs-str;
163 <tbody valign="top">
164 <row>
165 <entry>__u32</entry>
166 <entry><structfield>type</structfield></entry>
167 <entry></entry>
168 <entry>Type of DV timings as listed in <xref linkend="dv-timing-types"/>.</entry>
169 </row>
170 <row>
171 <entry>union</entry>
172 <entry><structfield></structfield></entry>
173 <entry></entry>
174 </row>
175 <row>
176 <entry></entry>
177 <entry>&v4l2-bt-timings;</entry>
178 <entry><structfield>bt</structfield></entry>
179 <entry>Timings defined by BT.656/1120 specifications</entry>
180 </row>
181 <row>
182 <entry></entry>
183 <entry>__u32</entry>
184 <entry><structfield>reserved</structfield>[32]</entry>
185 <entry></entry>
186 </row>
187 </tbody>
188 </tgroup>
189 </table>
190
191 <table pgwide="1" frame="none" id="dv-timing-types">
192 <title>DV Timing types</title>
193 <tgroup cols="3">
194 &cs-str;
195 <tbody valign="top">
196 <row>
197 <entry>Timing type</entry>
198 <entry>value</entry>
199 <entry>Description</entry>
200 </row>
201 <row>
202 <entry></entry>
203 <entry></entry>
204 <entry></entry>
205 </row>
206 <row>
207 <entry>V4L2_DV_BT_656_1120</entry>
208 <entry>0</entry>
209 <entry>BT.656/1120 timings</entry>
210 </row>
211 </tbody>
212 </tgroup>
213 </table>
214 </refsect1>
215</refentry>
216
217<!--
218Local Variables:
219mode: sgml
220sgml-parent-document: "v4l2.sgml"
221indent-tabs-mode: nil
222End:
223-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml
new file mode 100644
index 000000000000..9f242e4b2948
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml
@@ -0,0 +1,213 @@
1<refentry id="vidioc-g-enc-index">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_ENC_INDEX</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_ENC_INDEX</refname>
9 <refpurpose>Get meta data about a compressed video stream</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_enc_idx *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_G_ENC_INDEX</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <note>
52 <title>Experimental</title>
53
54 <para>This is an <link linkend="experimental">experimental</link>
55interface and may change in the future.</para>
56 </note>
57
58 <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides
59meta data about a compressed video stream the same or another
60application currently reads from the driver, which is useful for
61random access into the stream without decoding it.</para>
62
63 <para>To read the data applications must call
64<constant>VIDIOC_G_ENC_INDEX</constant> with a pointer to a
65&v4l2-enc-idx;. On success the driver fills the
66<structfield>entry</structfield> array, stores the number of elements
67written in the <structfield>entries</structfield> field, and
68initializes the <structfield>entries_cap</structfield> field.</para>
69
70 <para>Each element of the <structfield>entry</structfield> array
71contains meta data about one picture. A
72<constant>VIDIOC_G_ENC_INDEX</constant> call reads up to
73<constant>V4L2_ENC_IDX_ENTRIES</constant> entries from a driver
74buffer, which can hold up to <structfield>entries_cap</structfield>
75entries. This number can be lower or higher than
76<constant>V4L2_ENC_IDX_ENTRIES</constant>, but not zero. When the
77application fails to read the meta data in time the oldest entries
78will be lost. When the buffer is empty or no capturing/encoding is in
79progress, <structfield>entries</structfield> will be zero.</para>
80
81 <para>Currently this ioctl is only defined for MPEG-2 program
82streams and video elementary streams.</para>
83
84 <table pgwide="1" frame="none" id="v4l2-enc-idx">
85 <title>struct <structname>v4l2_enc_idx</structname></title>
86 <tgroup cols="3">
87 &cs-str;
88 <tbody valign="top">
89 <row>
90 <entry>__u32</entry>
91 <entry><structfield>entries</structfield></entry>
92 <entry>The number of entries the driver stored in the
93<structfield>entry</structfield> array.</entry>
94 </row>
95 <row>
96 <entry>__u32</entry>
97 <entry><structfield>entries_cap</structfield></entry>
98 <entry>The number of entries the driver can
99buffer. Must be greater than zero.</entry>
100 </row>
101 <row>
102 <entry>__u32</entry>
103 <entry><structfield>reserved</structfield>[4]</entry>
104 <entry spanname="hspan">Reserved for future extensions.
105Drivers must set the array to zero.</entry>
106 </row>
107 <row>
108 <entry>&v4l2-enc-idx-entry;</entry>
109 <entry><structfield>entry</structfield>[<constant>V4L2_ENC_IDX_ENTRIES</constant>]</entry>
110 <entry>Meta data about a compressed video stream. Each
111element of the array corresponds to one picture, sorted in ascending
112order by their <structfield>offset</structfield>.</entry>
113 </row>
114 </tbody>
115 </tgroup>
116 </table>
117
118 <table pgwide="1" frame="none" id="v4l2-enc-idx-entry">
119 <title>struct <structname>v4l2_enc_idx_entry</structname></title>
120 <tgroup cols="3">
121 &cs-str;
122 <tbody valign="top">
123 <row>
124 <entry>__u64</entry>
125 <entry><structfield>offset</structfield></entry>
126 <entry>The offset in bytes from the beginning of the
127compressed video stream to the beginning of this picture, that is a
128<wordasword>PES packet header</wordasword> as defined in <xref
129 linkend="mpeg2part1" /> or a <wordasword>picture
130header</wordasword> as defined in <xref linkend="mpeg2part2" />. When
131the encoder is stopped, the driver resets the offset to zero.</entry>
132 </row>
133 <row>
134 <entry>__u64</entry>
135 <entry><structfield>pts</structfield></entry>
136 <entry>The 33 bit <wordasword>Presentation Time
137Stamp</wordasword> of this picture as defined in <xref
138 linkend="mpeg2part1" />.</entry>
139 </row>
140 <row>
141 <entry>__u32</entry>
142 <entry><structfield>length</structfield></entry>
143 <entry>The length of this picture in bytes.</entry>
144 </row>
145 <row>
146 <entry>__u32</entry>
147 <entry><structfield>flags</structfield></entry>
148 <entry>Flags containing the coding type of this picture, see <xref
149 linkend="enc-idx-flags" />.</entry>
150 </row>
151 <row>
152 <entry>__u32</entry>
153 <entry><structfield>reserved</structfield>[2]</entry>
154 <entry>Reserved for future extensions.
155Drivers must set the array to zero.</entry>
156 </row>
157 </tbody>
158 </tgroup>
159 </table>
160
161 <table pgwide="1" frame="none" id="enc-idx-flags">
162 <title>Index Entry Flags</title>
163 <tgroup cols="3">
164 &cs-def;
165 <tbody valign="top">
166 <row>
167 <entry><constant>V4L2_ENC_IDX_FRAME_I</constant></entry>
168 <entry>0x00</entry>
169 <entry>This is an Intra-coded picture.</entry>
170 </row>
171 <row>
172 <entry><constant>V4L2_ENC_IDX_FRAME_P</constant></entry>
173 <entry>0x01</entry>
174 <entry>This is a Predictive-coded picture.</entry>
175 </row>
176 <row>
177 <entry><constant>V4L2_ENC_IDX_FRAME_B</constant></entry>
178 <entry>0x02</entry>
179 <entry>This is a Bidirectionally predictive-coded
180picture.</entry>
181 </row>
182 <row>
183 <entry><constant>V4L2_ENC_IDX_FRAME_MASK</constant></entry>
184 <entry>0x0F</entry>
185 <entry><wordasword>AND</wordasword> the flags field with
186this mask to obtain the picture coding type.</entry>
187 </row>
188 </tbody>
189 </tgroup>
190 </table>
191 </refsect1>
192
193 <refsect1>
194 &return-value;
195
196 <variablelist>
197 <varlistentry>
198 <term><errorcode>EINVAL</errorcode></term>
199 <listitem>
200 <para>The driver does not support this ioctl.</para>
201 </listitem>
202 </varlistentry>
203 </variablelist>
204 </refsect1>
205</refentry>
206
207<!--
208Local Variables:
209mode: sgml
210sgml-parent-document: "v4l2.sgml"
211indent-tabs-mode: nil
212End:
213-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
new file mode 100644
index 000000000000..3aa7f8f9ff0c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
@@ -0,0 +1,307 @@
1<refentry id="vidioc-g-ext-ctrls">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
4VIDIOC_TRY_EXT_CTRLS</refentrytitle>
5 &manvol;
6 </refmeta>
7
8 <refnamediv>
9 <refname>VIDIOC_G_EXT_CTRLS</refname>
10 <refname>VIDIOC_S_EXT_CTRLS</refname>
11 <refname>VIDIOC_TRY_EXT_CTRLS</refname>
12 <refpurpose>Get or set the value of several controls, try control
13values</refpurpose>
14 </refnamediv>
15
16 <refsynopsisdiv>
17 <funcsynopsis>
18 <funcprototype>
19 <funcdef>int <function>ioctl</function></funcdef>
20 <paramdef>int <parameter>fd</parameter></paramdef>
21 <paramdef>int <parameter>request</parameter></paramdef>
22 <paramdef>struct v4l2_ext_controls
23*<parameter>argp</parameter></paramdef>
24 </funcprototype>
25 </funcsynopsis>
26 </refsynopsisdiv>
27
28 <refsect1>
29 <title>Arguments</title>
30
31 <variablelist>
32 <varlistentry>
33 <term><parameter>fd</parameter></term>
34 <listitem>
35 <para>&fd;</para>
36 </listitem>
37 </varlistentry>
38 <varlistentry>
39 <term><parameter>request</parameter></term>
40 <listitem>
41 <para>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
42VIDIOC_TRY_EXT_CTRLS</para>
43 </listitem>
44 </varlistentry>
45 <varlistentry>
46 <term><parameter>argp</parameter></term>
47 <listitem>
48 <para></para>
49 </listitem>
50 </varlistentry>
51 </variablelist>
52 </refsect1>
53
54 <refsect1>
55 <title>Description</title>
56
57 <para>These ioctls allow the caller to get or set multiple
58controls atomically. Control IDs are grouped into control classes (see
59<xref linkend="ctrl-class" />) and all controls in the control array
60must belong to the same control class.</para>
61
62 <para>Applications must always fill in the
63<structfield>count</structfield>,
64<structfield>ctrl_class</structfield>,
65<structfield>controls</structfield> and
66<structfield>reserved</structfield> fields of &v4l2-ext-controls;, and
67initialize the &v4l2-ext-control; array pointed to by the
68<structfield>controls</structfield> fields.</para>
69
70 <para>To get the current value of a set of controls applications
71initialize the <structfield>id</structfield>,
72<structfield>size</structfield> and <structfield>reserved2</structfield> fields
73of each &v4l2-ext-control; and call the
74<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls
75must also set the <structfield>string</structfield> field.</para>
76
77 <para>If the <structfield>size</structfield> is too small to
78receive the control result (only relevant for pointer-type controls
79like strings), then the driver will set <structfield>size</structfield>
80to a valid value and return an &ENOSPC;. You should re-allocate the
81string memory to this new size and try again. It is possible that the
82same issue occurs again if the string has grown in the meantime. It is
83recommended to call &VIDIOC-QUERYCTRL; first and use
84<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
85value. It is guaranteed that that is sufficient memory.
86</para>
87
88 <para>To change the value of a set of controls applications
89initialize the <structfield>id</structfield>, <structfield>size</structfield>,
90<structfield>reserved2</structfield> and
91<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
92call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls
93will only be set if <emphasis>all</emphasis> control values are
94valid.</para>
95
96 <para>To check if a set of controls have correct values applications
97initialize the <structfield>id</structfield>, <structfield>size</structfield>,
98<structfield>reserved2</structfield> and
99<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
100call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to
101the driver whether wrong values are automatically adjusted to a valid
102value or if an error is returned.</para>
103
104 <para>When the <structfield>id</structfield> or
105<structfield>ctrl_class</structfield> is invalid drivers return an
106&EINVAL;. When the value is out of bounds drivers can choose to take
107the closest valid value or return an &ERANGE;, whatever seems more
108appropriate. In the first case the new value is set in
109&v4l2-ext-control;.</para>
110
111 <para>The driver will only set/get these controls if all control
112values are correct. This prevents the situation where only some of the
113controls were set/get. Only low-level errors (&eg; a failed i2c
114command) can still cause this situation.</para>
115
116 <table pgwide="1" frame="none" id="v4l2-ext-control">
117 <title>struct <structname>v4l2_ext_control</structname></title>
118 <tgroup cols="4">
119 &cs-ustr;
120 <tbody valign="top">
121 <row>
122 <entry>__u32</entry>
123 <entry><structfield>id</structfield></entry>
124 <entry></entry>
125 <entry>Identifies the control, set by the
126application.</entry>
127 </row>
128 <row>
129 <entry>__u32</entry>
130 <entry><structfield>size</structfield></entry>
131 <entry></entry>
132 <entry>The total size in bytes of the payload of this
133control. This is normally 0, but for pointer controls this should be
134set to the size of the memory containing the payload, or that will
135receive the payload. If <constant>VIDIOC_G_EXT_CTRLS</constant> finds
136that this value is less than is required to store
137the payload result, then it is set to a value large enough to store the
138payload result and ENOSPC is returned. Note that for string controls
139this <structfield>size</structfield> field should not be confused with the length of the string.
140This field refers to the size of the memory that contains the string.
141The actual <emphasis>length</emphasis> of the string may well be much smaller.
142</entry>
143 </row>
144 <row>
145 <entry>__u32</entry>
146 <entry><structfield>reserved2</structfield>[1]</entry>
147 <entry></entry>
148 <entry>Reserved for future extensions. Drivers and
149applications must set the array to zero.</entry>
150 </row>
151 <row>
152 <entry>union</entry>
153 <entry>(anonymous)</entry>
154 </row>
155 <row>
156 <entry></entry>
157 <entry>__s32</entry>
158 <entry><structfield>value</structfield></entry>
159 <entry>New value or current value.</entry>
160 </row>
161 <row>
162 <entry></entry>
163 <entry>__s64</entry>
164 <entry><structfield>value64</structfield></entry>
165 <entry>New value or current value.</entry>
166 </row>
167 <row>
168 <entry></entry>
169 <entry>char *</entry>
170 <entry><structfield>string</structfield></entry>
171 <entry>A pointer to a string.</entry>
172 </row>
173 </tbody>
174 </tgroup>
175 </table>
176
177 <table pgwide="1" frame="none" id="v4l2-ext-controls">
178 <title>struct <structname>v4l2_ext_controls</structname></title>
179 <tgroup cols="3">
180 &cs-str;
181 <tbody valign="top">
182 <row>
183 <entry>__u32</entry>
184 <entry><structfield>ctrl_class</structfield></entry>
185 <entry>The control class to which all controls belong, see
186<xref linkend="ctrl-class" />.</entry>
187 </row>
188 <row>
189 <entry>__u32</entry>
190 <entry><structfield>count</structfield></entry>
191 <entry>The number of controls in the controls array. May
192also be zero.</entry>
193 </row>
194 <row>
195 <entry>__u32</entry>
196 <entry><structfield>error_idx</structfield></entry>
197 <entry>Set by the driver in case of an error. It is the
198index of the control causing the error or equal to 'count' when the
199error is not associated with a particular control. Undefined when the
200ioctl returns 0 (success).</entry>
201 </row>
202 <row>
203 <entry>__u32</entry>
204 <entry><structfield>reserved</structfield>[2]</entry>
205 <entry>Reserved for future extensions. Drivers and
206applications must set the array to zero.</entry>
207 </row>
208 <row>
209 <entry>&v4l2-ext-control; *</entry>
210 <entry><structfield>controls</structfield></entry>
211 <entry>Pointer to an array of
212<structfield>count</structfield> v4l2_ext_control structures. Ignored
213if <structfield>count</structfield> equals zero.</entry>
214 </row>
215 </tbody>
216 </tgroup>
217 </table>
218
219 <table pgwide="1" frame="none" id="ctrl-class">
220 <title>Control classes</title>
221 <tgroup cols="3">
222 &cs-def;
223 <tbody valign="top">
224 <row>
225 <entry><constant>V4L2_CTRL_CLASS_USER</constant></entry>
226 <entry>0x980000</entry>
227 <entry>The class containing user controls. These controls
228are described in <xref linkend="control" />. All controls that can be set
229using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this
230class.</entry>
231 </row>
232 <row>
233 <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry>
234 <entry>0x990000</entry>
235 <entry>The class containing MPEG compression controls.
236These controls are described in <xref
237 linkend="mpeg-controls" />.</entry>
238 </row>
239 <row>
240 <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry>
241 <entry>0x9a0000</entry>
242 <entry>The class containing camera controls.
243These controls are described in <xref
244 linkend="camera-controls" />.</entry>
245 </row>
246 <row>
247 <entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry>
248 <entry>0x9b0000</entry>
249 <entry>The class containing FM Transmitter (FM TX) controls.
250These controls are described in <xref
251 linkend="fm-tx-controls" />.</entry>
252 </row>
253 </tbody>
254 </tgroup>
255 </table>
256
257 </refsect1>
258
259 <refsect1>
260 &return-value;
261
262 <variablelist>
263 <varlistentry>
264 <term><errorcode>EINVAL</errorcode></term>
265 <listitem>
266 <para>The &v4l2-ext-control; <structfield>id</structfield>
267is invalid or the &v4l2-ext-controls;
268<structfield>ctrl_class</structfield> is invalid. This error code is
269also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and
270<constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more
271control values are in conflict.</para>
272 </listitem>
273 </varlistentry>
274 <varlistentry>
275 <term><errorcode>ERANGE</errorcode></term>
276 <listitem>
277 <para>The &v4l2-ext-control; <structfield>value</structfield>
278is out of bounds.</para>
279 </listitem>
280 </varlistentry>
281 <varlistentry>
282 <term><errorcode>EBUSY</errorcode></term>
283 <listitem>
284 <para>The control is temporarily not changeable, possibly
285because another applications took over control of the device function
286this control belongs to.</para>
287 </listitem>
288 </varlistentry>
289 <varlistentry>
290 <term><errorcode>ENOSPC</errorcode></term>
291 <listitem>
292 <para>The space reserved for the control's payload is insufficient.
293The field <structfield>size</structfield> is set to a value that is enough
294to store the payload and this error code is returned.</para>
295 </listitem>
296 </varlistentry>
297 </variablelist>
298 </refsect1>
299</refentry>
300
301<!--
302Local Variables:
303mode: sgml
304sgml-parent-document: "v4l2.sgml"
305indent-tabs-mode: nil
306End:
307-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
new file mode 100644
index 000000000000..e7dda4822f04
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-fbuf.xml
@@ -0,0 +1,473 @@
1<refentry id="vidioc-g-fbuf">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_FBUF, VIDIOC_S_FBUF</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_FBUF</refname>
9 <refname>VIDIOC_S_FBUF</refname>
10 <refpurpose>Get or set frame buffer overlay parameters</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_framebuffer *<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_framebuffer *<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_G_FBUF, VIDIOC_S_FBUF</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 <para>Applications can use the <constant>VIDIOC_G_FBUF</constant> and
61<constant>VIDIOC_S_FBUF</constant> ioctl to get and set the
62framebuffer parameters for a <link linkend="overlay">Video
63Overlay</link> or <link linkend="osd">Video Output Overlay</link>
64(OSD). The type of overlay is implied by the device type (capture or
65output device) and can be determined with the &VIDIOC-QUERYCAP; ioctl.
66One <filename>/dev/videoN</filename> device must not support both
67kinds of overlay.</para>
68
69 <para>The V4L2 API distinguishes destructive and non-destructive
70overlays. A destructive overlay copies captured video images into the
71video memory of a graphics card. A non-destructive overlay blends
72video images into a VGA signal or graphics into a video signal.
73<wordasword>Video Output Overlays</wordasword> are always
74non-destructive.</para>
75
76 <para>To get the current parameters applications call the
77<constant>VIDIOC_G_FBUF</constant> ioctl with a pointer to a
78<structname>v4l2_framebuffer</structname> structure. The driver fills
79all fields of the structure or returns an &EINVAL; when overlays are
80not supported.</para>
81
82 <para>To set the parameters for a <wordasword>Video Output
83Overlay</wordasword>, applications must initialize the
84<structfield>flags</structfield> field of a struct
85<structname>v4l2_framebuffer</structname>. Since the framebuffer is
86implemented on the TV card all other parameters are determined by the
87driver. When an application calls <constant>VIDIOC_S_FBUF</constant>
88with a pointer to this structure, the driver prepares for the overlay
89and returns the framebuffer parameters as
90<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
91code.</para>
92
93 <para>To set the parameters for a <wordasword>non-destructive
94Video Overlay</wordasword>, applications must initialize the
95<structfield>flags</structfield> field, the
96<structfield>fmt</structfield> substructure, and call
97<constant>VIDIOC_S_FBUF</constant>. Again the driver prepares for the
98overlay and returns the framebuffer parameters as
99<constant>VIDIOC_G_FBUF</constant> does, or it returns an error
100code.</para>
101
102 <para>For a <wordasword>destructive Video Overlay</wordasword>
103applications must additionally provide a
104<structfield>base</structfield> address. Setting up a DMA to a
105random memory location can jeopardize the system security, its
106stability or even damage the hardware, therefore only the superuser
107can set the parameters for a destructive video overlay.</para>
108
109 <!-- NB v4l2_pix_format is also specified in pixfmt.sgml.-->
110
111 <table pgwide="1" frame="none" id="v4l2-framebuffer">
112 <title>struct <structname>v4l2_framebuffer</structname></title>
113 <tgroup cols="4">
114 &cs-ustr;
115 <tbody valign="top">
116 <row>
117 <entry>__u32</entry>
118 <entry><structfield>capability</structfield></entry>
119 <entry></entry>
120 <entry>Overlay capability flags set by the driver, see
121<xref linkend="framebuffer-cap" />.</entry>
122 </row>
123 <row>
124 <entry>__u32</entry>
125 <entry><structfield>flags</structfield></entry>
126 <entry></entry>
127 <entry>Overlay control flags set by application and
128driver, see <xref linkend="framebuffer-flags" /></entry>
129 </row>
130 <row>
131 <entry>void *</entry>
132 <entry><structfield>base</structfield></entry>
133 <entry></entry>
134 <entry>Physical base address of the framebuffer,
135that is the address of the pixel in the top left corner of the
136framebuffer.<footnote><para>A physical base address may not suit all
137platforms. GK notes in theory we should pass something like PCI device
138+ memory region + offset instead. If you encounter problems please
139discuss on the linux-media mailing list: &v4l-ml;.</para></footnote></entry>
140 </row>
141 <row>
142 <entry></entry>
143 <entry></entry>
144 <entry></entry>
145 <entry>This field is irrelevant to
146<wordasword>non-destructive Video Overlays</wordasword>. For
147<wordasword>destructive Video Overlays</wordasword> applications must
148provide a base address. The driver may accept only base addresses
149which are a multiple of two, four or eight bytes. For
150<wordasword>Video Output Overlays</wordasword> the driver must return
151a valid base address, so applications can find the corresponding Linux
152framebuffer device (see <xref linkend="osd" />).</entry>
153 </row>
154 <row>
155 <entry>&v4l2-pix-format;</entry>
156 <entry><structfield>fmt</structfield></entry>
157 <entry></entry>
158 <entry>Layout of the frame buffer. The
159<structname>v4l2_pix_format</structname> structure is defined in <xref
160linkend="pixfmt" />, for clarification the fields and acceptable values
161 are listed below:</entry>
162 </row>
163 <row>
164 <entry></entry>
165 <entry>__u32</entry>
166 <entry><structfield>width</structfield></entry>
167 <entry>Width of the frame buffer in pixels.</entry>
168 </row>
169 <row>
170 <entry></entry>
171 <entry>__u32</entry>
172 <entry><structfield>height</structfield></entry>
173 <entry>Height of the frame buffer in pixels.</entry>
174 </row>
175 <row>
176 <entry></entry>
177 <entry>__u32</entry>
178 <entry><structfield>pixelformat</structfield></entry>
179 <entry>The pixel format of the
180framebuffer.</entry>
181 </row>
182 <row>
183 <entry></entry>
184 <entry></entry>
185 <entry></entry>
186 <entry>For <wordasword>non-destructive Video
187Overlays</wordasword> this field only defines a format for the
188&v4l2-window; <structfield>chromakey</structfield> field.</entry>
189 </row>
190 <row>
191 <entry></entry>
192 <entry></entry>
193 <entry></entry>
194 <entry>For <wordasword>destructive Video
195Overlays</wordasword> applications must initialize this field. For
196<wordasword>Video Output Overlays</wordasword> the driver must return
197a valid format.</entry>
198 </row>
199 <row>
200 <entry></entry>
201 <entry></entry>
202 <entry></entry>
203 <entry>Usually this is an RGB format (for example
204<link linkend="V4L2-PIX-FMT-RGB565"><constant>V4L2_PIX_FMT_RGB565</constant></link>)
205but YUV formats (only packed YUV formats when chroma keying is used,
206not including <constant>V4L2_PIX_FMT_YUYV</constant> and
207<constant>V4L2_PIX_FMT_UYVY</constant>) and the
208<constant>V4L2_PIX_FMT_PAL8</constant> format are also permitted. The
209behavior of the driver when an application requests a compressed
210format is undefined. See <xref linkend="pixfmt" /> for information on
211pixel formats.</entry>
212 </row>
213 <row>
214 <entry></entry>
215 <entry>&v4l2-field;</entry>
216 <entry><structfield>field</structfield></entry>
217 <entry>Drivers and applications shall ignore this field.
218If applicable, the field order is selected with the &VIDIOC-S-FMT;
219ioctl, using the <structfield>field</structfield> field of
220&v4l2-window;.</entry>
221 </row>
222 <row>
223 <entry></entry>
224 <entry>__u32</entry>
225 <entry><structfield>bytesperline</structfield></entry>
226 <entry>Distance in bytes between the leftmost pixels in
227two adjacent lines.</entry>
228 </row>
229 <row>
230 <entry spanname="hspan"><para>This field is irrelevant to
231<wordasword>non-destructive Video
232Overlays</wordasword>.</para><para>For <wordasword>destructive Video
233Overlays</wordasword> both applications and drivers can set this field
234to request padding bytes at the end of each line. Drivers however may
235ignore the requested value, returning <structfield>width</structfield>
236times bytes-per-pixel or a larger value required by the hardware. That
237implies applications can just set this field to zero to get a
238reasonable default.</para><para>For <wordasword>Video Output
239Overlays</wordasword> the driver must return a valid
240value.</para><para>Video hardware may access padding bytes, therefore
241they must reside in accessible memory. Consider for example the case
242where padding bytes after the last line of an image cross a system
243page boundary. Capture devices may write padding bytes, the value is
244undefined. Output devices ignore the contents of padding
245bytes.</para><para>When the image format is planar the
246<structfield>bytesperline</structfield> value applies to the largest
247plane and is divided by the same factor as the
248<structfield>width</structfield> field for any smaller planes. For
249example the Cb and Cr planes of a YUV 4:2:0 image have half as many
250padding bytes following each line as the Y plane. To avoid ambiguities
251drivers must return a <structfield>bytesperline</structfield> value
252rounded up to a multiple of the scale factor.</para></entry>
253 </row>
254 <row>
255 <entry></entry>
256 <entry>__u32</entry>
257 <entry><structfield>sizeimage</structfield></entry>
258 <entry><para>This field is irrelevant to
259<wordasword>non-destructive Video Overlays</wordasword>. For
260<wordasword>destructive Video Overlays</wordasword> applications must
261initialize this field. For <wordasword>Video Output
262Overlays</wordasword> the driver must return a valid
263format.</para><para>Together with <structfield>base</structfield> it
264defines the framebuffer memory accessible by the
265driver.</para></entry>
266 </row>
267 <row>
268 <entry></entry>
269 <entry>&v4l2-colorspace;</entry>
270 <entry><structfield>colorspace</structfield></entry>
271 <entry>This information supplements the
272<structfield>pixelformat</structfield> and must be set by the driver,
273see <xref linkend="colorspaces" />.</entry>
274 </row>
275 <row>
276 <entry></entry>
277 <entry>__u32</entry>
278 <entry><structfield>priv</structfield></entry>
279 <entry>Reserved for additional information about custom
280(driver defined) formats. When not used drivers and applications must
281set this field to zero.</entry>
282 </row>
283 </tbody>
284 </tgroup>
285 </table>
286
287 <table pgwide="1" frame="none" id="framebuffer-cap">
288 <title>Frame Buffer Capability Flags</title>
289 <tgroup cols="3">
290 &cs-def;
291 <tbody valign="top">
292 <row>
293 <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant></entry>
294 <entry>0x0001</entry>
295 <entry>The device is capable of non-destructive overlays.
296When the driver clears this flag, only destructive overlays are
297supported. There are no drivers yet which support both destructive and
298non-destructive overlays.</entry>
299 </row>
300 <row>
301 <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
302 <entry>0x0002</entry>
303 <entry>The device supports clipping by chroma-keying the
304images. That is, image pixels replace pixels in the VGA or video
305signal only where the latter assume a certain color. Chroma-keying
306makes no sense for destructive overlays.</entry>
307 </row>
308 <row>
309 <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant></entry>
310 <entry>0x0004</entry>
311 <entry>The device supports clipping using a list of clip
312rectangles.</entry>
313 </row>
314 <row>
315 <entry><constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant></entry>
316 <entry>0x0008</entry>
317 <entry>The device supports clipping using a bit mask.</entry>
318 </row>
319 <row>
320 <entry><constant>V4L2_FBUF_CAP_LOCAL_ALPHA</constant></entry>
321 <entry>0x0010</entry>
322 <entry>The device supports clipping/blending using the
323alpha channel of the framebuffer or VGA signal. Alpha blending makes
324no sense for destructive overlays.</entry>
325 </row>
326 <row>
327 <entry><constant>V4L2_FBUF_CAP_GLOBAL_ALPHA</constant></entry>
328 <entry>0x0020</entry>
329 <entry>The device supports alpha blending using a global
330alpha value. Alpha blending makes no sense for destructive overlays.</entry>
331 </row>
332 <row>
333 <entry><constant>V4L2_FBUF_CAP_LOCAL_INV_ALPHA</constant></entry>
334 <entry>0x0040</entry>
335 <entry>The device supports clipping/blending using the
336inverted alpha channel of the framebuffer or VGA signal. Alpha
337blending makes no sense for destructive overlays.</entry>
338 </row>
339 <row>
340 <entry><constant>V4L2_FBUF_CAP_SRC_CHROMAKEY</constant></entry>
341 <entry>0x0080</entry>
342 <entry>The device supports Source Chroma-keying. Framebuffer pixels
343with the chroma-key colors are replaced by video pixels, which is exactly opposite of
344<constant>V4L2_FBUF_CAP_CHROMAKEY</constant></entry>
345 </row>
346 </tbody>
347 </tgroup>
348 </table>
349
350 <table pgwide="1" frame="none" id="framebuffer-flags">
351 <title>Frame Buffer Flags</title>
352 <tgroup cols="3">
353 &cs-def;
354 <tbody valign="top">
355 <row>
356 <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry>
357 <entry>0x0001</entry>
358 <entry>The framebuffer is the primary graphics surface.
359In other words, the overlay is destructive. [?]</entry>
360 </row>
361 <row>
362 <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry>
363 <entry>0x0002</entry>
364 <entry>The frame buffer is an overlay surface the same
365size as the capture. [?]</entry>
366 </row>
367 <row>
368 <entry spanname="hspan">The purpose of
369<constant>V4L2_FBUF_FLAG_PRIMARY</constant> and
370<constant>V4L2_FBUF_FLAG_OVERLAY</constant> was never quite clear.
371Most drivers seem to ignore these flags. For compatibility with the
372<wordasword>bttv</wordasword> driver applications should set the
373<constant>V4L2_FBUF_FLAG_OVERLAY</constant> flag.</entry>
374 </row>
375 <row>
376 <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry>
377 <entry>0x0004</entry>
378 <entry>Use chroma-keying. The chroma-key color is
379determined by the <structfield>chromakey</structfield> field of
380&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
381 linkend="overlay" />
382and
383 <xref linkend="osd" />.</entry>
384 </row>
385 <row>
386 <entry spanname="hspan">There are no flags to enable
387clipping using a list of clip rectangles or a bitmap. These methods
388are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
389 linkend="overlay" /> and <xref linkend="osd" />.</entry>
390 </row>
391 <row>
392 <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry>
393 <entry>0x0008</entry>
394 <entry>Use the alpha channel of the framebuffer to clip or
395blend framebuffer pixels with video images. The blend
396function is: output = framebuffer pixel * alpha + video pixel * (1 -
397alpha). The actual alpha depth depends on the framebuffer pixel
398format.</entry>
399 </row>
400 <row>
401 <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry>
402 <entry>0x0010</entry>
403 <entry>Use a global alpha value to blend the framebuffer
404with video images. The blend function is: output = (framebuffer pixel
405* alpha + video pixel * (255 - alpha)) / 255. The alpha value is
406determined by the <structfield>global_alpha</structfield> field of
407&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
408 linkend="overlay" />
409and <xref linkend="osd" />.</entry>
410 </row>
411 <row>
412 <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry>
413 <entry>0x0020</entry>
414 <entry>Like
415<constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel
416of the framebuffer to clip or blend framebuffer pixels with video
417images, but with an inverted alpha value. The blend function is:
418output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The
419actual alpha depth depends on the framebuffer pixel format.</entry>
420 </row>
421 <row>
422 <entry><constant>V4L2_FBUF_FLAG_SRC_CHROMAKEY</constant></entry>
423 <entry>0x0040</entry>
424 <entry>Use source chroma-keying. The source chroma-key color is
425determined by the <structfield>chromakey</structfield> field of
426&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
427linkend="overlay" /> and <xref linkend="osd" />.
428Both chroma-keying are mutual exclusive to each other, so same
429<structfield>chromakey</structfield> field of &v4l2-window; is being used.</entry>
430 </row>
431 </tbody>
432 </tgroup>
433 </table>
434 </refsect1>
435
436 <refsect1>
437 &return-value;
438
439 <variablelist>
440 <varlistentry>
441 <term><errorcode>EPERM</errorcode></term>
442 <listitem>
443 <para><constant>VIDIOC_S_FBUF</constant> can only be called
444by a privileged user to negotiate the parameters for a destructive
445overlay.</para>
446 </listitem>
447 </varlistentry>
448 <varlistentry>
449 <term><errorcode>EBUSY</errorcode></term>
450 <listitem>
451 <para>The framebuffer parameters cannot be changed at this
452time because overlay is already enabled, or capturing is enabled
453and the hardware cannot capture and overlay simultaneously.</para>
454 </listitem>
455 </varlistentry>
456 <varlistentry>
457 <term><errorcode>EINVAL</errorcode></term>
458 <listitem>
459 <para>The ioctl is not supported or the
460<constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para>
461 </listitem>
462 </varlistentry>
463 </variablelist>
464 </refsect1>
465</refentry>
466
467<!--
468Local Variables:
469mode: sgml
470sgml-parent-document: "v4l2.sgml"
471indent-tabs-mode: nil
472End:
473-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
new file mode 100644
index 000000000000..a4ae59b664eb
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml
@@ -0,0 +1,212 @@
1<refentry id="vidioc-g-fmt">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_FMT, VIDIOC_S_FMT,
4VIDIOC_TRY_FMT</refentrytitle>
5 &manvol;
6 </refmeta>
7
8 <refnamediv>
9 <refname>VIDIOC_G_FMT</refname>
10 <refname>VIDIOC_S_FMT</refname>
11 <refname>VIDIOC_TRY_FMT</refname>
12 <refpurpose>Get or set the data format, try a format</refpurpose>
13 </refnamediv>
14
15 <refsynopsisdiv>
16 <funcsynopsis>
17 <funcprototype>
18 <funcdef>int <function>ioctl</function></funcdef>
19 <paramdef>int <parameter>fd</parameter></paramdef>
20 <paramdef>int <parameter>request</parameter></paramdef>
21 <paramdef>struct v4l2_format
22*<parameter>argp</parameter></paramdef>
23 </funcprototype>
24 </funcsynopsis>
25 </refsynopsisdiv>
26
27 <refsect1>
28 <title>Arguments</title>
29
30 <variablelist>
31 <varlistentry>
32 <term><parameter>fd</parameter></term>
33 <listitem>
34 <para>&fd;</para>
35 </listitem>
36 </varlistentry>
37 <varlistentry>
38 <term><parameter>request</parameter></term>
39 <listitem>
40 <para>VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT</para>
41 </listitem>
42 </varlistentry>
43 <varlistentry>
44 <term><parameter>argp</parameter></term>
45 <listitem>
46 <para></para>
47 </listitem>
48 </varlistentry>
49 </variablelist>
50 </refsect1>
51
52 <refsect1>
53 <title>Description</title>
54
55 <para>These ioctls are used to negotiate the format of data
56(typically image format) exchanged between driver and
57application.</para>
58
59 <para>To query the current parameters applications set the
60<structfield>type</structfield> field of a struct
61<structname>v4l2_format</structname> to the respective buffer (stream)
62type. For example video capture devices use
63<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> or
64<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>. When the application
65calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
66this structure the driver fills the respective member of the
67<structfield>fmt</structfield> union. In case of video capture devices
68that is either the &v4l2-pix-format; <structfield>pix</structfield> or
69the &v4l2-pix-format-mplane; <structfield>pix_mp</structfield> member.
70When the requested buffer type is not supported drivers return an
71&EINVAL;.</para>
72
73 <para>To change the current format parameters applications
74initialize the <structfield>type</structfield> field and all
75fields of the respective <structfield>fmt</structfield>
76union member. For details see the documentation of the various devices
77types in <xref linkend="devices" />. Good practice is to query the
78current parameters first, and to
79modify only those parameters not suitable for the application. When
80the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
81with a pointer to a <structname>v4l2_format</structname> structure
82the driver checks
83and adjusts the parameters against hardware abilities. Drivers
84should not return an error code unless the input is ambiguous, this is
85a mechanism to fathom device capabilities and to approach parameters
86acceptable for both the application and driver. On success the driver
87may program the hardware, allocate resources and generally prepare for
88data exchange.
89Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
90current format parameters as <constant>VIDIOC_G_FMT</constant> does.
91Very simple, inflexible devices may even ignore all input and always
92return the default parameters. However all V4L2 devices exchanging
93data with the application must implement the
94<constant>VIDIOC_G_FMT</constant> and
95<constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
96type is not supported drivers return an &EINVAL; on a
97<constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
98progress or the resource is not available for other reasons drivers
99return the &EBUSY;.</para>
100
101 <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
102to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
103change driver state. It can also be called at any time, never
104returning <errorcode>EBUSY</errorcode>. This function is provided to
105negotiate parameters, to learn about hardware limitations, without
106disabling I/O or possibly time consuming hardware preparations.
107Although strongly recommended drivers are not required to implement
108this ioctl.</para>
109
110 <table pgwide="1" frame="none" id="v4l2-format">
111 <title>struct <structname>v4l2_format</structname></title>
112 <tgroup cols="4">
113 <colspec colname="c1" />
114 <colspec colname="c2" />
115 <colspec colname="c3" />
116 <colspec colname="c4" />
117 <tbody valign="top">
118 <row>
119 <entry>&v4l2-buf-type;</entry>
120 <entry><structfield>type</structfield></entry>
121 <entry></entry>
122 <entry>Type of the data stream, see <xref
123 linkend="v4l2-buf-type" />.</entry>
124 </row>
125 <row>
126 <entry>union</entry>
127 <entry><structfield>fmt</structfield></entry>
128 </row>
129 <row>
130 <entry></entry>
131 <entry>&v4l2-pix-format;</entry>
132 <entry><structfield>pix</structfield></entry>
133 <entry>Definition of an image format, see <xref
134 linkend="pixfmt" />, used by video capture and output
135devices.</entry>
136 </row>
137 <row>
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>
148 <entry>&v4l2-window;</entry>
149 <entry><structfield>win</structfield></entry>
150 <entry>Definition of an overlaid image, see <xref
151 linkend="overlay" />, used by video overlay devices.</entry>
152 </row>
153 <row>
154 <entry></entry>
155 <entry>&v4l2-vbi-format;</entry>
156 <entry><structfield>vbi</structfield></entry>
157 <entry>Raw VBI capture or output parameters. This is
158discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
159capture and output devices.</entry>
160 </row>
161 <row>
162 <entry></entry>
163 <entry>&v4l2-sliced-vbi-format;</entry>
164 <entry><structfield>sliced</structfield></entry>
165 <entry>Sliced VBI capture or output parameters. See
166<xref linkend="sliced" /> for details. Used by sliced VBI
167capture and output devices.</entry>
168 </row>
169 <row>
170 <entry></entry>
171 <entry>__u8</entry>
172 <entry><structfield>raw_data</structfield>[200]</entry>
173 <entry>Place holder for future extensions and custom
174(driver defined) formats with <structfield>type</structfield>
175<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry>
176 </row>
177 </tbody>
178 </tgroup>
179 </table>
180 </refsect1>
181
182 <refsect1>
183 &return-value;
184
185 <variablelist>
186 <varlistentry>
187 <term><errorcode>EBUSY</errorcode></term>
188 <listitem>
189 <para>The data format cannot be changed at this
190time, for example because I/O is already in progress.</para>
191 </listitem>
192 </varlistentry>
193 <varlistentry>
194 <term><errorcode>EINVAL</errorcode></term>
195 <listitem>
196 <para>The &v4l2-format; <structfield>type</structfield>
197field is invalid, the requested buffer type not supported, or
198<constant>VIDIOC_TRY_FMT</constant> was called and is not
199supported with this buffer type.</para>
200 </listitem>
201 </varlistentry>
202 </variablelist>
203 </refsect1>
204</refentry>
205
206<!--
207Local Variables:
208mode: sgml
209sgml-parent-document: "v4l2.sgml"
210indent-tabs-mode: nil
211End:
212-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml
new file mode 100644
index 000000000000..062d72069090
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-frequency.xml
@@ -0,0 +1,145 @@
1<refentry id="vidioc-g-frequency">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_FREQUENCY</refname>
9 <refname>VIDIOC_S_FREQUENCY</refname>
10 <refpurpose>Get or set tuner or modulator radio
11frequency</refpurpose>
12 </refnamediv>
13
14 <refsynopsisdiv>
15 <funcsynopsis>
16 <funcprototype>
17 <funcdef>int <function>ioctl</function></funcdef>
18 <paramdef>int <parameter>fd</parameter></paramdef>
19 <paramdef>int <parameter>request</parameter></paramdef>
20 <paramdef>struct v4l2_frequency
21*<parameter>argp</parameter></paramdef>
22 </funcprototype>
23 </funcsynopsis>
24 <funcsynopsis>
25 <funcprototype>
26 <funcdef>int <function>ioctl</function></funcdef>
27 <paramdef>int <parameter>fd</parameter></paramdef>
28 <paramdef>int <parameter>request</parameter></paramdef>
29 <paramdef>const struct v4l2_frequency
30*<parameter>argp</parameter></paramdef>
31 </funcprototype>
32 </funcsynopsis>
33 </refsynopsisdiv>
34
35 <refsect1>
36 <title>Arguments</title>
37
38 <variablelist>
39 <varlistentry>
40 <term><parameter>fd</parameter></term>
41 <listitem>
42 <para>&fd;</para>
43 </listitem>
44 </varlistentry>
45 <varlistentry>
46 <term><parameter>request</parameter></term>
47 <listitem>
48 <para>VIDIOC_G_FREQUENCY, VIDIOC_S_FREQUENCY</para>
49 </listitem>
50 </varlistentry>
51 <varlistentry>
52 <term><parameter>argp</parameter></term>
53 <listitem>
54 <para></para>
55 </listitem>
56 </varlistentry>
57 </variablelist>
58 </refsect1>
59
60 <refsect1>
61 <title>Description</title>
62
63 <para>To get the current tuner or modulator radio frequency
64applications set the <structfield>tuner</structfield> field of a
65&v4l2-frequency; to the respective tuner or modulator number (only
66input devices have tuners, only output devices have modulators), zero
67out the <structfield>reserved</structfield> array and
68call the <constant>VIDIOC_G_FREQUENCY</constant> ioctl with a pointer
69to this structure. The driver stores the current frequency in the
70<structfield>frequency</structfield> field.</para>
71
72 <para>To change the current tuner or modulator radio frequency
73applications initialize the <structfield>tuner</structfield>,
74<structfield>type</structfield> and
75<structfield>frequency</structfield> fields, and the
76<structfield>reserved</structfield> array of a &v4l2-frequency; and
77call the <constant>VIDIOC_S_FREQUENCY</constant> ioctl with a pointer
78to this structure. When the requested frequency is not possible the
79driver assumes the closest possible value. However
80<constant>VIDIOC_S_FREQUENCY</constant> is a write-only ioctl, it does
81not return the actual new frequency.</para>
82
83 <table pgwide="1" frame="none" id="v4l2-frequency">
84 <title>struct <structname>v4l2_frequency</structname></title>
85 <tgroup cols="3">
86 &cs-str;
87 <tbody valign="top">
88 <row>
89 <entry>__u32</entry>
90 <entry><structfield>tuner</structfield></entry>
91 <entry>The tuner or modulator index number. This is the
92same value as in the &v4l2-input; <structfield>tuner</structfield>
93field and the &v4l2-tuner; <structfield>index</structfield> field, or
94the &v4l2-output; <structfield>modulator</structfield> field and the
95&v4l2-modulator; <structfield>index</structfield> field.</entry>
96 </row>
97 <row>
98 <entry>&v4l2-tuner-type;</entry>
99 <entry><structfield>type</structfield></entry>
100 <entry>The tuner type. This is the same value as in the
101&v4l2-tuner; <structfield>type</structfield> field. The field is not
102applicable to modulators, &ie; ignored by drivers.</entry>
103 </row>
104 <row>
105 <entry>__u32</entry>
106 <entry><structfield>frequency</structfield></entry>
107 <entry>Tuning frequency in units of 62.5 kHz, or if the
108&v4l2-tuner; or &v4l2-modulator; <structfield>capabilities</structfield> flag
109<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
110Hz.</entry>
111 </row>
112 <row>
113 <entry>__u32</entry>
114 <entry><structfield>reserved</structfield>[8]</entry>
115 <entry>Reserved for future extensions. Drivers and
116 applications must set the array to zero.</entry>
117 </row>
118 </tbody>
119 </tgroup>
120 </table>
121 </refsect1>
122
123 <refsect1>
124 &return-value;
125
126 <variablelist>
127 <varlistentry>
128 <term><errorcode>EINVAL</errorcode></term>
129 <listitem>
130 <para>The <structfield>tuner</structfield> index is out of
131bounds or the value in the <structfield>type</structfield> field is
132wrong.</para>
133 </listitem>
134 </varlistentry>
135 </variablelist>
136 </refsect1>
137</refentry>
138
139<!--
140Local Variables:
141mode: sgml
142sgml-parent-document: "v4l2.sgml"
143indent-tabs-mode: nil
144End:
145-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-input.xml b/Documentation/DocBook/media/v4l/vidioc-g-input.xml
new file mode 100644
index 000000000000..ed076e92760d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-input.xml
@@ -0,0 +1,100 @@
1<refentry id="vidioc-g-input">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_INPUT, VIDIOC_S_INPUT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_INPUT</refname>
9 <refname>VIDIOC_S_INPUT</refname>
10 <refpurpose>Query or select the current video input</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>int *<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_G_INPUT, VIDIOC_S_INPUT</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 query the current video input applications call the
53<constant>VIDIOC_G_INPUT</constant> ioctl with a pointer to an integer
54where the driver stores the number of the input, as in the
55&v4l2-input; <structfield>index</structfield> field. This ioctl will
56fail only when there are no video inputs, returning
57<errorcode>EINVAL</errorcode>.</para>
58
59 <para>To select a video input applications store the number of the
60desired input in an integer and call the
61<constant>VIDIOC_S_INPUT</constant> ioctl with a pointer to this
62integer. Side effects are possible. For example inputs may support
63different video standards, so the driver may implicitly switch the
64current standard. It is good practice to select an input before
65querying or negotiating any other parameters.</para>
66
67 <para>Information about video inputs is available using the
68&VIDIOC-ENUMINPUT; ioctl.</para>
69 </refsect1>
70
71 <refsect1>
72 &return-value;
73
74 <variablelist>
75 <varlistentry>
76 <term><errorcode>EINVAL</errorcode></term>
77 <listitem>
78 <para>The number of the video input is out of bounds, or
79there are no video inputs at all and this ioctl is not
80supported.</para>
81 </listitem>
82 </varlistentry>
83 <varlistentry>
84 <term><errorcode>EBUSY</errorcode></term>
85 <listitem>
86 <para>I/O is in progress, the input cannot be
87switched.</para>
88 </listitem>
89 </varlistentry>
90 </variablelist>
91 </refsect1>
92</refentry>
93
94<!--
95Local Variables:
96mode: sgml
97sgml-parent-document: "v4l2.sgml"
98indent-tabs-mode: nil
99End:
100-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml b/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml
new file mode 100644
index 000000000000..77394b287411
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-jpegcomp.xml
@@ -0,0 +1,180 @@
1<refentry id="vidioc-g-jpegcomp">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_JPEGCOMP</refname>
9 <refname>VIDIOC_S_JPEGCOMP</refname>
10 <refpurpose></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>v4l2_jpegcompression *<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 v4l2_jpegcompression *<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_G_JPEGCOMP, VIDIOC_S_JPEGCOMP</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 <para>[to do]</para>
61
62 <para>Ronald Bultje elaborates:</para>
63
64 <!-- See video4linux-list@redhat.com on 16 Oct 2002, subject
65"Re: [V4L] Re: v4l2 api / Zoran v4l2_jpegcompression" -->
66
67 <para>APP is some application-specific information. The
68application can set it itself, and it'll be stored in the JPEG-encoded
69fields (eg; interlacing information for in an AVI or so). COM is the
70same, but it's comments, like 'encoded by me' or so.</para>
71
72 <para>jpeg_markers describes whether the huffman tables,
73quantization tables and the restart interval information (all
74JPEG-specific stuff) should be stored in the JPEG-encoded fields.
75These define how the JPEG field is encoded. If you omit them,
76applications assume you've used standard encoding. You usually do want
77to add them.</para>
78
79 <!-- NB VIDIOC_S_JPEGCOMP is w/o. -->
80
81 <table pgwide="1" frame="none" id="v4l2-jpegcompression">
82 <title>struct <structname>v4l2_jpegcompression</structname></title>
83 <tgroup cols="3">
84 &cs-str;
85 <tbody valign="top">
86 <row>
87 <entry>int</entry>
88 <entry><structfield>quality</structfield></entry>
89 <entry></entry>
90 </row>
91 <row>
92 <entry>int</entry>
93 <entry><structfield>APPn</structfield></entry>
94 <entry></entry>
95 </row>
96 <row>
97 <entry>int</entry>
98 <entry><structfield>APP_len</structfield></entry>
99 <entry></entry>
100 </row>
101 <row>
102 <entry>char</entry>
103 <entry><structfield>APP_data</structfield>[60]</entry>
104 <entry></entry>
105 </row>
106 <row>
107 <entry>int</entry>
108 <entry><structfield>COM_len</structfield></entry>
109 <entry></entry>
110 </row>
111 <row>
112 <entry>char</entry>
113 <entry><structfield>COM_data</structfield>[60]</entry>
114 <entry></entry>
115 </row>
116 <row>
117 <entry>__u32</entry>
118 <entry><structfield>jpeg_markers</structfield></entry>
119 <entry>See <xref linkend="jpeg-markers" />.</entry>
120 </row>
121 </tbody>
122 </tgroup>
123 </table>
124
125 <table pgwide="1" frame="none" id="jpeg-markers">
126 <title>JPEG Markers Flags</title>
127 <tgroup cols="3">
128 &cs-def;
129 <tbody valign="top">
130 <row>
131 <entry><constant>V4L2_JPEG_MARKER_DHT</constant></entry>
132 <entry>(1&lt;&lt;3)</entry>
133 <entry>Define Huffman Tables</entry>
134 </row>
135 <row>
136 <entry><constant>V4L2_JPEG_MARKER_DQT</constant></entry>
137 <entry>(1&lt;&lt;4)</entry>
138 <entry>Define Quantization Tables</entry>
139 </row>
140 <row>
141 <entry><constant>V4L2_JPEG_MARKER_DRI</constant></entry>
142 <entry>(1&lt;&lt;5)</entry>
143 <entry>Define Restart Interval</entry>
144 </row>
145 <row>
146 <entry><constant>V4L2_JPEG_MARKER_COM</constant></entry>
147 <entry>(1&lt;&lt;6)</entry>
148 <entry>Comment segment</entry>
149 </row>
150 <row>
151 <entry><constant>V4L2_JPEG_MARKER_APP</constant></entry>
152 <entry>(1&lt;&lt;7)</entry>
153 <entry>App segment, driver will always use APP0</entry>
154 </row>
155 </tbody>
156 </tgroup>
157 </table>
158 </refsect1>
159
160 <refsect1>
161 &return-value;
162
163 <variablelist>
164 <varlistentry>
165 <term><errorcode>EINVAL</errorcode></term>
166 <listitem>
167 <para>This ioctl is not supported.</para>
168 </listitem>
169 </varlistentry>
170 </variablelist>
171 </refsect1>
172</refentry>
173
174<!--
175Local Variables:
176mode: sgml
177sgml-parent-document: "v4l2.sgml"
178indent-tabs-mode: nil
179End:
180-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml
new file mode 100644
index 000000000000..15ce660f0f5a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-modulator.xml
@@ -0,0 +1,246 @@
1<refentry id="vidioc-g-modulator">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_MODULATOR</refname>
9 <refname>VIDIOC_S_MODULATOR</refname>
10 <refpurpose>Get or set modulator attributes</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_modulator
20*<parameter>argp</parameter></paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 <funcsynopsis>
24 <funcprototype>
25 <funcdef>int <function>ioctl</function></funcdef>
26 <paramdef>int <parameter>fd</parameter></paramdef>
27 <paramdef>int <parameter>request</parameter></paramdef>
28 <paramdef>const struct v4l2_modulator
29*<parameter>argp</parameter></paramdef>
30 </funcprototype>
31 </funcsynopsis>
32 </refsynopsisdiv>
33
34 <refsect1>
35 <title>Arguments</title>
36
37 <variablelist>
38 <varlistentry>
39 <term><parameter>fd</parameter></term>
40 <listitem>
41 <para>&fd;</para>
42 </listitem>
43 </varlistentry>
44 <varlistentry>
45 <term><parameter>request</parameter></term>
46 <listitem>
47 <para>VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR</para>
48 </listitem>
49 </varlistentry>
50 <varlistentry>
51 <term><parameter>argp</parameter></term>
52 <listitem>
53 <para></para>
54 </listitem>
55 </varlistentry>
56 </variablelist>
57 </refsect1>
58
59 <refsect1>
60 <title>Description</title>
61
62 <para>To query the attributes of a modulator applications initialize
63the <structfield>index</structfield> field and zero out the
64<structfield>reserved</structfield> array of a &v4l2-modulator; and
65call the <constant>VIDIOC_G_MODULATOR</constant> ioctl with a pointer
66to this structure. Drivers fill the rest of the structure or return an
67&EINVAL; when the index is out of bounds. To enumerate all modulators
68applications shall begin at index zero, incrementing by one until the
69driver returns <errorcode>EINVAL</errorcode>.</para>
70
71 <para>Modulators have two writable properties, an audio
72modulation set and the radio frequency. To change the modulated audio
73subprograms, applications initialize the <structfield>index
74</structfield> and <structfield>txsubchans</structfield> fields and the
75<structfield>reserved</structfield> array and call the
76<constant>VIDIOC_S_MODULATOR</constant> ioctl. Drivers may choose a
77different audio modulation if the request cannot be satisfied. However
78this is a write-only ioctl, it does not return the actual audio
79modulation selected.</para>
80
81 <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
82is available.</para>
83
84 <table pgwide="1" frame="none" id="v4l2-modulator">
85 <title>struct <structname>v4l2_modulator</structname></title>
86 <tgroup cols="3">
87 &cs-str;
88 <tbody valign="top">
89 <row>
90 <entry>__u32</entry>
91 <entry><structfield>index</structfield></entry>
92 <entry>Identifies the modulator, set by the
93application.</entry>
94 </row>
95 <row>
96 <entry>__u8</entry>
97 <entry><structfield>name</structfield>[32]</entry>
98 <entry>Name of the modulator, a NUL-terminated ASCII
99string. This information is intended for the user.</entry>
100 </row>
101 <row>
102 <entry>__u32</entry>
103 <entry><structfield>capability</structfield></entry>
104 <entry>Modulator capability flags. No flags are defined
105for this field, the tuner flags in &v4l2-tuner;
106are used accordingly. The audio flags indicate the ability
107to encode audio subprograms. They will <emphasis>not</emphasis>
108change for example with the current video standard.</entry>
109 </row>
110 <row>
111 <entry>__u32</entry>
112 <entry><structfield>rangelow</structfield></entry>
113 <entry>The lowest tunable frequency in units of 62.5
114KHz, or if the <structfield>capability</structfield> flag
115<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
116Hz.</entry>
117 </row>
118 <row>
119 <entry>__u32</entry>
120 <entry><structfield>rangehigh</structfield></entry>
121 <entry>The highest tunable frequency in units of 62.5
122KHz, or if the <structfield>capability</structfield> flag
123<constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
124Hz.</entry>
125 </row>
126 <row>
127 <entry>__u32</entry>
128 <entry><structfield>txsubchans</structfield></entry>
129 <entry>With this field applications can determine how
130audio sub-carriers shall be modulated. It contains a set of flags as
131defined in <xref linkend="modulator-txsubchans" />. Note the tuner
132<structfield>rxsubchans</structfield> flags are reused, but the
133semantics are different. Video output devices are assumed to have an
134analog or PCM audio input with 1-3 channels. The
135<structfield>txsubchans</structfield> flags select one or more
136channels for modulation, together with some audio subprogram
137indicator, for example a stereo pilot tone.</entry>
138 </row>
139 <row>
140 <entry>__u32</entry>
141 <entry><structfield>reserved</structfield>[4]</entry>
142 <entry>Reserved for future extensions. Drivers and
143applications must set the array to zero.</entry>
144 </row>
145 </tbody>
146 </tgroup>
147 </table>
148
149 <table pgwide="1" frame="none" id="modulator-txsubchans">
150 <title>Modulator Audio Transmission Flags</title>
151 <tgroup cols="3">
152 &cs-def;
153 <tbody valign="top">
154 <row>
155 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
156 <entry>0x0001</entry>
157 <entry>Modulate channel 1 as mono audio, when the input
158has more channels, a down-mix of channel 1 and 2. This flag does not
159combine with <constant>V4L2_TUNER_SUB_STEREO</constant> or
160<constant>V4L2_TUNER_SUB_LANG1</constant>.</entry>
161 </row>
162 <row>
163 <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
164 <entry>0x0002</entry>
165 <entry>Modulate channel 1 and 2 as left and right
166channel of a stereo audio signal. When the input has only one channel
167or two channels and <constant>V4L2_TUNER_SUB_SAP</constant> is also
168set, channel 1 is encoded as left and right channel. This flag does
169not combine with <constant>V4L2_TUNER_SUB_MONO</constant> or
170<constant>V4L2_TUNER_SUB_LANG1</constant>. When the driver does not
171support stereo audio it shall fall back to mono.</entry>
172 </row>
173 <row>
174 <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
175 <entry>0x0008</entry>
176 <entry>Modulate channel 1 and 2 as primary and secondary
177language of a bilingual audio signal. When the input has only one
178channel it is used for both languages. It is not possible to encode
179the primary or secondary language only. This flag does not combine
180with <constant>V4L2_TUNER_SUB_MONO</constant>,
181<constant>V4L2_TUNER_SUB_STEREO</constant> or
182<constant>V4L2_TUNER_SUB_SAP</constant>. If the hardware does not
183support the respective audio matrix, or the current video standard
184does not permit bilingual audio the
185<constant>VIDIOC_S_MODULATOR</constant> ioctl shall return an &EINVAL;
186and the driver shall fall back to mono or stereo mode.</entry>
187 </row>
188 <row>
189 <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
190 <entry>0x0004</entry>
191 <entry>Same effect as
192<constant>V4L2_TUNER_SUB_SAP</constant>.</entry>
193 </row>
194 <row>
195 <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
196 <entry>0x0004</entry>
197 <entry>When combined with <constant>V4L2_TUNER_SUB_MONO
198</constant> the first channel is encoded as mono audio, the last
199channel as Second Audio Program. When the input has only one channel
200it is used for both audio tracks. When the input has three channels
201the mono track is a down-mix of channel 1 and 2. When combined with
202<constant>V4L2_TUNER_SUB_STEREO</constant> channel 1 and 2 are
203encoded as left and right stereo audio, channel 3 as Second Audio
204Program. When the input has only two channels, the first is encoded as
205left and right channel and the second as SAP. When the input has only
206one channel it is used for all audio tracks. It is not possible to
207encode a Second Audio Program only. This flag must combine with
208<constant>V4L2_TUNER_SUB_MONO</constant> or
209<constant>V4L2_TUNER_SUB_STEREO</constant>. If the hardware does not
210support the respective audio matrix, or the current video standard
211does not permit SAP the <constant>VIDIOC_S_MODULATOR</constant> ioctl
212shall return an &EINVAL; and driver shall fall back to mono or stereo
213mode.</entry>
214 </row>
215 <row>
216 <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
217 <entry>0x0010</entry>
218 <entry>Enable the RDS encoder for a radio FM transmitter.</entry>
219 </row>
220 </tbody>
221 </tgroup>
222 </table>
223 </refsect1>
224
225 <refsect1>
226 &return-value;
227
228 <variablelist>
229 <varlistentry>
230 <term><errorcode>EINVAL</errorcode></term>
231 <listitem>
232 <para>The &v4l2-modulator;
233<structfield>index</structfield> is out of bounds.</para>
234 </listitem>
235 </varlistentry>
236 </variablelist>
237 </refsect1>
238</refentry>
239
240<!--
241Local Variables:
242mode: sgml
243sgml-parent-document: "v4l2.sgml"
244indent-tabs-mode: nil
245End:
246-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-output.xml b/Documentation/DocBook/media/v4l/vidioc-g-output.xml
new file mode 100644
index 000000000000..3ea8c0ed812e
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-output.xml
@@ -0,0 +1,100 @@
1<refentry id="vidioc-g-output">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_OUTPUT, VIDIOC_S_OUTPUT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_OUTPUT</refname>
9 <refname>VIDIOC_S_OUTPUT</refname>
10 <refpurpose>Query or select the current video output</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>int *<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_G_OUTPUT, VIDIOC_S_OUTPUT</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 query the current video output applications call the
53<constant>VIDIOC_G_OUTPUT</constant> ioctl with a pointer to an integer
54where the driver stores the number of the output, as in the
55&v4l2-output; <structfield>index</structfield> field. This ioctl
56will fail only when there are no video outputs, returning the
57&EINVAL;.</para>
58
59 <para>To select a video output applications store the number of the
60desired output in an integer and call the
61<constant>VIDIOC_S_OUTPUT</constant> ioctl with a pointer to this integer.
62Side effects are possible. For example outputs may support different
63video standards, so the driver may implicitly switch the current
64standard. It is good practice to select an output before querying or
65negotiating any other parameters.</para>
66
67 <para>Information about video outputs is available using the
68&VIDIOC-ENUMOUTPUT; ioctl.</para>
69 </refsect1>
70
71 <refsect1>
72 &return-value;
73
74 <variablelist>
75 <varlistentry>
76 <term><errorcode>EINVAL</errorcode></term>
77 <listitem>
78 <para>The number of the video output is out of bounds, or
79there are no video outputs at all and this ioctl is not
80supported.</para>
81 </listitem>
82 </varlistentry>
83 <varlistentry>
84 <term><errorcode>EBUSY</errorcode></term>
85 <listitem>
86 <para>I/O is in progress, the output cannot be
87switched.</para>
88 </listitem>
89 </varlistentry>
90 </variablelist>
91 </refsect1>
92</refentry>
93
94<!--
95Local Variables:
96mode: sgml
97sgml-parent-document: "v4l2.sgml"
98indent-tabs-mode: nil
99End:
100-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml
new file mode 100644
index 000000000000..392aa9e5571e
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml
@@ -0,0 +1,332 @@
1<refentry id="vidioc-g-parm">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_PARM, VIDIOC_S_PARM</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_PARM</refname>
9 <refname>VIDIOC_S_PARM</refname>
10 <refpurpose>Get or set streaming parameters</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>v4l2_streamparm *<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_G_PARM, VIDIOC_S_PARM</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>The current video standard determines a nominal number of
53frames per second. If less than this number of frames is to be
54captured or output, applications can request frame skipping or
55duplicating on the driver side. This is especially useful when using
56the <function>read()</function> or <function>write()</function>, which
57are not augmented by timestamps or sequence counters, and to avoid
58unnecessary data copying.</para>
59
60 <para>Further these ioctls can be used to determine the number of
61buffers used internally by a driver in read/write mode. For
62implications see the section discussing the &func-read;
63function.</para>
64
65 <para>To get and set the streaming parameters applications call
66the <constant>VIDIOC_G_PARM</constant> and
67<constant>VIDIOC_S_PARM</constant> ioctl, respectively. They take a
68pointer to a struct <structname>v4l2_streamparm</structname> which
69contains a union holding separate parameters for input and output
70devices.</para>
71
72 <table pgwide="1" frame="none" id="v4l2-streamparm">
73 <title>struct <structname>v4l2_streamparm</structname></title>
74 <tgroup cols="4">
75 &cs-ustr;
76 <tbody valign="top">
77 <row>
78 <entry>&v4l2-buf-type;</entry>
79 <entry><structfield>type</structfield></entry>
80 <entry></entry>
81 <entry>The buffer (stream) type, same as &v4l2-format;
82<structfield>type</structfield>, set by the application.</entry>
83 </row>
84 <row>
85 <entry>union</entry>
86 <entry><structfield>parm</structfield></entry>
87 <entry></entry>
88 <entry></entry>
89 </row>
90 <row>
91 <entry></entry>
92 <entry>&v4l2-captureparm;</entry>
93 <entry><structfield>capture</structfield></entry>
94 <entry>Parameters for capture devices, used when
95<structfield>type</structfield> is
96<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>.</entry>
97 </row>
98 <row>
99 <entry></entry>
100 <entry>&v4l2-outputparm;</entry>
101 <entry><structfield>output</structfield></entry>
102 <entry>Parameters for output devices, used when
103<structfield>type</structfield> is
104<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>.</entry>
105 </row>
106 <row>
107 <entry></entry>
108 <entry>__u8</entry>
109 <entry><structfield>raw_data</structfield>[200]</entry>
110 <entry>A place holder for future extensions and custom
111(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and
112higher.</entry>
113 </row>
114 </tbody>
115 </tgroup>
116 </table>
117
118 <table pgwide="1" frame="none" id="v4l2-captureparm">
119 <title>struct <structname>v4l2_captureparm</structname></title>
120 <tgroup cols="3">
121 &cs-str;
122 <tbody valign="top">
123 <row>
124 <entry>__u32</entry>
125 <entry><structfield>capability</structfield></entry>
126 <entry>See <xref linkend="parm-caps" />.</entry>
127 </row>
128 <row>
129 <entry>__u32</entry>
130 <entry><structfield>capturemode</structfield></entry>
131 <entry>Set by drivers and applications, see <xref linkend="parm-flags" />.</entry>
132 </row>
133 <row>
134 <entry>&v4l2-fract;</entry>
135 <entry><structfield>timeperframe</structfield></entry>
136 <entry><para>This is is the desired period between
137successive frames captured by the driver, in seconds. The
138field is intended to skip frames on the driver side, saving I/O
139bandwidth.</para><para>Applications store here the desired frame
140period, drivers return the actual frame period, which must be greater
141or equal to the nominal frame period determined by the current video
142standard (&v4l2-standard; <structfield>frameperiod</structfield>
143field). Changing the video standard (also implicitly by switching the
144video input) may reset this parameter to the nominal frame period. To
145reset manually applications can just set this field to
146zero.</para><para>Drivers support this function only when they set the
147<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
148<structfield>capability</structfield> field.</para></entry>
149 </row>
150 <row>
151 <entry>__u32</entry>
152 <entry><structfield>extendedmode</structfield></entry>
153 <entry>Custom (driver specific) streaming parameters. When
154unused, applications and drivers must set this field to zero.
155Applications using this field should check the driver name and
156version, see <xref linkend="querycap" />.</entry>
157 </row>
158 <row>
159 <entry>__u32</entry>
160 <entry><structfield>readbuffers</structfield></entry>
161 <entry>Applications set this field to the desired number
162of buffers used internally by the driver in &func-read; mode. Drivers
163return the actual number of buffers. When an application requests zero
164buffers, drivers should just return the current setting rather than
165the minimum or an error code. For details see <xref
166 linkend="rw" />.</entry>
167 </row>
168 <row>
169 <entry>__u32</entry>
170 <entry><structfield>reserved</structfield>[4]</entry>
171 <entry>Reserved for future extensions. Drivers and
172applications must set the array to zero.</entry>
173 </row>
174 </tbody>
175 </tgroup>
176 </table>
177
178 <table pgwide="1" frame="none" id="v4l2-outputparm">
179 <title>struct <structname>v4l2_outputparm</structname></title>
180 <tgroup cols="3">
181 &cs-str;
182 <tbody valign="top">
183 <row>
184 <entry>__u32</entry>
185 <entry><structfield>capability</structfield></entry>
186 <entry>See <xref linkend="parm-caps" />.</entry>
187 </row>
188 <row>
189 <entry>__u32</entry>
190 <entry><structfield>outputmode</structfield></entry>
191 <entry>Set by drivers and applications, see <xref
192 linkend="parm-flags" />.</entry>
193 </row>
194 <row>
195 <entry>&v4l2-fract;</entry>
196 <entry><structfield>timeperframe</structfield></entry>
197 <entry>This is is the desired period between
198successive frames output by the driver, in seconds.</entry>
199 </row>
200 <row>
201 <entry spanname="hspan"><para>The field is intended to
202repeat frames on the driver side in &func-write; mode (in streaming
203mode timestamps can be used to throttle the output), saving I/O
204bandwidth.</para><para>Applications store here the desired frame
205period, drivers return the actual frame period, which must be greater
206or equal to the nominal frame period determined by the current video
207standard (&v4l2-standard; <structfield>frameperiod</structfield>
208field). Changing the video standard (also implicitly by switching the
209video output) may reset this parameter to the nominal frame period. To
210reset manually applications can just set this field to
211zero.</para><para>Drivers support this function only when they set the
212<constant>V4L2_CAP_TIMEPERFRAME</constant> flag in the
213<structfield>capability</structfield> field.</para></entry>
214 </row>
215 <row>
216 <entry>__u32</entry>
217 <entry><structfield>extendedmode</structfield></entry>
218 <entry>Custom (driver specific) streaming parameters. When
219unused, applications and drivers must set this field to zero.
220Applications using this field should check the driver name and
221version, see <xref linkend="querycap" />.</entry>
222 </row>
223 <row>
224 <entry>__u32</entry>
225 <entry><structfield>writebuffers</structfield></entry>
226 <entry>Applications set this field to the desired number
227of buffers used internally by the driver in
228<function>write()</function> mode. Drivers return the actual number of
229buffers. When an application requests zero buffers, drivers should
230just return the current setting rather than the minimum or an error
231code. For details see <xref linkend="rw" />.</entry>
232 </row>
233 <row>
234 <entry>__u32</entry>
235 <entry><structfield>reserved</structfield>[4]</entry>
236 <entry>Reserved for future extensions. Drivers and
237applications must set the array to zero.</entry>
238 </row>
239 </tbody>
240 </tgroup>
241 </table>
242
243 <table pgwide="1" frame="none" id="parm-caps">
244 <title>Streaming Parameters Capabilites</title>
245 <tgroup cols="3">
246 &cs-def;
247 <tbody valign="top">
248 <row>
249 <entry><constant>V4L2_CAP_TIMEPERFRAME</constant></entry>
250 <entry>0x1000</entry>
251 <entry>The frame skipping/repeating controlled by the
252<structfield>timeperframe</structfield> field is supported.</entry>
253 </row>
254 </tbody>
255 </tgroup>
256 </table>
257
258 <table pgwide="1" frame="none" id="parm-flags">
259 <title>Capture Parameters Flags</title>
260 <tgroup cols="3">
261 &cs-def;
262 <tbody valign="top">
263 <row>
264 <entry><constant>V4L2_MODE_HIGHQUALITY</constant></entry>
265 <entry>0x0001</entry>
266 <entry><para>High quality imaging mode. High quality mode
267is intended for still imaging applications. The idea is to get the
268best possible image quality that the hardware can deliver. It is not
269defined how the driver writer may achieve that; it will depend on the
270hardware and the ingenuity of the driver writer. High quality mode is
271a different mode from the the regular motion video capture modes. In
272high quality mode:<itemizedlist>
273 <listitem>
274 <para>The driver may be able to capture higher
275resolutions than for motion capture.</para>
276 </listitem>
277 <listitem>
278 <para>The driver may support fewer pixel formats
279than motion capture (eg; true color).</para>
280 </listitem>
281 <listitem>
282 <para>The driver may capture and arithmetically
283combine multiple successive fields or frames to remove color edge
284artifacts and reduce the noise in the video data.
285</para>
286 </listitem>
287 <listitem>
288 <para>The driver may capture images in slices like
289a scanner in order to handle larger format images than would otherwise
290be possible. </para>
291 </listitem>
292 <listitem>
293 <para>An image capture operation may be
294significantly slower than motion capture. </para>
295 </listitem>
296 <listitem>
297 <para>Moving objects in the image might have
298excessive motion blur. </para>
299 </listitem>
300 <listitem>
301 <para>Capture might only work through the
302<function>read()</function> call.</para>
303 </listitem>
304 </itemizedlist></para></entry>
305 </row>
306 </tbody>
307 </tgroup>
308 </table>
309
310 </refsect1>
311
312 <refsect1>
313 &return-value;
314
315 <variablelist>
316 <varlistentry>
317 <term><errorcode>EINVAL</errorcode></term>
318 <listitem>
319 <para>This ioctl is not supported.</para>
320 </listitem>
321 </varlistentry>
322 </variablelist>
323 </refsect1>
324</refentry>
325
326<!--
327Local Variables:
328mode: sgml
329sgml-parent-document: "v4l2.sgml"
330indent-tabs-mode: nil
331End:
332-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-priority.xml b/Documentation/DocBook/media/v4l/vidioc-g-priority.xml
new file mode 100644
index 000000000000..5fb001978645
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-priority.xml
@@ -0,0 +1,144 @@
1<refentry id="vidioc-g-priority">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_PRIORITY</refname>
9 <refname>VIDIOC_S_PRIORITY</refname>
10 <refpurpose>Query or request the access priority associated with a
11file descriptor</refpurpose>
12 </refnamediv>
13
14 <refsynopsisdiv>
15 <funcsynopsis>
16 <funcprototype>
17 <funcdef>int <function>ioctl</function></funcdef>
18 <paramdef>int <parameter>fd</parameter></paramdef>
19 <paramdef>int <parameter>request</parameter></paramdef>
20 <paramdef>enum v4l2_priority *<parameter>argp</parameter></paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 <funcsynopsis>
24 <funcprototype>
25 <funcdef>int <function>ioctl</function></funcdef>
26 <paramdef>int <parameter>fd</parameter></paramdef>
27 <paramdef>int <parameter>request</parameter></paramdef>
28 <paramdef>const enum v4l2_priority *<parameter>argp</parameter></paramdef>
29 </funcprototype>
30 </funcsynopsis>
31 </refsynopsisdiv>
32
33 <refsect1>
34 <title>Arguments</title>
35
36 <variablelist>
37 <varlistentry>
38 <term><parameter>fd</parameter></term>
39 <listitem>
40 <para>&fd;</para>
41 </listitem>
42 </varlistentry>
43 <varlistentry>
44 <term><parameter>request</parameter></term>
45 <listitem>
46 <para>VIDIOC_G_PRIORITY, VIDIOC_S_PRIORITY</para>
47 </listitem>
48 </varlistentry>
49 <varlistentry>
50 <term><parameter>argp</parameter></term>
51 <listitem>
52 <para>Pointer to an enum v4l2_priority type.</para>
53 </listitem>
54 </varlistentry>
55 </variablelist>
56 </refsect1>
57
58 <refsect1>
59 <title>Description</title>
60
61 <para>To query the current access priority
62applications call the <constant>VIDIOC_G_PRIORITY</constant> ioctl
63with a pointer to an enum v4l2_priority variable where the driver stores
64the current priority.</para>
65
66 <para>To request an access priority applications store the
67desired priority in an enum v4l2_priority variable and call
68<constant>VIDIOC_S_PRIORITY</constant> ioctl with a pointer to this
69variable.</para>
70
71 <table frame="none" pgwide="1" id="v4l2-priority">
72 <title>enum v4l2_priority</title>
73 <tgroup cols="3">
74 &cs-def;
75 <tbody valign="top">
76 <row>
77 <entry><constant>V4L2_PRIORITY_UNSET</constant></entry>
78 <entry>0</entry>
79 <entry></entry>
80 </row>
81 <row>
82 <entry><constant>V4L2_PRIORITY_BACKGROUND</constant></entry>
83 <entry>1</entry>
84 <entry>Lowest priority, usually applications running in
85background, for example monitoring VBI transmissions. A proxy
86application running in user space will be necessary if multiple
87applications want to read from a device at this priority.</entry>
88 </row>
89 <row>
90 <entry><constant>V4L2_PRIORITY_INTERACTIVE</constant></entry>
91 <entry>2</entry>
92 <entry></entry>
93 </row>
94 <row>
95 <entry><constant>V4L2_PRIORITY_DEFAULT</constant></entry>
96 <entry>2</entry>
97 <entry>Medium priority, usually applications started and
98interactively controlled by the user. For example TV viewers, Teletext
99browsers, or just "panel" applications to change the channel or video
100controls. This is the default priority unless an application requests
101another.</entry>
102 </row>
103 <row>
104 <entry><constant>V4L2_PRIORITY_RECORD</constant></entry>
105 <entry>3</entry>
106 <entry>Highest priority. Only one file descriptor can have
107this priority, it blocks any other fd from changing device properties.
108Usually applications which must not be interrupted, like video
109recording.</entry>
110 </row>
111 </tbody>
112 </tgroup>
113 </table>
114 </refsect1>
115
116 <refsect1>
117 &return-value;
118
119 <variablelist>
120 <varlistentry>
121 <term><errorcode>EINVAL</errorcode></term>
122 <listitem>
123 <para>The requested priority value is invalid, or the
124driver does not support access priorities.</para>
125 </listitem>
126 </varlistentry>
127 <varlistentry>
128 <term><errorcode>EBUSY</errorcode></term>
129 <listitem>
130 <para>Another application already requested higher
131priority.</para>
132 </listitem>
133 </varlistentry>
134 </variablelist>
135 </refsect1>
136</refentry>
137
138<!--
139Local Variables:
140mode: sgml
141sgml-parent-document: "v4l2.sgml"
142indent-tabs-mode: nil
143End:
144-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml b/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml
new file mode 100644
index 000000000000..10e721b17374
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml
@@ -0,0 +1,264 @@
1<refentry id="vidioc-g-sliced-vbi-cap">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_SLICED_VBI_CAP</refname>
9 <refpurpose>Query sliced VBI capabilities</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_sliced_vbi_cap *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_G_SLICED_VBI_CAP</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>To find out which data services are supported by a sliced
52VBI capture or output device, applications initialize the
53<structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;,
54clear the <structfield>reserved</structfield> array and
55call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The
56driver fills in the remaining fields or returns an &EINVAL; if the
57sliced VBI API is unsupported or <structfield>type</structfield>
58is invalid.</para>
59
60 <para>Note the <structfield>type</structfield> field was added,
61and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para>
62
63 <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap">
64 <title>struct <structname>v4l2_sliced_vbi_cap</structname></title>
65 <tgroup cols="5">
66 <colspec colname="c1" colwidth="3*" />
67 <colspec colname="c2" colwidth="3*" />
68 <colspec colname="c3" colwidth="2*" />
69 <colspec colname="c4" colwidth="2*" />
70 <colspec colname="c5" colwidth="2*" />
71 <spanspec spanname="hspan" namest="c3" nameend="c5" />
72 <tbody valign="top">
73 <row>
74 <entry>__u16</entry>
75 <entry><structfield>service_set</structfield></entry>
76 <entry spanname="hspan">A set of all data services
77supported by the driver. Equal to the union of all elements of the
78<structfield>service_lines </structfield> array.</entry>
79 </row>
80 <row>
81 <entry>__u16</entry>
82 <entry><structfield>service_lines</structfield>[2][24]</entry>
83 <entry spanname="hspan">Each element of this array
84contains a set of data services the hardware can look for or insert
85into a particular scan line. Data services are defined in <xref
86 linkend="vbi-services" />. Array indices map to ITU-R
87line numbers (see also <xref
88 linkend="vbi-525" /> and <xref
89linkend="vbi-625" />) as follows:</entry>
90 </row>
91 <row>
92 <entry></entry>
93 <entry></entry>
94 <entry>Element</entry>
95 <entry>525 line systems</entry>
96 <entry>625 line systems</entry>
97 </row>
98 <row>
99 <entry></entry>
100 <entry></entry>
101 <entry><structfield>service_lines</structfield>[0][1]</entry>
102 <entry align="center">1</entry>
103 <entry align="center">1</entry>
104 </row>
105 <row>
106 <entry></entry>
107 <entry></entry>
108 <entry><structfield>service_lines</structfield>[0][23]</entry>
109 <entry align="center">23</entry>
110 <entry align="center">23</entry>
111 </row>
112 <row>
113 <entry></entry>
114 <entry></entry>
115 <entry><structfield>service_lines</structfield>[1][1]</entry>
116 <entry align="center">264</entry>
117 <entry align="center">314</entry>
118 </row>
119 <row>
120 <entry></entry>
121 <entry></entry>
122 <entry><structfield>service_lines</structfield>[1][23]</entry>
123 <entry align="center">286</entry>
124 <entry align="center">336</entry>
125 </row>
126 <row>
127 <entry></entry>
128 </row>
129 <row>
130 <entry></entry>
131 <entry></entry>
132 <entry spanname="hspan">The number of VBI lines the
133hardware can capture or output per frame, or the number of services it
134can identify on a given line may be limited. For example on PAL line
13516 the hardware may be able to look for a VPS or Teletext signal, but
136not both at the same time. Applications can learn about these limits
137using the &VIDIOC-S-FMT; ioctl as described in <xref
138 linkend="sliced" />.</entry>
139 </row>
140 <row>
141 <entry></entry>
142 </row>
143 <row>
144 <entry></entry>
145 <entry></entry>
146 <entry spanname="hspan">Drivers must set
147<structfield>service_lines</structfield>[0][0] and
148<structfield>service_lines</structfield>[1][0] to zero.</entry>
149 </row>
150 <row>
151 <entry>&v4l2-buf-type;</entry>
152 <entry><structfield>type</structfield></entry>
153 <entry>Type of the data stream, see <xref
154 linkend="v4l2-buf-type" />. Should be
155<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or
156<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry>
157 </row>
158 <row>
159 <entry>__u32</entry>
160 <entry><structfield>reserved</structfield>[3]</entry>
161 <entry spanname="hspan">This array is reserved for future
162extensions. Applications and drivers must set it to zero.</entry>
163 </row>
164 </tbody>
165 </tgroup>
166 </table>
167
168 <!-- See also dev-sliced-vbi.sgml -->
169 <table pgwide="1" frame="none" id="vbi-services">
170 <title>Sliced VBI services</title>
171 <tgroup cols="5">
172 <colspec colname="c1" colwidth="2*" />
173 <colspec colname="c2" colwidth="1*" />
174 <colspec colname="c3" colwidth="1*" />
175 <colspec colname="c4" colwidth="2*" />
176 <colspec colname="c5" colwidth="2*" />
177 <spanspec spanname='rlp' namest='c3' nameend='c5' />
178 <thead>
179 <row>
180 <entry>Symbol</entry>
181 <entry>Value</entry>
182 <entry>Reference</entry>
183 <entry>Lines, usually</entry>
184 <entry>Payload</entry>
185 </row>
186 </thead>
187 <tbody valign="top">
188 <row>
189 <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext
190System B)</entry>
191 <entry>0x0001</entry>
192 <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
193 <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
194 <entry>Last 42 of the 45 byte Teletext packet, that is
195without clock run-in and framing code, lsb first transmitted.</entry>
196 </row>
197 <row>
198 <entry><constant>V4L2_SLICED_VPS</constant></entry>
199 <entry>0x0400</entry>
200 <entry><xref linkend="ets300231" /></entry>
201 <entry>PAL line 16</entry>
202 <entry>Byte number 3 to 15 according to Figure 9 of
203ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
204 </row>
205 <row>
206 <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
207 <entry>0x1000</entry>
208 <entry><xref linkend="eia608" /></entry>
209 <entry>NTSC line 21, 284 (second field 21)</entry>
210 <entry>Two bytes in transmission order, including parity
211bit, lsb first transmitted.</entry>
212 </row>
213 <row>
214 <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
215 <entry>0x4000</entry>
216 <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry>
217 <entry>PAL/SECAM line 23</entry>
218 <entry><screen>
219Byte 0 1
220 msb lsb msb lsb
221Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
222</screen></entry>
223 </row>
224 <row>
225 <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
226 <entry>0x1000</entry>
227 <entry spanname="rlp">Set of services applicable to 525
228line systems.</entry>
229 </row>
230 <row>
231 <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
232 <entry>0x4401</entry>
233 <entry spanname="rlp">Set of services applicable to 625
234line systems.</entry>
235 </row>
236 </tbody>
237 </tgroup>
238 </table>
239
240 </refsect1>
241
242 <refsect1>
243 &return-value;
244
245 <variablelist>
246 <varlistentry>
247 <term><errorcode>EINVAL</errorcode></term>
248 <listitem>
249 <para>The device does not support sliced VBI capturing or
250output, or the value in the <structfield>type</structfield> field is
251wrong.</para>
252 </listitem>
253 </varlistentry>
254 </variablelist>
255 </refsect1>
256</refentry>
257
258<!--
259Local Variables:
260mode: sgml
261sgml-parent-document: "v4l2.sgml"
262indent-tabs-mode: nil
263End:
264-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-std.xml b/Documentation/DocBook/media/v4l/vidioc-g-std.xml
new file mode 100644
index 000000000000..912f8513e5da
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-std.xml
@@ -0,0 +1,105 @@
1<refentry id="vidioc-g-std">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_STD, VIDIOC_S_STD</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_STD</refname>
9 <refname>VIDIOC_S_STD</refname>
10 <refpurpose>Query or select the video standard of the current input</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>v4l2_std_id
20*<parameter>argp</parameter></paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 <funcsynopsis>
24 <funcprototype>
25 <funcdef>int <function>ioctl</function></funcdef>
26 <paramdef>int <parameter>fd</parameter></paramdef>
27 <paramdef>int <parameter>request</parameter></paramdef>
28 <paramdef>const v4l2_std_id
29*<parameter>argp</parameter></paramdef>
30 </funcprototype>
31 </funcsynopsis>
32 </refsynopsisdiv>
33
34 <refsect1>
35 <title>Arguments</title>
36
37 <variablelist>
38 <varlistentry>
39 <term><parameter>fd</parameter></term>
40 <listitem>
41 <para>&fd;</para>
42 </listitem>
43 </varlistentry>
44 <varlistentry>
45 <term><parameter>request</parameter></term>
46 <listitem>
47 <para>VIDIOC_G_STD, VIDIOC_S_STD</para>
48 </listitem>
49 </varlistentry>
50 <varlistentry>
51 <term><parameter>argp</parameter></term>
52 <listitem>
53 <para></para>
54 </listitem>
55 </varlistentry>
56 </variablelist>
57 </refsect1>
58
59 <refsect1>
60 <title>Description</title>
61
62 <para>To query and select the current video standard applications
63use the <constant>VIDIOC_G_STD</constant> and <constant>VIDIOC_S_STD</constant> ioctls which take a pointer to a
64&v4l2-std-id; type as argument. <constant>VIDIOC_G_STD</constant> can
65return a single flag or a set of flags as in &v4l2-standard; field
66<structfield>id</structfield>. The flags must be unambiguous such
67that they appear in only one enumerated <structname>v4l2_standard</structname> structure.</para>
68
69 <para><constant>VIDIOC_S_STD</constant> accepts one or more
70flags, being a write-only ioctl it does not return the actual new standard as
71<constant>VIDIOC_G_STD</constant> does. When no flags are given or
72the current input does not support the requested standard the driver
73returns an &EINVAL;. When the standard set is ambiguous drivers may
74return <errorcode>EINVAL</errorcode> or choose any of the requested
75standards.</para>
76 </refsect1>
77
78 <refsect1>
79 &return-value;
80
81 <variablelist>
82 <varlistentry>
83 <term><errorcode>EINVAL</errorcode></term>
84 <listitem>
85 <para>This ioctl is not supported, or the
86<constant>VIDIOC_S_STD</constant> parameter was unsuitable.</para>
87 </listitem>
88 </varlistentry>
89 <varlistentry>
90 <term><errorcode>EBUSY</errorcode></term>
91 <listitem>
92 <para>The device is busy and therefore can not change the standard</para>
93 </listitem>
94 </varlistentry>
95 </variablelist>
96 </refsect1>
97</refentry>
98
99<!--
100Local Variables:
101mode: sgml
102sgml-parent-document: "v4l2.sgml"
103indent-tabs-mode: nil
104End:
105-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml
new file mode 100644
index 000000000000..bd98c734c06b
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml
@@ -0,0 +1,535 @@
1<refentry id="vidioc-g-tuner">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_G_TUNER</refname>
9 <refname>VIDIOC_S_TUNER</refname>
10 <refpurpose>Get or set tuner attributes</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_tuner
20*<parameter>argp</parameter></paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 <funcsynopsis>
24 <funcprototype>
25 <funcdef>int <function>ioctl</function></funcdef>
26 <paramdef>int <parameter>fd</parameter></paramdef>
27 <paramdef>int <parameter>request</parameter></paramdef>
28 <paramdef>const struct v4l2_tuner
29*<parameter>argp</parameter></paramdef>
30 </funcprototype>
31 </funcsynopsis>
32 </refsynopsisdiv>
33
34 <refsect1>
35 <title>Arguments</title>
36
37 <variablelist>
38 <varlistentry>
39 <term><parameter>fd</parameter></term>
40 <listitem>
41 <para>&fd;</para>
42 </listitem>
43 </varlistentry>
44 <varlistentry>
45 <term><parameter>request</parameter></term>
46 <listitem>
47 <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para>
48 </listitem>
49 </varlistentry>
50 <varlistentry>
51 <term><parameter>argp</parameter></term>
52 <listitem>
53 <para></para>
54 </listitem>
55 </varlistentry>
56 </variablelist>
57 </refsect1>
58
59 <refsect1>
60 <title>Description</title>
61
62 <para>To query the attributes of a tuner applications initialize the
63<structfield>index</structfield> field and zero out the
64<structfield>reserved</structfield> array of a &v4l2-tuner; and call the
65<constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this
66structure. Drivers fill the rest of the structure or return an
67&EINVAL; when the index is out of bounds. To enumerate all tuners
68applications shall begin at index zero, incrementing by one until the
69driver returns <errorcode>EINVAL</errorcode>.</para>
70
71 <para>Tuners have two writable properties, the audio mode and
72the radio frequency. To change the audio mode, applications initialize
73the <structfield>index</structfield>,
74<structfield>audmode</structfield> and
75<structfield>reserved</structfield> fields and call the
76<constant>VIDIOC_S_TUNER</constant> ioctl. This will
77<emphasis>not</emphasis> change the current tuner, which is determined
78by the current video input. Drivers may choose a different audio mode
79if the requested mode is invalid or unsupported. Since this is a
80<!-- FIXME -->write-only ioctl, it does not return the actually
81selected audio mode.</para>
82
83 <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
84is available.</para>
85
86 <table pgwide="1" frame="none" id="v4l2-tuner">
87 <title>struct <structname>v4l2_tuner</structname></title>
88 <tgroup cols="3">
89 <colspec colname="c1" colwidth="1*" />
90 <colspec colname="c2" colwidth="1*" />
91 <colspec colname="c3" colwidth="1*" />
92 <colspec colname="c4" colwidth="1*" />
93 <spanspec spanname="hspan" namest="c3" nameend="c4" />
94 <tbody valign="top">
95 <row>
96 <entry>__u32</entry>
97 <entry><structfield>index</structfield></entry>
98 <entry spanname="hspan">Identifies the tuner, set by the
99application.</entry>
100 </row>
101 <row>
102 <entry>__u8</entry>
103 <entry><structfield>name</structfield>[32]</entry>
104 <entry spanname="hspan"><para>Name of the tuner, a
105NUL-terminated ASCII string. This information is intended for the
106user.<!-- FIXME Video inputs already have a name, the purpose of this
107field is not quite clear.--></para></entry>
108 </row>
109 <row>
110 <entry>&v4l2-tuner-type;</entry>
111 <entry><structfield>type</structfield></entry>
112 <entry spanname="hspan">Type of the tuner, see <xref
113 linkend="v4l2-tuner-type" />.</entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>capability</structfield></entry>
118 <entry spanname="hspan"><para>Tuner capability flags, see
119<xref linkend="tuner-capability" />. Audio flags indicate the ability
120to decode audio subprograms. They will <emphasis>not</emphasis>
121change, for example with the current video standard.</para><para>When
122the structure refers to a radio tuner only the
123<constant>V4L2_TUNER_CAP_LOW</constant>,
124<constant>V4L2_TUNER_CAP_STEREO</constant> and
125<constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</para></entry>
126 </row>
127 <row>
128 <entry>__u32</entry>
129 <entry><structfield>rangelow</structfield></entry>
130 <entry spanname="hspan">The lowest tunable frequency in
131units of 62.5 kHz, or if the <structfield>capability</structfield>
132flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
133Hz.</entry>
134 </row>
135 <row>
136 <entry>__u32</entry>
137 <entry><structfield>rangehigh</structfield></entry>
138 <entry spanname="hspan">The highest tunable frequency in
139units of 62.5 kHz, or if the <structfield>capability</structfield>
140flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
141Hz.</entry>
142 </row>
143 <row>
144 <entry>__u32</entry>
145 <entry><structfield>rxsubchans</structfield></entry>
146 <entry spanname="hspan"><para>Some tuners or audio
147decoders can determine the received audio subprograms by analyzing
148audio carriers, pilot tones or other indicators. To pass this
149information drivers set flags defined in <xref
150 linkend="tuner-rxsubchans" /> in this field. For
151example:</para></entry>
152 </row>
153 <row>
154 <entry></entry>
155 <entry></entry>
156 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
157 <entry>receiving mono audio</entry>
158 </row>
159 <row>
160 <entry></entry>
161 <entry></entry>
162 <entry><constant>STEREO | SAP</constant></entry>
163 <entry>receiving stereo audio and a secondary audio
164program</entry>
165 </row>
166 <row>
167 <entry></entry>
168 <entry></entry>
169 <entry><constant>MONO | STEREO</constant></entry>
170 <entry>receiving mono or stereo audio, the hardware cannot
171distinguish</entry>
172 </row>
173 <row>
174 <entry></entry>
175 <entry></entry>
176 <entry><constant>LANG1 | LANG2</constant></entry>
177 <entry>receiving bilingual audio</entry>
178 </row>
179 <row>
180 <entry></entry>
181 <entry></entry>
182 <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry>
183 <entry>receiving mono, stereo or bilingual
184audio</entry>
185 </row>
186 <row>
187 <entry></entry>
188 <entry></entry>
189 <entry spanname="hspan"><para>When the
190<constant>V4L2_TUNER_CAP_STEREO</constant>,
191<constant>_LANG1</constant>, <constant>_LANG2</constant> or
192<constant>_SAP</constant> flag is cleared in the
193<structfield>capability</structfield> field, the corresponding
194<constant>V4L2_TUNER_SUB_</constant> flag must not be set
195here.</para><para>This field is valid only if this is the tuner of the
196current video input, or when the structure refers to a radio
197tuner.</para></entry>
198 </row>
199 <row>
200 <entry>__u32</entry>
201 <entry><structfield>audmode</structfield></entry>
202 <entry spanname="hspan"><para>The selected audio mode, see
203<xref linkend="tuner-audmode" /> for valid values. The audio mode does
204not affect audio subprogram detection, and like a <link
205linkend="control">control</link> it does not automatically change
206unless the requested mode is invalid or unsupported. See <xref
207 linkend="tuner-matrix" /> for possible results when
208the selected and received audio programs do not
209match.</para><para>Currently this is the only field of struct
210<structname>v4l2_tuner</structname> applications can
211change.</para></entry>
212 </row>
213 <row>
214 <entry>__u32</entry>
215 <entry><structfield>signal</structfield></entry>
216 <entry spanname="hspan">The signal strength if known, ranging
217from 0 to 65535. Higher values indicate a better signal.</entry>
218 </row>
219 <row>
220 <entry>__s32</entry>
221 <entry><structfield>afc</structfield></entry>
222 <entry spanname="hspan">Automatic frequency control: When the
223<structfield>afc</structfield> value is negative, the frequency is too
224low, when positive too high.<!-- FIXME need example what to do when it never
225settles at zero, &ie; range is what? --></entry>
226 </row>
227 <row>
228 <entry>__u32</entry>
229 <entry><structfield>reserved</structfield>[4]</entry>
230 <entry spanname="hspan">Reserved for future extensions. Drivers and
231applications must set the array to zero.</entry>
232 </row>
233 </tbody>
234 </tgroup>
235 </table>
236
237 <table pgwide="1" frame="none" id="v4l2-tuner-type">
238 <title>enum v4l2_tuner_type</title>
239 <tgroup cols="3">
240 &cs-def;
241 <tbody valign="top">
242 <row>
243 <entry><constant>V4L2_TUNER_RADIO</constant></entry>
244 <entry>1</entry>
245 <entry></entry>
246 </row>
247 <row>
248 <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry>
249 <entry>2</entry>
250 <entry></entry>
251 </row>
252 </tbody>
253 </tgroup>
254 </table>
255
256 <table pgwide="1" frame="none" id="tuner-capability">
257 <title>Tuner and Modulator Capability Flags</title>
258 <tgroup cols="3">
259 &cs-def;
260 <tbody valign="top">
261 <row>
262 <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry>
263 <entry>0x0001</entry>
264 <entry>When set, tuning frequencies are expressed in units of
26562.5&nbsp;Hz, otherwise in units of 62.5&nbsp;kHz.</entry>
266 </row>
267 <row>
268 <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry>
269 <entry>0x0002</entry>
270 <entry>This is a multi-standard tuner; the video standard
271can or must be switched. (B/G PAL tuners for example are typically not
272 considered multi-standard because the video standard is automatically
273 determined from the frequency band.) The set of supported video
274 standards is available from the &v4l2-input; pointing to this tuner,
275 see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only
276 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
277 </row>
278 <row>
279 <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry>
280 <entry>0x0010</entry>
281 <entry>Stereo audio reception is supported.</entry>
282 </row>
283 <row>
284 <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry>
285 <entry>0x0040</entry>
286 <entry>Reception of the primary language of a bilingual
287audio program is supported. Bilingual audio is a feature of
288two-channel systems, transmitting the primary language monaural on the
289main audio carrier and a secondary language monaural on a second
290carrier. Only
291 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
292 </row>
293 <row>
294 <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry>
295 <entry>0x0020</entry>
296 <entry>Reception of the secondary language of a bilingual
297audio program is supported. Only
298 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
299 </row>
300 <row>
301 <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry>
302 <entry>0x0020</entry>
303 <entry><para>Reception of a secondary audio program is
304supported. This is a feature of the BTSC system which accompanies the
305NTSC video standard. Two audio carriers are available for mono or
306stereo transmissions of a primary language, and an independent third
307carrier for a monaural secondary language. Only
308 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the
309<constant>V4L2_TUNER_CAP_LANG2</constant> and
310<constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms.
311<constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner
312supports the <constant>V4L2_STD_NTSC_M</constant> video
313standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry>
314 </row>
315 <row>
316 <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry>
317 <entry>0x0080</entry>
318 <entry>RDS capture is supported. This capability is only valid for
319radio tuners.</entry>
320 </row>
321 </tbody>
322 </tgroup>
323 </table>
324
325 <table pgwide="1" frame="none" id="tuner-rxsubchans">
326 <title>Tuner Audio Reception Flags</title>
327 <tgroup cols="3">
328 &cs-def;
329 <tbody valign="top">
330 <row>
331 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
332 <entry>0x0001</entry>
333 <entry>The tuner receives a mono audio signal.</entry>
334 </row>
335 <row>
336 <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
337 <entry>0x0002</entry>
338 <entry>The tuner receives a stereo audio signal.</entry>
339 </row>
340 <row>
341 <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
342 <entry>0x0008</entry>
343 <entry>The tuner receives the primary language of a
344bilingual audio signal. Drivers must clear this flag when the current
345video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
346 </row>
347 <row>
348 <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
349 <entry>0x0004</entry>
350 <entry>The tuner receives the secondary language of a
351bilingual audio signal (or a second audio program).</entry>
352 </row>
353 <row>
354 <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
355 <entry>0x0004</entry>
356 <entry>The tuner receives a Second Audio Program. Note the
357<constant>V4L2_TUNER_SUB_LANG2</constant> and
358<constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The
359<constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the
360current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
361 </row>
362 <row>
363 <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
364 <entry>0x0010</entry>
365 <entry>The tuner receives an RDS channel.</entry>
366 </row>
367 </tbody>
368 </tgroup>
369 </table>
370
371 <table pgwide="1" frame="none" id="tuner-audmode">
372 <title>Tuner Audio Modes</title>
373 <tgroup cols="3">
374 &cs-def;
375 <tbody valign="top">
376 <row>
377 <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry>
378 <entry>0</entry>
379 <entry>Play mono audio. When the tuner receives a stereo
380signal this a down-mix of the left and right channel. When the tuner
381receives a bilingual or SAP signal this mode selects the primary
382language.</entry>
383 </row>
384 <row>
385 <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry>
386 <entry>1</entry>
387 <entry><para>Play stereo audio. When the tuner receives
388bilingual audio it may play different languages on the left and right
389channel or the primary language is played on both channels.</para><para>Playing
390different languages in this mode is
391deprecated. New drivers should do this only in
392<constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner
393receives no stereo signal or does not support stereo reception the
394driver shall fall back to <constant>MODE_MONO</constant>.</para></entry>
395 </row>
396 <row>
397 <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry>
398 <entry>3</entry>
399 <entry>Play the primary language, mono or stereo. Only
400<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
401mode.</entry>
402 </row>
403 <row>
404 <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry>
405 <entry>2</entry>
406 <entry>Play the secondary language, mono. When the tuner
407receives no bilingual audio or SAP, or their reception is not
408supported the driver shall fall back to mono or stereo mode. Only
409<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
410mode.</entry>
411 </row>
412 <row>
413 <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry>
414 <entry>2</entry>
415 <entry>Play the Second Audio Program. When the tuner
416receives no bilingual audio or SAP, or their reception is not
417supported the driver shall fall back to mono or stereo mode. Only
418<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode.
419Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and
420<constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry>
421 </row>
422 <row>
423 <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry>
424 <entry>4</entry>
425 <entry>Play the primary language on the left channel, the
426secondary language on the right channel. When the tuner receives no
427bilingual audio or SAP, it shall fall back to
428<constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>.
429Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
430mode.</entry>
431 </row>
432 </tbody>
433 </tgroup>
434 </table>
435
436 <table pgwide="1" frame="all" id="tuner-matrix">
437 <title>Tuner Audio Matrix</title>
438 <tgroup cols="6" align="center">
439 <colspec align="left" />
440 <colspec colname="c2" colwidth="1*" />
441 <colspec colwidth="1*" />
442 <colspec colwidth="1*" />
443 <colspec colnum="6" colname="c6" colwidth="1*" />
444 <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" />
445 <thead>
446 <row>
447 <entry></entry>
448 <entry spanname="hspan">Selected
449<constant>V4L2_TUNER_MODE_</constant></entry>
450 </row>
451 <row>
452 <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry>
453 <entry><constant>MONO</constant></entry>
454 <entry><constant>STEREO</constant></entry>
455 <entry><constant>LANG1</constant></entry>
456 <entry><constant>LANG2 = SAP</constant></entry>
457 <entry><constant>LANG1_LANG2</constant><footnote><para>This
458mode has been added in Linux 2.6.17 and may not be supported by older
459drivers.</para></footnote></entry>
460 </row>
461 </thead>
462 <tbody valign="top">
463 <row>
464 <entry><constant>MONO</constant></entry>
465 <entry>Mono</entry>
466 <entry>Mono/Mono</entry>
467 <entry>Mono</entry>
468 <entry>Mono</entry>
469 <entry>Mono/Mono</entry>
470 </row>
471 <row>
472 <entry><constant>MONO | SAP</constant></entry>
473 <entry>Mono</entry>
474 <entry>Mono/Mono</entry>
475 <entry>Mono</entry>
476 <entry>SAP</entry>
477 <entry>Mono/SAP (preferred) or Mono/Mono</entry>
478 </row>
479 <row>
480 <entry><constant>STEREO</constant></entry>
481 <entry>L+R</entry>
482 <entry>L/R</entry>
483 <entry>Stereo L/R (preferred) or Mono L+R</entry>
484 <entry>Stereo L/R (preferred) or Mono L+R</entry>
485 <entry>L/R (preferred) or L+R/L+R</entry>
486 </row>
487 <row>
488 <entry><constant>STEREO | SAP</constant></entry>
489 <entry>L+R</entry>
490 <entry>L/R</entry>
491 <entry>Stereo L/R (preferred) or Mono L+R</entry>
492 <entry>SAP</entry>
493 <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry>
494 </row>
495 <row>
496 <entry><constant>LANG1 | LANG2</constant></entry>
497 <entry>Language&nbsp;1</entry>
498 <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of
499both languages in <constant>MODE_STEREO</constant> is deprecated. In
500the future drivers should produce only the primary language in this
501mode. Applications should request
502<constant>MODE_LANG1_LANG2</constant> to record both languages or a
503stereo signal.</para></footnote>) or
504Lang1/Lang1</entry>
505 <entry>Language&nbsp;1</entry>
506 <entry>Language&nbsp;2</entry>
507 <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry>
508 </row>
509 </tbody>
510 </tgroup>
511 </table>
512 </refsect1>
513
514 <refsect1>
515 &return-value;
516
517 <variablelist>
518 <varlistentry>
519 <term><errorcode>EINVAL</errorcode></term>
520 <listitem>
521 <para>The &v4l2-tuner; <structfield>index</structfield> is
522out of bounds.</para>
523 </listitem>
524 </varlistentry>
525 </variablelist>
526 </refsect1>
527</refentry>
528
529<!--
530Local Variables:
531mode: sgml
532sgml-parent-document: "v4l2.sgml"
533indent-tabs-mode: nil
534End:
535-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-log-status.xml b/Documentation/DocBook/media/v4l/vidioc-log-status.xml
new file mode 100644
index 000000000000..2634b7c88b58
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-log-status.xml
@@ -0,0 +1,58 @@
1<refentry id="vidioc-log-status">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_LOG_STATUS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_LOG_STATUS</refname>
9 <refpurpose>Log driver status 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 </funcprototype>
19 </funcsynopsis>
20 </refsynopsisdiv>
21
22 <refsect1>
23 <title>Description</title>
24
25 <para>As the video/audio devices become more complicated it
26becomes harder to debug problems. When this ioctl is called the driver
27will output the current device status to the kernel log. This is
28particular useful when dealing with problems like no sound, no video
29and incorrectly tuned channels. Also many modern devices autodetect
30video and audio standards and this ioctl will report what the device
31thinks what the standard is. Mismatches may give an indication where
32the problem is.</para>
33
34 <para>This ioctl is optional and not all drivers support it. It
35was introduced in Linux 2.6.15.</para>
36 </refsect1>
37
38 <refsect1>
39 &return-value;
40
41 <variablelist>
42 <varlistentry>
43 <term><errorcode>EINVAL</errorcode></term>
44 <listitem>
45 <para>The driver does not support this ioctl.</para>
46 </listitem>
47 </varlistentry>
48 </variablelist>
49 </refsect1>
50</refentry>
51
52<!--
53Local Variables:
54mode: sgml
55sgml-parent-document: "v4l2.sgml"
56indent-tabs-mode: nil
57End:
58-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-overlay.xml b/Documentation/DocBook/media/v4l/vidioc-overlay.xml
new file mode 100644
index 000000000000..1036c582cc15
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-overlay.xml
@@ -0,0 +1,83 @@
1<refentry id="vidioc-overlay">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_OVERLAY</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_OVERLAY</refname>
9 <refpurpose>Start or stop video overlay</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>const int *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_OVERLAY</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>This ioctl is part of the <link linkend="overlay">video
52 overlay</link> I/O method. Applications call
53 <constant>VIDIOC_OVERLAY</constant> to start or stop the
54 overlay. It takes a pointer to an integer which must be set to
55 zero by the application to stop overlay, to one to start.</para>
56
57 <para>Drivers do not support &VIDIOC-STREAMON; or
58&VIDIOC-STREAMOFF; with <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
59 </refsect1>
60
61 <refsect1>
62 &return-value;
63
64 <variablelist>
65 <varlistentry>
66 <term><errorcode>EINVAL</errorcode></term>
67 <listitem>
68 <para>Video overlay is not supported, or the
69parameters have not been set up. See <xref
70linkend="overlay" /> for the necessary steps.</para>
71 </listitem>
72 </varlistentry>
73 </variablelist>
74 </refsect1>
75</refentry>
76
77<!--
78Local Variables:
79mode: sgml
80sgml-parent-document: "v4l2.sgml"
81indent-tabs-mode: nil
82End:
83-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
new file mode 100644
index 000000000000..f2b11f8a4031
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml
@@ -0,0 +1,194 @@
1<refentry id="vidioc-qbuf">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QBUF, VIDIOC_DQBUF</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_QBUF</refname>
9 <refname>VIDIOC_DQBUF</refname>
10 <refpurpose>Exchange a buffer with the driver</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_buffer *<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_QBUF, VIDIOC_DQBUF</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>Applications call the <constant>VIDIOC_QBUF</constant> ioctl
53to enqueue an empty (capturing) or filled (output) buffer in the
54driver's incoming queue. The semantics depend on the selected I/O
55method.</para>
56
57 <para>To enqueue a buffer applications set the <structfield>type</structfield>
58field of a &v4l2-buffer; to the same buffer type as was previously used
59with &v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
60<structfield>type</structfield>. Applications must also set the
61<structfield>index</structfield> field. Valid index numbers range from
62zero to the number of buffers allocated with &VIDIOC-REQBUFS;
63(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
64contents of the struct <structname>v4l2_buffer</structname> returned
65by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
66intended for output (<structfield>type</structfield> is
67<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>,
68<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, or
69<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
70initialize the <structfield>bytesused</structfield>,
71<structfield>field</structfield> and
72<structfield>timestamp</structfield> fields, see <xref
73linkend="buffer" /> for details.
74Applications must also set <structfield>flags</structfield> to 0. If a driver
75supports capturing from specific video inputs and you want to specify a video
76input, then <structfield>flags</structfield> should be set to
77<constant>V4L2_BUF_FLAG_INPUT</constant> and the field
78<structfield>input</structfield> must be initialized to the desired input.
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.
84</para>
85
86 <para>To enqueue a <link linkend="mmap">memory mapped</link>
87buffer applications set the <structfield>memory</structfield>
88field to <constant>V4L2_MEMORY_MMAP</constant>. When
89<constant>VIDIOC_QBUF</constant> is called with a pointer to this
90structure the driver sets the
91<constant>V4L2_BUF_FLAG_MAPPED</constant> and
92<constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
93<constant>V4L2_BUF_FLAG_DONE</constant> flag in the
94<structfield>flags</structfield> field, or it returns an
95&EINVAL;.</para>
96
97 <para>To enqueue a <link linkend="userp">user pointer</link>
98buffer applications set the <structfield>memory</structfield>
99field to <constant>V4L2_MEMORY_USERPTR</constant>, the
100<structfield>m.userptr</structfield> field to the address of the
101buffer and <structfield>length</structfield> to its size. When the multi-planar
102API is used, <structfield>m.userptr</structfield> and
103<structfield>length</structfield> members of the passed array of &v4l2-plane;
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
108<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
109<structfield>flags</structfield> field, or it returns an error code.
110This ioctl locks the memory pages of the buffer in physical memory,
111they cannot be swapped out to disk. Buffers remain locked until
112dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl is
113called, or until the device is closed.</para>
114
115 <para>Applications call the <constant>VIDIOC_DQBUF</constant>
116ioctl to dequeue a filled (capturing) or displayed (output) buffer
117from the driver's outgoing queue. They just set the
118<structfield>type</structfield>, <structfield>memory</structfield>
119and <structfield>reserved</structfield>
120fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
121is called with a pointer to this structure the driver fills the
122remaining fields or returns an error code. The driver may also set
123<constant>V4L2_BUF_FLAG_ERROR</constant> in the <structfield>flags</structfield>
124field. It indicates a non-critical (recoverable) streaming error. In such case
125the application may continue as normal, but should be aware that data in the
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>
129
130 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
131buffer is in the outgoing queue. When the
132<constant>O_NONBLOCK</constant> flag was given to the &func-open;
133function, <constant>VIDIOC_DQBUF</constant> returns immediately
134with an &EAGAIN; when no buffer is available.</para>
135
136 <para>The <structname>v4l2_buffer</structname> structure is
137specified in <xref linkend="buffer" />.</para>
138 </refsect1>
139
140 <refsect1>
141 &return-value;
142
143 <variablelist>
144 <varlistentry>
145 <term><errorcode>EAGAIN</errorcode></term>
146 <listitem>
147 <para>Non-blocking I/O has been selected using
148<constant>O_NONBLOCK</constant> and no buffer was in the outgoing
149queue.</para>
150 </listitem>
151 </varlistentry>
152 <varlistentry>
153 <term><errorcode>EINVAL</errorcode></term>
154 <listitem>
155 <para>The buffer <structfield>type</structfield> is not
156supported, or the <structfield>index</structfield> is out of bounds,
157or no buffers have been allocated yet, or the
158<structfield>userptr</structfield> or
159<structfield>length</structfield> are invalid.</para>
160 </listitem>
161 </varlistentry>
162 <varlistentry>
163 <term><errorcode>ENOMEM</errorcode></term>
164 <listitem>
165 <para>Not enough physical or virtual memory was available to
166enqueue a user pointer buffer.</para>
167 </listitem>
168 </varlistentry>
169 <varlistentry>
170 <term><errorcode>EIO</errorcode></term>
171 <listitem>
172 <para><constant>VIDIOC_DQBUF</constant> failed due to an
173internal error. Can also indicate temporary problems like signal
174loss. Note the driver might dequeue an (empty) buffer despite
175returning an error, or even stop capturing. Reusing such buffer may be unsafe
176though and its details (e.g. <structfield>index</structfield>) may not be
177returned either. It is recommended that drivers indicate recoverable errors
178by setting the <constant>V4L2_BUF_FLAG_ERROR</constant> and returning 0 instead.
179In that case the application should be able to safely reuse the buffer and
180continue streaming.
181 </para>
182 </listitem>
183 </varlistentry>
184 </variablelist>
185 </refsect1>
186</refentry>
187
188<!--
189Local Variables:
190mode: sgml
191sgml-parent-document: "v4l2.sgml"
192indent-tabs-mode: nil
193End:
194-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml
new file mode 100644
index 000000000000..d272f7ab91b8
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml
@@ -0,0 +1,87 @@
1<refentry id="vidioc-query-dv-preset">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QUERY_DV_PRESET</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_QUERY_DV_PRESET</refname>
9 <refpurpose>Sense the DV preset received by the current
10input</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_dv_preset *<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_QUERY_DV_PRESET</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>The hardware may be able to detect the current DV preset
53automatically, similar to sensing the video standard. To do so, applications
54call <constant> VIDIOC_QUERY_DV_PRESET</constant> with a pointer to a
55&v4l2-dv-preset; type. Once the hardware detects a preset, that preset is
56returned in the preset field of &v4l2-dv-preset;. If the preset could not be
57detected because there was no signal, or the signal was unreliable, or the
58signal did not map to a supported preset, then the value V4L2_DV_INVALID is
59returned.</para>
60 </refsect1>
61
62 <refsect1>
63 &return-value;
64 <variablelist>
65 <varlistentry>
66 <term><errorcode>EINVAL</errorcode></term>
67 <listitem>
68 <para>This ioctl is not supported.</para>
69 </listitem>
70 </varlistentry>
71 <varlistentry>
72 <term><errorcode>EBUSY</errorcode></term>
73 <listitem>
74 <para>The device is busy and therefore can not sense the preset</para>
75 </listitem>
76 </varlistentry>
77 </variablelist>
78 </refsect1>
79</refentry>
80
81<!--
82Local Variables:
83mode: sgml
84sgml-parent-document: "v4l2.sgml"
85indent-tabs-mode: nil
86End:
87-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-querybuf.xml b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml
new file mode 100644
index 000000000000..5c104d42d31c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-querybuf.xml
@@ -0,0 +1,110 @@
1<refentry id="vidioc-querybuf">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QUERYBUF</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_QUERYBUF</refname>
9 <refpurpose>Query the status of a buffer</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_buffer *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_QUERYBUF</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>This ioctl is part of the <link linkend="mmap">memory
52mapping</link> I/O method. It can be used to query the status of a
53buffer at any time after buffers have been allocated with the
54&VIDIOC-REQBUFS; ioctl.</para>
55
56 <para>Applications set the <structfield>type</structfield> field
57 of a &v4l2-buffer; to the same buffer type as was previously used with
58&v4l2-format; <structfield>type</structfield> and &v4l2-requestbuffers;
59<structfield>type</structfield>, and the <structfield>index</structfield>
60 field. Valid index numbers range from zero
61to the number of buffers allocated with &VIDIOC-REQBUFS;
62 (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.
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.
68After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
69 this structure drivers return an error code or fill the rest of
70the structure.</para>
71
72 <para>In the <structfield>flags</structfield> field the
73<constant>V4L2_BUF_FLAG_MAPPED</constant>,
74<constant>V4L2_BUF_FLAG_QUEUED</constant> and
75<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The
76<structfield>memory</structfield> field will be set to the current
77I/O method. For the single-planar API, the <structfield>m.offset</structfield>
78contains the offset of the buffer from the start of the device memory,
79the <structfield>length</structfield> field its size. For the multi-planar API,
80fields <structfield>m.mem_offset</structfield> and
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>
84
85 <para>The <structname>v4l2_buffer</structname> structure is
86 specified in <xref linkend="buffer" />.</para>
87 </refsect1>
88
89 <refsect1>
90 &return-value;
91
92 <variablelist>
93 <varlistentry>
94 <term><errorcode>EINVAL</errorcode></term>
95 <listitem>
96 <para>The buffer <structfield>type</structfield> is not
97supported, or the <structfield>index</structfield> is out of bounds.</para>
98 </listitem>
99 </varlistentry>
100 </variablelist>
101 </refsect1>
102</refentry>
103
104<!--
105Local Variables:
106mode: sgml
107sgml-parent-document: "v4l2.sgml"
108indent-tabs-mode: nil
109End:
110-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml
new file mode 100644
index 000000000000..f29f1b86213c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml
@@ -0,0 +1,303 @@
1<refentry id="vidioc-querycap">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QUERYCAP</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_QUERYCAP</refname>
9 <refpurpose>Query device capabilities</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_capability *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_QUERYCAP</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>All V4L2 devices support the
52<constant>VIDIOC_QUERYCAP</constant> ioctl. It is used to identify
53kernel devices compatible with this specification and to obtain
54information about driver and hardware capabilities. The ioctl takes a
55pointer to a &v4l2-capability; which is filled by the driver. When the
56driver is not compatible with this specification the ioctl returns an
57&EINVAL;.</para>
58
59 <table pgwide="1" frame="none" id="v4l2-capability">
60 <title>struct <structname>v4l2_capability</structname></title>
61 <tgroup cols="3">
62 &cs-str;
63 <tbody valign="top">
64 <row>
65 <entry>__u8</entry>
66 <entry><structfield>driver</structfield>[16]</entry>
67 <entry><para>Name of the driver, a unique NUL-terminated
68ASCII string. For example: "bttv". Driver specific applications can
69use this information to verify the driver identity. It is also useful
70to work around known bugs, or to identify drivers in error reports.
71The driver version is stored in the <structfield>version</structfield>
72field.</para><para>Storing strings in fixed sized arrays is bad
73practice but unavoidable here. Drivers and applications should take
74precautions to never read or write beyond the end of the array and to
75make sure the strings are properly NUL-terminated.</para></entry>
76 </row>
77 <row>
78 <entry>__u8</entry>
79 <entry><structfield>card</structfield>[32]</entry>
80 <entry>Name of the device, a NUL-terminated ASCII string.
81For example: "Yoyodyne TV/FM". One driver may support different brands
82or models of video hardware. This information is intended for users,
83for example in a menu of available devices. Since multiple TV cards of
84the same brand may be installed which are supported by the same
85driver, this name should be combined with the character device file
86name (&eg; <filename>/dev/video2</filename>) or the
87<structfield>bus_info</structfield> string to avoid
88ambiguities.</entry>
89 </row>
90 <row>
91 <entry>__u8</entry>
92 <entry><structfield>bus_info</structfield>[32]</entry>
93 <entry>Location of the device in the system, a
94NUL-terminated ASCII string. For example: "PCI Slot 4". This
95information is intended for users, to distinguish multiple
96identical devices. If no such information is available the field may
97simply count the devices controlled by the driver, or contain the
98empty string (<structfield>bus_info</structfield>[0] = 0).<!-- XXX pci_dev->slot_name example --></entry>
99 </row>
100 <row>
101 <entry>__u32</entry>
102 <entry><structfield>version</structfield></entry>
103 <entry><para>Version number of the driver. Together with
104the <structfield>driver</structfield> field this identifies a
105particular driver. The version number is formatted using the
106<constant>KERNEL_VERSION()</constant> macro:</para></entry>
107 </row>
108 <row>
109 <entry spanname="hspan"><para>
110<programlisting>
111#define KERNEL_VERSION(a,b,c) (((a) &lt;&lt; 16) + ((b) &lt;&lt; 8) + (c))
112
113__u32 version = KERNEL_VERSION(0, 8, 1);
114
115printf ("Version: %u.%u.%u\n",
116 (version &gt;&gt; 16) &amp; 0xFF,
117 (version &gt;&gt; 8) &amp; 0xFF,
118 version &amp; 0xFF);
119</programlisting></para></entry>
120 </row>
121 <row>
122 <entry>__u32</entry>
123 <entry><structfield>capabilities</structfield></entry>
124 <entry>Device capabilities, see <xref
125 linkend="device-capabilities" />.</entry>
126 </row>
127 <row>
128 <entry>__u32</entry>
129 <entry><structfield>reserved</structfield>[4]</entry>
130 <entry>Reserved for future extensions. Drivers must set
131this array to zero.</entry>
132 </row>
133 </tbody>
134 </tgroup>
135 </table>
136
137 <table pgwide="1" frame="none" id="device-capabilities">
138 <title>Device Capabilities Flags</title>
139 <tgroup cols="3">
140 &cs-def;
141 <tbody valign="top">
142 <row>
143 <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
144 <entry>0x00000001</entry>
145 <entry>The device supports the single-planar API through the <link
146linkend="capture">Video Capture</link> interface.</entry>
147 </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>
156 <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry>
157 <entry>0x00000002</entry>
158 <entry>The device supports the single-planar API through the <link
159linkend="output">Video Output</link> interface.</entry>
160 </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>
169 <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
170 <entry>0x00000004</entry>
171 <entry>The device supports the <link
172linkend="overlay">Video Overlay</link> interface. A video overlay device
173typically stores captured images directly in the video memory of a
174graphics card, with hardware clipping and scaling.</entry>
175 </row>
176 <row>
177 <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
178 <entry>0x00000010</entry>
179 <entry>The device supports the <link linkend="raw-vbi">Raw
180VBI Capture</link> interface, providing Teletext and Closed Caption
181data.</entry>
182 </row>
183 <row>
184 <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry>
185 <entry>0x00000020</entry>
186 <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry>
187 </row>
188 <row>
189 <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry>
190 <entry>0x00000040</entry>
191 <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry>
192 </row>
193 <row>
194 <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry>
195 <entry>0x00000080</entry>
196 <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry>
197 </row>
198 <row>
199 <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry>
200 <entry>0x00000100</entry>
201 <entry>The device supports the <link linkend="rds">RDS</link> capture interface.</entry>
202 </row>
203 <row>
204 <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry>
205 <entry>0x00000200</entry>
206 <entry>The device supports the <link linkend="osd">Video
207Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video
208Overlay</wordasword> interface, this is a secondary function of video
209output devices and overlays an image onto an outgoing video signal.
210When the driver sets this flag, it must clear the
211<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice
212versa.<footnote><para>The &v4l2-framebuffer; lacks an
213&v4l2-buf-type; field, therefore the type of overlay is implied by the
214driver capabilities.</para></footnote></entry>
215 </row>
216 <row>
217 <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry>
218 <entry>0x00000400</entry>
219 <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for
220hardware frequency seeking.</entry>
221 </row>
222 <row>
223 <entry><constant>V4L2_CAP_RDS_OUTPUT</constant></entry>
224 <entry>0x00000800</entry>
225 <entry>The device supports the <link linkend="rds">RDS</link> output interface.</entry>
226 </row>
227 <row>
228 <entry><constant>V4L2_CAP_TUNER</constant></entry>
229 <entry>0x00010000</entry>
230 <entry>The device has some sort of tuner to
231receive RF-modulated video signals. For more information about
232tuner programming see
233<xref linkend="tuner" />.</entry>
234 </row>
235 <row>
236 <entry><constant>V4L2_CAP_AUDIO</constant></entry>
237 <entry>0x00020000</entry>
238 <entry>The device has audio inputs or outputs. It may or
239may not support audio recording or playback, in PCM or compressed
240formats. PCM audio support must be implemented as ALSA or OSS
241interface. For more information on audio inputs and outputs see <xref
242 linkend="audio" />.</entry>
243 </row>
244 <row>
245 <entry><constant>V4L2_CAP_RADIO</constant></entry>
246 <entry>0x00040000</entry>
247 <entry>This is a radio receiver.</entry>
248 </row>
249 <row>
250 <entry><constant>V4L2_CAP_MODULATOR</constant></entry>
251 <entry>0x00080000</entry>
252 <entry>The device has some sort of modulator to
253emit RF-modulated video/audio signals. For more information about
254modulator programming see
255<xref linkend="tuner" />.</entry>
256 </row>
257 <row>
258 <entry><constant>V4L2_CAP_READWRITE</constant></entry>
259 <entry>0x01000000</entry>
260 <entry>The device supports the <link
261linkend="rw">read()</link> and/or <link linkend="rw">write()</link>
262I/O methods.</entry>
263 </row>
264 <row>
265 <entry><constant>V4L2_CAP_ASYNCIO</constant></entry>
266 <entry>0x02000000</entry>
267 <entry>The device supports the <link
268linkend="async">asynchronous</link> I/O methods.</entry>
269 </row>
270 <row>
271 <entry><constant>V4L2_CAP_STREAMING</constant></entry>
272 <entry>0x04000000</entry>
273 <entry>The device supports the <link
274linkend="mmap">streaming</link> I/O method.</entry>
275 </row>
276 </tbody>
277 </tgroup>
278 </table>
279 </refsect1>
280
281 <refsect1>
282 &return-value;
283
284 <variablelist>
285 <varlistentry>
286 <term><errorcode>EINVAL</errorcode></term>
287 <listitem>
288 <para>The device is not compatible with this
289specification.</para>
290 </listitem>
291 </varlistentry>
292 </variablelist>
293 </refsect1>
294</refentry>
295
296<!--
297Local Variables:
298mode: sgml
299sgml-parent-document: "v4l2.sgml"
300indent-tabs-mode: nil
301End:
302-->
303
diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
new file mode 100644
index 000000000000..0d5e8283cf32
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
@@ -0,0 +1,434 @@
1<refentry id="vidioc-queryctrl">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_QUERYCTRL</refname>
9 <refname>VIDIOC_QUERYMENU</refname>
10 <refpurpose>Enumerate controls and menu control items</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_queryctrl *<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>struct v4l2_querymenu *<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_QUERYCTRL, VIDIOC_QUERYMENU</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 <para>To query the attributes of a control applications set the
61<structfield>id</structfield> field of a &v4l2-queryctrl; and call the
62<constant>VIDIOC_QUERYCTRL</constant> ioctl with a pointer to this
63structure. The driver fills the rest of the structure or returns an
64&EINVAL; when the <structfield>id</structfield> is invalid.</para>
65
66 <para>It is possible to enumerate controls by calling
67<constant>VIDIOC_QUERYCTRL</constant> with successive
68<structfield>id</structfield> values starting from
69<constant>V4L2_CID_BASE</constant> up to and exclusive
70<constant>V4L2_CID_BASE_LASTP1</constant>. Drivers may return
71<errorcode>EINVAL</errorcode> if a control in this range is not
72supported. Further applications can enumerate private controls, which
73are not defined in this specification, by starting at
74<constant>V4L2_CID_PRIVATE_BASE</constant> and incrementing
75<structfield>id</structfield> until the driver returns
76<errorcode>EINVAL</errorcode>.</para>
77
78 <para>In both cases, when the driver sets the
79<constant>V4L2_CTRL_FLAG_DISABLED</constant> flag in the
80<structfield>flags</structfield> field this control is permanently
81disabled and should be ignored by the application.<footnote>
82 <para><constant>V4L2_CTRL_FLAG_DISABLED</constant> was
83intended for two purposes: Drivers can skip predefined controls not
84supported by the hardware (although returning EINVAL would do as
85well), or disable predefined and private controls after hardware
86detection without the trouble of reordering control arrays and indices
87(EINVAL cannot be used to skip private controls because it would
88prematurely end the enumeration).</para></footnote></para>
89
90 <para>When the application ORs <structfield>id</structfield> with
91<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> the driver returns the
92next supported control, or <errorcode>EINVAL</errorcode> if there is
93none. Drivers which do not support this flag yet always return
94<errorcode>EINVAL</errorcode>.</para>
95
96 <para>Additional information is required for menu controls: the
97names of the menu items. To query them applications set the
98<structfield>id</structfield> and <structfield>index</structfield>
99fields of &v4l2-querymenu; and call the
100<constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this
101structure. The driver fills the rest of the structure or returns an
102&EINVAL; when the <structfield>id</structfield> or
103<structfield>index</structfield> is invalid. Menu items are enumerated
104by calling <constant>VIDIOC_QUERYMENU</constant> with successive
105<structfield>index</structfield> values from &v4l2-queryctrl;
106<structfield>minimum</structfield> to
107<structfield>maximum</structfield>, inclusive. Note that it is possible
108for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some
109indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>.
110In that case that particular menu item is not supported by this driver. Also note that
111the <structfield>minimum</structfield> value is not necessarily 0.</para>
112
113 <para>See also the examples in <xref linkend="control" />.</para>
114
115 <table pgwide="1" frame="none" id="v4l2-queryctrl">
116 <title>struct <structname>v4l2_queryctrl</structname></title>
117 <tgroup cols="3">
118 &cs-str;
119 <tbody valign="top">
120 <row>
121 <entry>__u32</entry>
122 <entry><structfield>id</structfield></entry>
123 <entry>Identifies the control, set by the application. See
124<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
125with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns
126the first control with a higher ID. Drivers which do not support this
127flag yet always return an &EINVAL;.</entry>
128 </row>
129 <row>
130 <entry>&v4l2-ctrl-type;</entry>
131 <entry><structfield>type</structfield></entry>
132 <entry>Type of control, see <xref
133 linkend="v4l2-ctrl-type" />.</entry>
134 </row>
135 <row>
136 <entry>__u8</entry>
137 <entry><structfield>name</structfield>[32]</entry>
138 <entry>Name of the control, a NUL-terminated ASCII
139string. This information is intended for the user.</entry>
140 </row>
141 <row>
142 <entry>__s32</entry>
143 <entry><structfield>minimum</structfield></entry>
144 <entry>Minimum value, inclusive. This field gives a lower
145bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
146lowest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> controls.
147For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value
148gives the minimum length of the string. This length <emphasis>does not include the terminating
149zero</emphasis>. It may not be valid for any other type of control, including
150<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
151signed value.</entry>
152 </row>
153 <row>
154 <entry>__s32</entry>
155 <entry><structfield>maximum</structfield></entry>
156 <entry>Maximum value, inclusive. This field gives an upper
157bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
158highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant>
159controls.
160For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value
161gives the maximum length of the string. This length <emphasis>does not include the terminating
162zero</emphasis>. It may not be valid for any other type of control, including
163<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
164signed value.</entry>
165 </row>
166 <row>
167 <entry>__s32</entry>
168 <entry><structfield>step</structfield></entry>
169 <entry><para>This field gives a step size for
170<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For
171<constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to
172the string length that has to be a multiple of this step size.
173It may not be valid for any other type of control, including
174<constant>V4L2_CTRL_TYPE_INTEGER64</constant>
175controls.</para><para>Generally drivers should not scale hardware
176control values. It may be necessary for example when the
177<structfield>name</structfield> or <structfield>id</structfield> imply
178a particular unit and the hardware actually accepts only multiples of
179said unit. If so, drivers must take care values are properly rounded
180when scaling, such that errors will not accumulate on repeated
181read-write cycles.</para><para>This field gives the smallest change of
182an integer control actually affecting hardware. Often the information
183is needed when the user can change controls by keyboard or GUI
184buttons, rather than a slider. When for example a hardware register
185accepts values 0-511 and the driver reports 0-65535, step should be
186128.</para><para>Note that although signed, the step value is supposed to
187be always positive.</para></entry>
188 </row>
189 <row>
190 <entry>__s32</entry>
191 <entry><structfield>default_value</structfield></entry>
192 <entry>The default value of a
193<constant>V4L2_CTRL_TYPE_INTEGER</constant>,
194<constant>_BOOLEAN</constant> or <constant>_MENU</constant> control.
195Not valid for other types of controls. Drivers reset controls only
196when the driver is loaded, not later, in particular not when the
197func-open; is called.</entry>
198 </row>
199 <row>
200 <entry>__u32</entry>
201 <entry><structfield>flags</structfield></entry>
202 <entry>Control flags, see <xref
203 linkend="control-flags" />.</entry>
204 </row>
205 <row>
206 <entry>__u32</entry>
207 <entry><structfield>reserved</structfield>[2]</entry>
208 <entry>Reserved for future extensions. Drivers must set
209the array to zero.</entry>
210 </row>
211 </tbody>
212 </tgroup>
213 </table>
214
215 <table pgwide="1" frame="none" id="v4l2-querymenu">
216 <title>struct <structname>v4l2_querymenu</structname></title>
217 <tgroup cols="3">
218 &cs-str;
219 <tbody valign="top">
220 <row>
221 <entry>__u32</entry>
222 <entry><structfield>id</structfield></entry>
223 <entry>Identifies the control, set by the application
224from the respective &v4l2-queryctrl;
225<structfield>id</structfield>.</entry>
226 </row>
227 <row>
228 <entry>__u32</entry>
229 <entry><structfield>index</structfield></entry>
230 <entry>Index of the menu item, starting at zero, set by
231 the application.</entry>
232 </row>
233 <row>
234 <entry>__u8</entry>
235 <entry><structfield>name</structfield>[32]</entry>
236 <entry>Name of the menu item, a NUL-terminated ASCII
237string. This information is intended for the user.</entry>
238 </row>
239 <row>
240 <entry>__u32</entry>
241 <entry><structfield>reserved</structfield></entry>
242 <entry>Reserved for future extensions. Drivers must set
243the array to zero.</entry>
244 </row>
245 </tbody>
246 </tgroup>
247 </table>
248
249 <table pgwide="1" frame="none" id="v4l2-ctrl-type">
250 <title>enum v4l2_ctrl_type</title>
251 <tgroup cols="5" align="left">
252 <colspec colwidth="30*" />
253 <colspec colwidth="5*" align="center" />
254 <colspec colwidth="5*" align="center" />
255 <colspec colwidth="5*" align="center" />
256 <colspec colwidth="55*" />
257 <thead>
258 <row>
259 <entry>Type</entry>
260 <entry><structfield>minimum</structfield></entry>
261 <entry><structfield>step</structfield></entry>
262 <entry><structfield>maximum</structfield></entry>
263 <entry>Description</entry>
264 </row>
265 </thead>
266 <tbody valign="top">
267 <row>
268 <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry>
269 <entry>any</entry>
270 <entry>any</entry>
271 <entry>any</entry>
272 <entry>An integer-valued control ranging from minimum to
273maximum inclusive. The step value indicates the increment between
274values which are actually different on the hardware.</entry>
275 </row>
276 <row>
277 <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry>
278 <entry>0</entry>
279 <entry>1</entry>
280 <entry>1</entry>
281 <entry>A boolean-valued control. Zero corresponds to
282"disabled", and one means "enabled".</entry>
283 </row>
284 <row>
285 <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry>
286 <entry>&ge; 0</entry>
287 <entry>1</entry>
288 <entry>N-1</entry>
289 <entry>The control has a menu of N choices. The names of
290the menu items can be enumerated with the
291<constant>VIDIOC_QUERYMENU</constant> ioctl.</entry>
292 </row>
293 <row>
294 <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry>
295 <entry>0</entry>
296 <entry>0</entry>
297 <entry>0</entry>
298 <entry>A control which performs an action when set.
299Drivers must ignore the value passed with
300<constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a
301<constant>VIDIOC_G_CTRL</constant> attempt.</entry>
302 </row>
303 <row>
304 <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry>
305 <entry>n/a</entry>
306 <entry>n/a</entry>
307 <entry>n/a</entry>
308 <entry>A 64-bit integer valued control. Minimum, maximum
309and step size cannot be queried.</entry>
310 </row>
311 <row>
312 <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
313 <entry>&ge; 0</entry>
314 <entry>&ge; 1</entry>
315 <entry>&ge; 0</entry>
316 <entry>The minimum and maximum string lengths. The step size
317means that the string must be (minimum + N * step) characters long for
318N &ge; 0. These lengths do not include the terminating zero, so in order to
319pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the
320<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can
321set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1.
322Which character encoding is used will depend on the string control itself and
323should be part of the control documentation.</entry>
324 </row>
325 <row>
326 <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry>
327 <entry>n/a</entry>
328 <entry>n/a</entry>
329 <entry>n/a</entry>
330 <entry>This is not a control. When
331<constant>VIDIOC_QUERYCTRL</constant> is called with a control ID
332equal to a control class code (see <xref linkend="ctrl-class" />) + 1, the
333ioctl returns the name of the control class and this control type.
334Older drivers which do not support this feature return an
335&EINVAL;.</entry>
336 </row>
337 </tbody>
338 </tgroup>
339 </table>
340
341 <table pgwide="1" frame="none" id="control-flags">
342 <title>Control Flags</title>
343 <tgroup cols="3">
344 &cs-def;
345 <tbody valign="top">
346 <row>
347 <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry>
348 <entry>0x0001</entry>
349 <entry>This control is permanently disabled and should be
350ignored by the application. Any attempt to change the control will
351result in an &EINVAL;.</entry>
352 </row>
353 <row>
354 <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry>
355 <entry>0x0002</entry>
356 <entry>This control is temporarily unchangeable, for
357example because another application took over control of the
358respective resource. Such controls may be displayed specially in a
359user interface. Attempts to change the control may result in an
360&EBUSY;.</entry>
361 </row>
362 <row>
363 <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry>
364 <entry>0x0004</entry>
365 <entry>This control is permanently readable only. Any
366attempt to change the control will result in an &EINVAL;.</entry>
367 </row>
368 <row>
369 <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry>
370 <entry>0x0008</entry>
371 <entry>A hint that changing this control may affect the
372value of other controls within the same control class. Applications
373should update their user interface accordingly.</entry>
374 </row>
375 <row>
376 <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry>
377 <entry>0x0010</entry>
378 <entry>This control is not applicable to the current
379configuration and should be displayed accordingly in a user interface.
380For example the flag may be set on a MPEG audio level 2 bitrate
381control when MPEG audio encoding level 1 was selected with another
382control.</entry>
383 </row>
384 <row>
385 <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry>
386 <entry>0x0020</entry>
387 <entry>A hint that this control is best represented as a
388slider-like element in a user interface.</entry>
389 </row>
390 <row>
391 <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry>
392 <entry>0x0040</entry>
393 <entry>This control is permanently writable only. Any
394attempt to read the control will result in an &EACCES; error code. This
395flag is typically present for relative controls or action controls where
396writing a value will cause the device to carry out a given action
397(&eg; motor control) but no meaningful value can be returned.</entry>
398 </row>
399 </tbody>
400 </tgroup>
401 </table>
402 </refsect1>
403
404 <refsect1>
405 &return-value;
406
407 <variablelist>
408 <varlistentry>
409 <term><errorcode>EINVAL</errorcode></term>
410 <listitem>
411 <para>The &v4l2-queryctrl; <structfield>id</structfield>
412is invalid. The &v4l2-querymenu; <structfield>id</structfield> is
413invalid or <structfield>index</structfield> is out of range (less than
414<structfield>minimum</structfield> or greater than <structfield>maximum</structfield>)
415or this particular menu item is not supported by the driver.</para>
416 </listitem>
417 </varlistentry>
418 <varlistentry>
419 <term><errorcode>EACCES</errorcode></term>
420 <listitem>
421 <para>An attempt was made to read a write-only control.</para>
422 </listitem>
423 </varlistentry>
424 </variablelist>
425 </refsect1>
426</refentry>
427
428<!--
429Local Variables:
430mode: sgml
431sgml-parent-document: "v4l2.sgml"
432indent-tabs-mode: nil
433End:
434-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-querystd.xml b/Documentation/DocBook/media/v4l/vidioc-querystd.xml
new file mode 100644
index 000000000000..1a9e60393091
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-querystd.xml
@@ -0,0 +1,89 @@
1<refentry id="vidioc-querystd">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QUERYSTD</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_QUERYSTD</refname>
9 <refpurpose>Sense the video standard received by the current
10input</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>v4l2_std_id *<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_QUERYSTD</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>The hardware may be able to detect the current video
53standard automatically. To do so, applications call <constant>
54VIDIOC_QUERYSTD</constant> with a pointer to a &v4l2-std-id; type. The
55driver stores here a set of candidates, this can be a single flag or a
56set of supported standards if for example the hardware can only
57distinguish between 50 and 60 Hz systems. When detection is not
58possible or fails, the set must contain all standards supported by the
59current video input or output.</para>
60
61 </refsect1>
62
63 <refsect1>
64 &return-value;
65
66 <variablelist>
67 <varlistentry>
68 <term><errorcode>EINVAL</errorcode></term>
69 <listitem>
70 <para>This ioctl is not supported.</para>
71 </listitem>
72 </varlistentry>
73 <varlistentry>
74 <term><errorcode>EBUSY</errorcode></term>
75 <listitem>
76 <para>The device is busy and therefore can not detect the standard</para>
77 </listitem>
78 </varlistentry>
79 </variablelist>
80 </refsect1>
81</refentry>
82
83<!--
84Local Variables:
85mode: sgml
86sgml-parent-document: "v4l2.sgml"
87indent-tabs-mode: nil
88End:
89-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
new file mode 100644
index 000000000000..69800ae23348
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
@@ -0,0 +1,150 @@
1<refentry id="vidioc-reqbufs">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_REQBUFS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_REQBUFS</refname>
9 <refpurpose>Initiate Memory Mapping or User Pointer I/O</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_requestbuffers *<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>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_REQBUFS</para>
37 </listitem>
38 </varlistentry>
39 <varlistentry>
40 <term><parameter>argp</parameter></term>
41 <listitem>
42 <para></para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47
48 <refsect1>
49 <title>Description</title>
50
51 <para>This ioctl is used to initiate <link linkend="mmap">memory
52mapped</link> or <link linkend="userp">user pointer</link>
53I/O. Memory mapped buffers are located in device memory and must be
54allocated with this ioctl before they can be mapped into the
55application's address space. User buffers are allocated by
56applications themselves, and this ioctl is merely used to switch the
57driver into user pointer I/O mode and to setup some internal structures.</para>
58
59 <para>To allocate device buffers applications initialize all
60fields of the <structname>v4l2_requestbuffers</structname> structure.
61They set the <structfield>type</structfield> field to the respective
62stream or buffer type, the <structfield>count</structfield> field to
63the desired number of buffers, <structfield>memory</structfield>
64must be set to the requested I/O method and the <structfield>reserved</structfield> array
65must be zeroed. When the ioctl
66is called with a pointer to this structure the driver will attempt to allocate
67the requested number of buffers and it stores the actual number
68allocated in the <structfield>count</structfield> field. It can be
69smaller than the number requested, even zero, when the driver runs out
70of free memory. A larger number is also possible when the driver requires
71more buffers to function correctly. For example video output requires at least two buffers,
72one displayed and one filled by the application.</para>
73 <para>When the I/O method is not supported the ioctl
74returns an &EINVAL;.</para>
75
76 <para>Applications can call <constant>VIDIOC_REQBUFS</constant>
77again to change the number of buffers, however this cannot succeed
78when any buffers are still mapped. A <structfield>count</structfield>
79value of zero frees all buffers, after aborting or finishing any DMA
80in progress, an implicit &VIDIOC-STREAMOFF;. <!-- mhs: I see no
81reason why munmap()ping one or even all buffers must imply
82streamoff.--></para>
83
84 <table pgwide="1" frame="none" id="v4l2-requestbuffers">
85 <title>struct <structname>v4l2_requestbuffers</structname></title>
86 <tgroup cols="3">
87 &cs-str;
88 <tbody valign="top">
89 <row>
90 <entry>__u32</entry>
91 <entry><structfield>count</structfield></entry>
92 <entry>The number of buffers requested or granted.</entry>
93 </row>
94 <row>
95 <entry>&v4l2-buf-type;</entry>
96 <entry><structfield>type</structfield></entry>
97 <entry>Type of the stream or buffers, this is the same
98as the &v4l2-format; <structfield>type</structfield> field. See <xref
99 linkend="v4l2-buf-type" /> for valid values.</entry>
100 </row>
101 <row>
102 <entry>&v4l2-memory;</entry>
103 <entry><structfield>memory</structfield></entry>
104 <entry>Applications set this field to
105<constant>V4L2_MEMORY_MMAP</constant> or
106<constant>V4L2_MEMORY_USERPTR</constant>.</entry>
107 </row>
108 <row>
109 <entry>__u32</entry>
110 <entry><structfield>reserved</structfield>[2]</entry>
111 <entry>A place holder for future extensions and custom
112(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and
113higher. This array should be zeroed by applications.</entry>
114 </row>
115 </tbody>
116 </tgroup>
117 </table>
118 </refsect1>
119
120 <refsect1>
121 &return-value;
122
123 <variablelist>
124 <varlistentry>
125 <term><errorcode>EBUSY</errorcode></term>
126 <listitem>
127 <para>The driver supports multiple opens and I/O is already
128in progress, or reallocation of buffers was attempted although one or
129more are still mapped.</para>
130 </listitem>
131 </varlistentry>
132 <varlistentry>
133 <term><errorcode>EINVAL</errorcode></term>
134 <listitem>
135 <para>The buffer type (<structfield>type</structfield> field) or the
136requested I/O method (<structfield>memory</structfield>) is not
137supported.</para>
138 </listitem>
139 </varlistentry>
140 </variablelist>
141 </refsect1>
142</refentry>
143
144<!--
145Local Variables:
146mode: sgml
147sgml-parent-document: "v4l2.sgml"
148indent-tabs-mode: nil
149End:
150-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml
new file mode 100644
index 000000000000..c30dcc4232c0
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml
@@ -0,0 +1,135 @@
1<refentry id="vidioc-s-hw-freq-seek">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_S_HW_FREQ_SEEK</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_S_HW_FREQ_SEEK</refname>
9 <refpurpose>Perform a hardware frequency seek</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_hw_freq_seek
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_S_HW_FREQ_SEEK</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>Start a hardware frequency seek from the current frequency.
53To do this applications initialize the <structfield>tuner</structfield>,
54<structfield>type</structfield>, <structfield>seek_upward</structfield>,
55<structfield>spacing</structfield> and
56<structfield>wrap_around</structfield> fields, and zero out the
57<structfield>reserved</structfield> array of a &v4l2-hw-freq-seek; and
58call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl with a pointer
59to this structure.</para>
60
61 <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para>
62
63 <table pgwide="1" frame="none" id="v4l2-hw-freq-seek">
64 <title>struct <structname>v4l2_hw_freq_seek</structname></title>
65 <tgroup cols="3">
66 &cs-str;
67 <tbody valign="top">
68 <row>
69 <entry>__u32</entry>
70 <entry><structfield>tuner</structfield></entry>
71 <entry>The tuner index number. This is the
72same value as in the &v4l2-input; <structfield>tuner</structfield>
73field and the &v4l2-tuner; <structfield>index</structfield> field.</entry>
74 </row>
75 <row>
76 <entry>&v4l2-tuner-type;</entry>
77 <entry><structfield>type</structfield></entry>
78 <entry>The tuner type. This is the same value as in the
79&v4l2-tuner; <structfield>type</structfield> field.</entry>
80 </row>
81 <row>
82 <entry>__u32</entry>
83 <entry><structfield>seek_upward</structfield></entry>
84 <entry>If non-zero, seek upward from the current frequency, else seek downward.</entry>
85 </row>
86 <row>
87 <entry>__u32</entry>
88 <entry><structfield>wrap_around</structfield></entry>
89 <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking.</entry>
90 </row>
91 <row>
92 <entry>__u32</entry>
93 <entry><structfield>spacing</structfield></entry>
94 <entry>If non-zero, defines the hardware seek resolution in Hz. The driver selects the nearest value that is supported by the device. If spacing is zero a reasonable default value is used.</entry>
95 </row>
96 <row>
97 <entry>__u32</entry>
98 <entry><structfield>reserved</structfield>[7]</entry>
99 <entry>Reserved for future extensions. Drivers and
100 applications must set the array to zero.</entry>
101 </row>
102 </tbody>
103 </tgroup>
104 </table>
105 </refsect1>
106
107 <refsect1>
108 &return-value;
109
110 <variablelist>
111 <varlistentry>
112 <term><errorcode>EINVAL</errorcode></term>
113 <listitem>
114 <para>The <structfield>tuner</structfield> index is out of
115bounds or the value in the <structfield>type</structfield> field is
116wrong.</para>
117 </listitem>
118 </varlistentry>
119 <varlistentry>
120 <term><errorcode>EAGAIN</errorcode></term>
121 <listitem>
122 <para>The ioctl timed-out. Try again.</para>
123 </listitem>
124 </varlistentry>
125 </variablelist>
126 </refsect1>
127</refentry>
128
129<!--
130Local Variables:
131mode: sgml
132sgml-parent-document: "v4l2.sgml"
133indent-tabs-mode: nil
134End:
135-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-streamon.xml b/Documentation/DocBook/media/v4l/vidioc-streamon.xml
new file mode 100644
index 000000000000..75ed39bf4d2b
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-streamon.xml
@@ -0,0 +1,115 @@
1<refentry id="vidioc-streamon">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_STREAMON</refname>
9 <refname>VIDIOC_STREAMOFF</refname>
10 <refpurpose>Start or stop streaming I/O</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>const int *<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_STREAMON, VIDIOC_STREAMOFF</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>The <constant>VIDIOC_STREAMON</constant> and
53<constant>VIDIOC_STREAMOFF</constant> ioctl start and stop the capture
54or output process during streaming (<link linkend="mmap">memory
55mapping</link> or <link linkend="userp">user pointer</link>) I/O.</para>
56
57 <para>Specifically the capture hardware is disabled and no input
58buffers are filled (if there are any empty buffers in the incoming
59queue) until <constant>VIDIOC_STREAMON</constant> has been called.
60Accordingly the output hardware is disabled, no video signal is
61produced until <constant>VIDIOC_STREAMON</constant> has been called.
62The ioctl will succeed only when at least one output buffer is in the
63incoming queue.</para>
64
65 <para>The <constant>VIDIOC_STREAMOFF</constant> ioctl, apart of
66aborting or finishing any DMA in progress, unlocks any user pointer
67buffers locked in physical memory, and it removes all buffers from the
68incoming and outgoing queues. That means all images captured but not
69dequeued yet will be lost, likewise all images enqueued for output but
70not transmitted yet. I/O returns to the same state as after calling
71&VIDIOC-REQBUFS; and can be restarted accordingly.</para>
72
73 <para>Both ioctls take a pointer to an integer, the desired buffer or
74stream type. This is the same as &v4l2-requestbuffers;
75<structfield>type</structfield>.</para>
76
77 <para>Note applications can be preempted for unknown periods right
78before or after the <constant>VIDIOC_STREAMON</constant> or
79<constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of
80starting or stopping "now". Buffer timestamps can be used to
81synchronize with other events.</para>
82 </refsect1>
83
84 <refsect1>
85 &return-value;
86
87 <variablelist>
88 <varlistentry>
89 <term><errorcode>EINVAL</errorcode></term>
90 <listitem>
91 <para>Streaming I/O is not supported, the buffer
92<structfield>type</structfield> is not supported, or no buffers have
93been allocated (memory mapping) or enqueued (output) yet.</para>
94 </listitem>
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>
105 </variablelist>
106 </refsect1>
107</refentry>
108
109<!--
110Local Variables:
111mode: sgml
112sgml-parent-document: "v4l2.sgml"
113indent-tabs-mode: nil
114End:
115-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-interval.xml
new file mode 100644
index 000000000000..2f8f4f0a0235
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/vidioc-subdev-enum-frame-size.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-frame-size.xml
new file mode 100644
index 000000000000..79ce42b7c60c
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/vidioc-subdev-enum-mbus-code.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-enum-mbus-code.xml
new file mode 100644
index 000000000000..a6b3432449f6
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/vidioc-subdev-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-crop.xml
new file mode 100644
index 000000000000..06197323a8cc
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/vidioc-subdev-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-fmt.xml
new file mode 100644
index 000000000000..f367c570c530
--- /dev/null
+++ b/Documentation/DocBook/media/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/media/v4l/vidioc-subdev-g-frame-interval.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-frame-interval.xml
new file mode 100644
index 000000000000..0bc3ea22d31f
--- /dev/null
+++ b/Documentation/DocBook/media/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/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
new file mode 100644
index 000000000000..8b501791aa68
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
@@ -0,0 +1,133 @@
1<refentry id="vidioc-subscribe-event">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</refname>
9 <refpurpose>Subscribe or unsubscribe event</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_event_subscription
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_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT</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>Subscribe or unsubscribe V4L2 event. Subscribed events are
53 dequeued by using the &VIDIOC-DQEVENT; ioctl.</para>
54
55 <table frame="none" pgwide="1" id="v4l2-event-subscription">
56 <title>struct <structname>v4l2_event_subscription</structname></title>
57 <tgroup cols="3">
58 &cs-str;
59 <tbody valign="top">
60 <row>
61 <entry>__u32</entry>
62 <entry><structfield>type</structfield></entry>
63 <entry>Type of the event.</entry>
64 </row>
65 <row>
66 <entry>__u32</entry>
67 <entry><structfield>reserved</structfield>[7]</entry>
68 <entry>Reserved for future extensions. Drivers and applications
69 must set the array to zero.</entry>
70 </row>
71 </tbody>
72 </tgroup>
73 </table>
74
75 <table frame="none" pgwide="1" id="event-type">
76 <title>Event Types</title>
77 <tgroup cols="3">
78 &cs-def;
79 <tbody valign="top">
80 <row>
81 <entry><constant>V4L2_EVENT_ALL</constant></entry>
82 <entry>0</entry>
83 <entry>All events. V4L2_EVENT_ALL is valid only for
84 VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once.
85 </entry>
86 </row>
87 <row>
88 <entry><constant>V4L2_EVENT_VSYNC</constant></entry>
89 <entry>1</entry>
90 <entry>This event is triggered on the vertical sync.
91 This event has &v4l2-event-vsync; associated with it.
92 </entry>
93 </row>
94 <row>
95 <entry><constant>V4L2_EVENT_EOS</constant></entry>
96 <entry>2</entry>
97 <entry>This event is triggered when the end of a stream is reached.
98 This is typically used with MPEG decoders to report to the application
99 when the last of the MPEG stream has been decoded.
100 </entry>
101 </row>
102 <row>
103 <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
104 <entry>0x08000000</entry>
105 <entry>Base event number for driver-private events.</entry>
106 </row>
107 </tbody>
108 </tgroup>
109 </table>
110
111 <table frame="none" pgwide="1" id="v4l2-event-vsync">
112 <title>struct <structname>v4l2_event_vsync</structname></title>
113 <tgroup cols="3">
114 &cs-str;
115 <tbody valign="top">
116 <row>
117 <entry>__u8</entry>
118 <entry><structfield>field</structfield></entry>
119 <entry>The upcoming field. See &v4l2-field;.</entry>
120 </row>
121 </tbody>
122 </tgroup>
123 </table>
124
125 </refsect1>
126</refentry>
127<!--
128Local Variables:
129mode: sgml
130sgml-parent-document: "v4l2.sgml"
131indent-tabs-mode: nil
132End:
133-->