aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/v4l
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/v4l')
-rw-r--r--Documentation/DocBook/v4l/biblio.xml188
-rw-r--r--Documentation/DocBook/v4l/capture.c.xml659
-rw-r--r--Documentation/DocBook/v4l/common.xml1169
-rw-r--r--Documentation/DocBook/v4l/compat.xml2457
-rw-r--r--Documentation/DocBook/v4l/controls.xml2049
-rw-r--r--Documentation/DocBook/v4l/crop.gifbin0 -> 5967 bytes
-rw-r--r--Documentation/DocBook/v4l/crop.pdfbin0 -> 5846 bytes
-rw-r--r--Documentation/DocBook/v4l/dev-capture.xml115
-rw-r--r--Documentation/DocBook/v4l/dev-codec.xml26
-rw-r--r--Documentation/DocBook/v4l/dev-effect.xml25
-rw-r--r--Documentation/DocBook/v4l/dev-osd.xml164
-rw-r--r--Documentation/DocBook/v4l/dev-output.xml111
-rw-r--r--Documentation/DocBook/v4l/dev-overlay.xml379
-rw-r--r--Documentation/DocBook/v4l/dev-radio.xml57
-rw-r--r--Documentation/DocBook/v4l/dev-raw-vbi.xml347
-rw-r--r--Documentation/DocBook/v4l/dev-rds.xml168
-rw-r--r--Documentation/DocBook/v4l/dev-sliced-vbi.xml708
-rw-r--r--Documentation/DocBook/v4l/dev-teletext.xml40
-rw-r--r--Documentation/DocBook/v4l/driver.xml208
-rw-r--r--Documentation/DocBook/v4l/fdl-appendix.xml671
-rw-r--r--Documentation/DocBook/v4l/fieldseq_bt.gifbin0 -> 25430 bytes
-rw-r--r--Documentation/DocBook/v4l/fieldseq_bt.pdfbin0 -> 9185 bytes
-rw-r--r--Documentation/DocBook/v4l/fieldseq_tb.gifbin0 -> 25323 bytes
-rw-r--r--Documentation/DocBook/v4l/fieldseq_tb.pdfbin0 -> 9173 bytes
-rw-r--r--Documentation/DocBook/v4l/func-close.xml70
-rw-r--r--Documentation/DocBook/v4l/func-ioctl.xml146
-rw-r--r--Documentation/DocBook/v4l/func-mmap.xml185
-rw-r--r--Documentation/DocBook/v4l/func-munmap.xml83
-rw-r--r--Documentation/DocBook/v4l/func-open.xml121
-rw-r--r--Documentation/DocBook/v4l/func-poll.xml127
-rw-r--r--Documentation/DocBook/v4l/func-read.xml189
-rw-r--r--Documentation/DocBook/v4l/func-select.xml138
-rw-r--r--Documentation/DocBook/v4l/func-write.xml136
-rw-r--r--Documentation/DocBook/v4l/io.xml1073
-rw-r--r--Documentation/DocBook/v4l/keytable.c.xml172
-rw-r--r--Documentation/DocBook/v4l/libv4l.xml167
-rw-r--r--Documentation/DocBook/v4l/pixfmt-grey.xml70
-rw-r--r--Documentation/DocBook/v4l/pixfmt-nv12.xml151
-rw-r--r--Documentation/DocBook/v4l/pixfmt-nv16.xml174
-rw-r--r--Documentation/DocBook/v4l/pixfmt-packed-rgb.xml862
-rw-r--r--Documentation/DocBook/v4l/pixfmt-packed-yuv.xml244
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sbggr16.xml91
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sbggr8.xml75
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sgbrg8.xml75
-rw-r--r--Documentation/DocBook/v4l/pixfmt-sgrbg8.xml75
-rw-r--r--Documentation/DocBook/v4l/pixfmt-uyvy.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt-vyuy.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt-y16.xml89
-rw-r--r--Documentation/DocBook/v4l/pixfmt-y41p.xml157
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv410.xml141
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv411p.xml155
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv420.xml157
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuv422p.xml161
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yuyv.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt-yvyu.xml128
-rw-r--r--Documentation/DocBook/v4l/pixfmt.xml796
-rw-r--r--Documentation/DocBook/v4l/remote_controllers.xml170
-rw-r--r--Documentation/DocBook/v4l/v4l2.xml481
-rw-r--r--Documentation/DocBook/v4l/v4l2grab.c.xml164
-rw-r--r--Documentation/DocBook/v4l/vbi_525.gifbin0 -> 4741 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_525.pdfbin0 -> 3395 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_625.gifbin0 -> 5095 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_625.pdfbin0 -> 3683 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_hsync.gifbin0 -> 2400 bytes
-rw-r--r--Documentation/DocBook/v4l/vbi_hsync.pdfbin0 -> 7405 bytes
-rw-r--r--Documentation/DocBook/v4l/videodev2.h.xml1639
-rw-r--r--Documentation/DocBook/v4l/vidioc-cropcap.xml174
-rw-r--r--Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml275
-rw-r--r--Documentation/DocBook/v4l/vidioc-dbg-g-register.xml275
-rw-r--r--Documentation/DocBook/v4l/vidioc-encoder-cmd.xml204
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-fmt.xml164
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml270
-rw-r--r--Documentation/DocBook/v4l/vidioc-enum-framesizes.xml282
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumaudio.xml86
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumaudioout.xml89
-rw-r--r--Documentation/DocBook/v4l/vidioc-enuminput.xml287
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumoutput.xml172
-rw-r--r--Documentation/DocBook/v4l/vidioc-enumstd.xml391
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-audio.xml188
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-audioout.xml154
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-crop.xml143
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-ctrl.xml130
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-enc-index.xml213
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml307
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-fbuf.xml456
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-fmt.xml201
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-frequency.xml145
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-input.xml100
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml180
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-modulator.xml246
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-output.xml100
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-parm.xml332
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-priority.xml144
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml264
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-std.xml99
-rw-r--r--Documentation/DocBook/v4l/vidioc-g-tuner.xml535
-rw-r--r--Documentation/DocBook/v4l/vidioc-log-status.xml58
-rw-r--r--Documentation/DocBook/v4l/vidioc-overlay.xml83
-rw-r--r--Documentation/DocBook/v4l/vidioc-qbuf.xml168
-rw-r--r--Documentation/DocBook/v4l/vidioc-querybuf.xml103
-rw-r--r--Documentation/DocBook/v4l/vidioc-querycap.xml284
-rw-r--r--Documentation/DocBook/v4l/vidioc-queryctrl.xml428
-rw-r--r--Documentation/DocBook/v4l/vidioc-querystd.xml83
-rw-r--r--Documentation/DocBook/v4l/vidioc-reqbufs.xml160
-rw-r--r--Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml129
-rw-r--r--Documentation/DocBook/v4l/vidioc-streamon.xml106
106 files changed, 26795 insertions, 0 deletions
diff --git a/Documentation/DocBook/v4l/biblio.xml b/Documentation/DocBook/v4l/biblio.xml
new file mode 100644
index 000000000000..afc8a0dd2601
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/capture.c.xml b/Documentation/DocBook/v4l/capture.c.xml
new file mode 100644
index 000000000000..acf46b6dac23
--- /dev/null
+++ b/Documentation/DocBook/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 were got from V4L2 API, Draft 0.20
8 * available at: http://v4l2spec.bytesex.org/
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/v4l/common.xml b/Documentation/DocBook/v4l/common.xml
new file mode 100644
index 000000000000..dd598ac9a450
--- /dev/null
+++ b/Documentation/DocBook/v4l/common.xml
@@ -0,0 +1,1169 @@
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 recomended 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
510 <section>
511 <title>Satellite Receivers</title>
512
513 <para>To be discussed. See also <!-- private discussions of
514Peter Schlaf, BD & MHS on 23 Jun 1999 ff., subject "v4l2 and satellit" and -->
515proposals by Peter Schlaf, video4linux-list@redhat.com on 23 Oct 2002,
516subject: "Re: [V4L] Re: v4l2 api".</para>
517 </section>
518 </section>
519
520 <section id="standard">
521 <title>Video Standards</title>
522
523 <para>Video devices typically support one or more different video
524standards or variations of standards. Each video input and output may
525support another set of standards. This set is reported by the
526<structfield>std</structfield> field of &v4l2-input; and
527&v4l2-output; returned by the &VIDIOC-ENUMINPUT; and
528&VIDIOC-ENUMOUTPUT; ioctl, respectively.</para>
529
530 <para>V4L2 defines one bit for each analog video standard
531currently in use worldwide, and sets aside bits for driver defined
532standards, &eg; hybrid standards to watch NTSC video tapes on PAL TVs
533and vice versa. Applications can use the predefined bits to select a
534particular standard, although presenting the user a menu of supported
535standards is preferred. To enumerate and query the attributes of the
536supported standards applications use the &VIDIOC-ENUMSTD; ioctl.</para>
537
538 <para>Many of the defined standards are actually just variations
539of a few major standards. The hardware may in fact not distinguish
540between them, or do so internal and switch automatically. Therefore
541enumerated standards also contain sets of one or more standard
542bits.</para>
543
544 <para>Assume a hypothetic tuner capable of demodulating B/PAL,
545G/PAL and I/PAL signals. The first enumerated standard is a set of B
546and G/PAL, switched automatically depending on the selected radio
547frequency in UHF or VHF band. Enumeration gives a "PAL-B/G" or "PAL-I"
548choice. Similar a Composite input may collapse standards, enumerating
549"PAL-B/G/H/I", "NTSC-M" and "SECAM-D/K".<footnote>
550 <para>Some users are already confused by technical terms PAL,
551NTSC and SECAM. There is no point asking them to distinguish between
552B, G, D, or K when the software or hardware can do that
553automatically.</para>
554 </footnote></para>
555
556 <para>To query and select the standard used by the current video
557input or output applications call the &VIDIOC-G-STD; and
558&VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis>
559standard 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>
560 <para>An alternative to the current scheme is to use pointers
561to indices as arguments of <constant>VIDIOC_G_STD</constant> and
562<constant>VIDIOC_S_STD</constant>, the &v4l2-input; and
563&v4l2-output; <structfield>std</structfield> field would be a set of
564indices like <structfield>audioset</structfield>.</para>
565 <para>Indices are consistent with the rest of the API
566and identify the standard unambiguously. In the present scheme of
567things an enumerated standard is looked up by &v4l2-std-id;. Now the
568standards supported by the inputs of a device can overlap. Just
569assume the tuner and composite input in the example above both
570exist on a device. An enumeration of "PAL-B/G", "PAL-H/I" suggests
571a choice which does not exist. We cannot merge or omit sets, because
572applications would be unable to find the standards reported by
573<constant>VIDIOC_G_STD</constant>. That leaves separate enumerations
574for each input. Also selecting a standard by &v4l2-std-id; can be
575ambiguous. Advantage of this method is that applications need not
576identify the standard indirectly, after enumerating.</para><para>So in
577summary, the lookup itself is unavoidable. The difference is only
578whether the lookup is necessary to find an enumerated standard or to
579switch to a standard by &v4l2-std-id;.</para>
580 </footnote> Drivers must implement all video standard ioctls
581when the device has one or more video inputs or outputs.</para>
582
583 <para>Special rules apply to USB cameras where the notion of video
584standards makes little sense. More generally any capture device,
585output devices accordingly, which is <itemizedlist>
586 <listitem>
587 <para>incapable of capturing fields or frames at the nominal
588rate of the video standard, or</para>
589 </listitem>
590 <listitem>
591 <para>where <link linkend="buffer">timestamps</link> refer
592to the instant the field or frame was received by the driver, not the
593capture time, or</para>
594 </listitem>
595 <listitem>
596 <para>where <link linkend="buffer">sequence numbers</link>
597refer to the frames received by the driver, not the captured
598frames.</para>
599 </listitem>
600 </itemizedlist> Here the driver shall set the
601<structfield>std</structfield> field of &v4l2-input; and &v4l2-output;
602to zero, the <constant>VIDIOC_G_STD</constant>,
603<constant>VIDIOC_S_STD</constant>,
604<constant>VIDIOC_QUERYSTD</constant> and
605<constant>VIDIOC_ENUMSTD</constant> ioctls shall return the
606&EINVAL;.<footnote>
607 <para>See <xref linkend="buffer" /> for a rationale. Probably
608even USB cameras follow some well known video standard. It might have
609been better to explicitly indicate elsewhere if a device cannot live
610up to normal expectations, instead of this exception.</para>
611 </footnote></para>
612
613 <example>
614 <title>Information about the current video standard</title>
615
616 <programlisting>
617&v4l2-std-id; std_id;
618&v4l2-standard; standard;
619
620if (-1 == ioctl (fd, &VIDIOC-G-STD;, &amp;std_id)) {
621 /* Note when VIDIOC_ENUMSTD always returns EINVAL this
622 is no video device or it falls under the USB exception,
623 and VIDIOC_G_STD returning EINVAL is no error. */
624
625 perror ("VIDIOC_G_STD");
626 exit (EXIT_FAILURE);
627}
628
629memset (&amp;standard, 0, sizeof (standard));
630standard.index = 0;
631
632while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
633 if (standard.id &amp; std_id) {
634 printf ("Current video standard: %s\n", standard.name);
635 exit (EXIT_SUCCESS);
636 }
637
638 standard.index++;
639}
640
641/* EINVAL indicates the end of the enumeration, which cannot be
642 empty unless this device falls under the USB exception. */
643
644if (errno == EINVAL || standard.index == 0) {
645 perror ("VIDIOC_ENUMSTD");
646 exit (EXIT_FAILURE);
647}
648 </programlisting>
649 </example>
650
651 <example>
652 <title>Listing the video standards supported by the current
653input</title>
654
655 <programlisting>
656&v4l2-input; input;
657&v4l2-standard; standard;
658
659memset (&amp;input, 0, sizeof (input));
660
661if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
662 perror ("VIDIOC_G_INPUT");
663 exit (EXIT_FAILURE);
664}
665
666if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
667 perror ("VIDIOC_ENUM_INPUT");
668 exit (EXIT_FAILURE);
669}
670
671printf ("Current input %s supports:\n", input.name);
672
673memset (&amp;standard, 0, sizeof (standard));
674standard.index = 0;
675
676while (0 == ioctl (fd, &VIDIOC-ENUMSTD;, &amp;standard)) {
677 if (standard.id &amp; input.std)
678 printf ("%s\n", standard.name);
679
680 standard.index++;
681}
682
683/* EINVAL indicates the end of the enumeration, which cannot be
684 empty unless this device falls under the USB exception. */
685
686if (errno != EINVAL || standard.index == 0) {
687 perror ("VIDIOC_ENUMSTD");
688 exit (EXIT_FAILURE);
689}
690 </programlisting>
691 </example>
692
693 <example>
694 <title>Selecting a new video standard</title>
695
696 <programlisting>
697&v4l2-input; input;
698&v4l2-std-id; std_id;
699
700memset (&amp;input, 0, sizeof (input));
701
702if (-1 == ioctl (fd, &VIDIOC-G-INPUT;, &amp;input.index)) {
703 perror ("VIDIOC_G_INPUT");
704 exit (EXIT_FAILURE);
705}
706
707if (-1 == ioctl (fd, &VIDIOC-ENUMINPUT;, &amp;input)) {
708 perror ("VIDIOC_ENUM_INPUT");
709 exit (EXIT_FAILURE);
710}
711
712if (0 == (input.std &amp; V4L2_STD_PAL_BG)) {
713 fprintf (stderr, "Oops. B/G PAL is not supported.\n");
714 exit (EXIT_FAILURE);
715}
716
717/* Note this is also supposed to work when only B
718 <emphasis>or</emphasis> G/PAL is supported. */
719
720std_id = V4L2_STD_PAL_BG;
721
722if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
723 perror ("VIDIOC_S_STD");
724 exit (EXIT_FAILURE);
725}
726 </programlisting>
727 </example>
728 </section>
729
730 &sub-controls;
731
732 <section id="format">
733 <title>Data Formats</title>
734
735 <section>
736 <title>Data Format Negotiation</title>
737
738 <para>Different devices exchange different kinds of data with
739applications, for example video images, raw or sliced VBI data, RDS
740datagrams. Even within one kind many different formats are possible,
741in particular an abundance of image formats. Although drivers must
742provide a default and the selection persists across closing and
743reopening a device, applications should always negotiate a data format
744before engaging in data exchange. Negotiation means the application
745asks for a particular format and the driver selects and reports the
746best the hardware can do to satisfy the request. Of course
747applications can also just query the current selection.</para>
748
749 <para>A single mechanism exists to negotiate all data formats
750using the aggregate &v4l2-format; and the &VIDIOC-G-FMT; and
751&VIDIOC-S-FMT; ioctls. Additionally the &VIDIOC-TRY-FMT; ioctl can be
752used to examine what the hardware <emphasis>could</emphasis> do,
753without actually selecting a new data format. The data formats
754supported by the V4L2 API are covered in the respective device section
755in <xref linkend="devices" />. For a closer look at image formats see
756<xref linkend="pixfmt" />.</para>
757
758 <para>The <constant>VIDIOC_S_FMT</constant> ioctl is a major
759turning-point in the initialization sequence. Prior to this point
760multiple panel applications can access the same device concurrently to
761select the current input, change controls or modify other properties.
762The first <constant>VIDIOC_S_FMT</constant> assigns a logical stream
763(video data, VBI data etc.) exclusively to one file descriptor.</para>
764
765 <para>Exclusive means no other application, more precisely no
766other file descriptor, can grab this stream or change device
767properties inconsistent with the negotiated parameters. A video
768standard change for example, when the new standard uses a different
769number of scan lines, can invalidate the selected image format.
770Therefore only the file descriptor owning the stream can make
771invalidating changes. Accordingly multiple file descriptors which
772grabbed different logical streams prevent each other from interfering
773with their settings. When for example video overlay is about to start
774or already in progress, simultaneous video capturing may be restricted
775to the same cropping and image size.</para>
776
777 <para>When applications omit the
778<constant>VIDIOC_S_FMT</constant> ioctl its locking side effects are
779implied by the next step, the selection of an I/O method with the
780&VIDIOC-REQBUFS; ioctl or implicit with the first &func-read; or
781&func-write; call.</para>
782
783 <para>Generally only one logical stream can be assigned to a
784file descriptor, the exception being drivers permitting simultaneous
785video capturing and overlay using the same file descriptor for
786compatibility with V4L and earlier versions of V4L2. Switching the
787logical stream or returning into "panel mode" is possible by closing
788and reopening the device. Drivers <emphasis>may</emphasis> support a
789switch using <constant>VIDIOC_S_FMT</constant>.</para>
790
791 <para>All drivers exchanging data with
792applications must support the <constant>VIDIOC_G_FMT</constant> and
793<constant>VIDIOC_S_FMT</constant> ioctl. Implementation of the
794<constant>VIDIOC_TRY_FMT</constant> is highly recommended but
795optional.</para>
796 </section>
797
798 <section>
799 <title>Image Format Enumeration</title>
800
801 <para>Apart of the generic format negotiation functions
802a special ioctl to enumerate all image formats supported by video
803capture, overlay or output devices is available.<footnote>
804 <para>Enumerating formats an application has no a-priori
805knowledge of (otherwise it could explicitely ask for them and need not
806enumerate) seems useless, but there are applications serving as proxy
807between drivers and the actual video applications for which this is
808useful.</para>
809 </footnote></para>
810
811 <para>The &VIDIOC-ENUM-FMT; ioctl must be supported
812by all drivers exchanging image data with applications.</para>
813
814 <important>
815 <para>Drivers are not supposed to convert image formats in
816kernel space. They must enumerate only formats directly supported by
817the hardware. If necessary driver writers should publish an example
818conversion routine or library for integration into applications.</para>
819 </important>
820 </section>
821 </section>
822
823 <section id="crop">
824 <title>Image Cropping, Insertion and Scaling</title>
825
826 <para>Some video capture devices can sample a subsection of the
827picture and shrink or enlarge it to an image of arbitrary size. We
828call these abilities cropping and scaling. Some video output devices
829can scale an image up or down and insert it at an arbitrary scan line
830and horizontal offset into a video signal.</para>
831
832 <para>Applications can use the following API to select an area in
833the video signal, query the default area and the hardware limits.
834<emphasis>Despite their name, the &VIDIOC-CROPCAP;, &VIDIOC-G-CROP;
835and &VIDIOC-S-CROP; ioctls apply to input as well as output
836devices.</emphasis></para>
837
838 <para>Scaling requires a source and a target. On a video capture
839or overlay device the source is the video signal, and the cropping
840ioctls determine the area actually sampled. The target are images
841read by the application or overlaid onto the graphics screen. Their
842size (and position for an overlay) is negotiated with the
843&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls.</para>
844
845 <para>On a video output device the source are the images passed in
846by the application, and their size is again negotiated with the
847<constant>VIDIOC_G/S_FMT</constant> ioctls, or may be encoded in a
848compressed video stream. The target is the video signal, and the
849cropping ioctls determine the area where the images are
850inserted.</para>
851
852 <para>Source and target rectangles are defined even if the device
853does not support scaling or the <constant>VIDIOC_G/S_CROP</constant>
854ioctls. Their size (and position where applicable) will be fixed in
855this case. <emphasis>All capture and output device must support the
856<constant>VIDIOC_CROPCAP</constant> ioctl such that applications can
857determine if scaling takes place.</emphasis></para>
858
859 <section>
860 <title>Cropping Structures</title>
861
862 <figure id="crop-scale">
863 <title>Image Cropping, Insertion and Scaling</title>
864 <mediaobject>
865 <imageobject>
866 <imagedata fileref="crop.pdf" format="PS" />
867 </imageobject>
868 <imageobject>
869 <imagedata fileref="crop.gif" format="GIF" />
870 </imageobject>
871 <textobject>
872 <phrase>The cropping, insertion and scaling process</phrase>
873 </textobject>
874 </mediaobject>
875 </figure>
876
877 <para>For capture devices the coordinates of the top left
878corner, width and height of the area which can be sampled is given by
879the <structfield>bounds</structfield> substructure of the
880&v4l2-cropcap; returned by the <constant>VIDIOC_CROPCAP</constant>
881ioctl. To support a wide range of hardware this specification does not
882define an origin or units. However by convention drivers should
883horizontally count unscaled samples relative to 0H (the leading edge
884of the horizontal sync pulse, see <xref linkend="vbi-hsync" />).
885Vertically ITU-R line
886numbers of the first field (<xref linkend="vbi-525" />, <xref
887linkend="vbi-625" />), multiplied by two if the driver can capture both
888fields.</para>
889
890 <para>The top left corner, width and height of the source
891rectangle, that is the area actually sampled, is given by &v4l2-crop;
892using the same coordinate system as &v4l2-cropcap;. Applications can
893use the <constant>VIDIOC_G_CROP</constant> and
894<constant>VIDIOC_S_CROP</constant> ioctls to get and set this
895rectangle. It must lie completely within the capture boundaries and
896the driver may further adjust the requested size and/or position
897according to hardware limitations.</para>
898
899 <para>Each capture device has a default source rectangle, given
900by the <structfield>defrect</structfield> substructure of
901&v4l2-cropcap;. The center of this rectangle shall align with the
902center of the active picture area of the video signal, and cover what
903the driver writer considers the complete picture. Drivers shall reset
904the source rectangle to the default when the driver is first loaded,
905but not later.</para>
906
907 <para>For output devices these structures and ioctls are used
908accordingly, defining the <emphasis>target</emphasis> rectangle where
909the images will be inserted into the video signal.</para>
910
911 </section>
912
913 <section>
914 <title>Scaling Adjustments</title>
915
916 <para>Video hardware can have various cropping, insertion and
917scaling limitations. It may only scale up or down, support only
918discrete scaling factors, or have different scaling abilities in
919horizontal and vertical direction. Also it may not support scaling at
920all. At the same time the &v4l2-crop; rectangle may have to be
921aligned, and both the source and target rectangles may have arbitrary
922upper and lower size limits. In particular the maximum
923<structfield>width</structfield> and <structfield>height</structfield>
924in &v4l2-crop; may be smaller than the
925&v4l2-cropcap;.<structfield>bounds</structfield> area. Therefore, as
926usual, drivers are expected to adjust the requested parameters and
927return the actual values selected.</para>
928
929 <para>Applications can change the source or the target rectangle
930first, as they may prefer a particular image size or a certain area in
931the video signal. If the driver has to adjust both to satisfy hardware
932limitations, the last requested rectangle shall take priority, and the
933driver should preferably adjust the opposite one. The &VIDIOC-TRY-FMT;
934ioctl however shall not change the driver state and therefore only
935adjust the requested rectangle.</para>
936
937 <para>Suppose scaling on a video capture device is restricted to
938a factor 1:1 or 2:1 in either direction and the target image size must
939be a multiple of 16&nbsp;&times;&nbsp;16 pixels. The source cropping
940rectangle is set to defaults, which are also the upper limit in this
941example, of 640&nbsp;&times;&nbsp;400 pixels at offset 0,&nbsp;0. An
942application requests an image size of 300&nbsp;&times;&nbsp;225
943pixels, assuming video will be scaled down from the "full picture"
944accordingly. The driver sets the image size to the closest possible
945values 304&nbsp;&times;&nbsp;224, then chooses the cropping rectangle
946closest to the requested size, that is 608&nbsp;&times;&nbsp;224
947(224&nbsp;&times;&nbsp;2:1 would exceed the limit 400). The offset
9480,&nbsp;0 is still valid, thus unmodified. Given the default cropping
949rectangle reported by <constant>VIDIOC_CROPCAP</constant> the
950application can easily propose another offset to center the cropping
951rectangle.</para>
952
953 <para>Now the application may insist on covering an area using a
954picture aspect ratio closer to the original request, so it asks for a
955cropping rectangle of 608&nbsp;&times;&nbsp;456 pixels. The present
956scaling factors limit cropping to 640&nbsp;&times;&nbsp;384, so the
957driver returns the cropping size 608&nbsp;&times;&nbsp;384 and adjusts
958the image size to closest possible 304&nbsp;&times;&nbsp;192.</para>
959
960 </section>
961
962 <section>
963 <title>Examples</title>
964
965 <para>Source and target rectangles shall remain unchanged across
966closing and reopening a device, such that piping data into or out of a
967device will work without special preparations. More advanced
968applications should ensure the parameters are suitable before starting
969I/O.</para>
970
971 <example>
972 <title>Resetting the cropping parameters</title>
973
974 <para>(A video capture device is assumed; change
975<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> for other
976devices.)</para>
977
978 <programlisting>
979&v4l2-cropcap; cropcap;
980&v4l2-crop; crop;
981
982memset (&amp;cropcap, 0, sizeof (cropcap));
983cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
984
985if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
986 perror ("VIDIOC_CROPCAP");
987 exit (EXIT_FAILURE);
988}
989
990memset (&amp;crop, 0, sizeof (crop));
991crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
992crop.c = cropcap.defrect;
993
994/* Ignore if cropping is not supported (EINVAL). */
995
996if (-1 == ioctl (fd, &VIDIOC-S-CROP;, &amp;crop)
997 &amp;&amp; errno != EINVAL) {
998 perror ("VIDIOC_S_CROP");
999 exit (EXIT_FAILURE);
1000}
1001 </programlisting>
1002 </example>
1003
1004 <example>
1005 <title>Simple downscaling</title>
1006
1007 <para>(A video capture device is assumed.)</para>
1008
1009 <programlisting>
1010&v4l2-cropcap; cropcap;
1011&v4l2-format; format;
1012
1013reset_cropping_parameters ();
1014
1015/* Scale down to 1/4 size of full picture. */
1016
1017memset (&amp;format, 0, sizeof (format)); /* defaults */
1018
1019format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1020
1021format.fmt.pix.width = cropcap.defrect.width &gt;&gt; 1;
1022format.fmt.pix.height = cropcap.defrect.height &gt;&gt; 1;
1023format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV;
1024
1025if (-1 == ioctl (fd, &VIDIOC-S-FMT;, &amp;format)) {
1026 perror ("VIDIOC_S_FORMAT");
1027 exit (EXIT_FAILURE);
1028}
1029
1030/* We could check the actual image size now, the actual scaling factor
1031 or if the driver can scale at all. */
1032 </programlisting>
1033 </example>
1034
1035 <example>
1036 <title>Selecting an output area</title>
1037
1038 <programlisting>
1039&v4l2-cropcap; cropcap;
1040&v4l2-crop; crop;
1041
1042memset (&amp;cropcap, 0, sizeof (cropcap));
1043cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1044
1045if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &amp;cropcap)) {
1046 perror ("VIDIOC_CROPCAP");
1047 exit (EXIT_FAILURE);
1048}
1049
1050memset (&amp;crop, 0, sizeof (crop));
1051
1052crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT;
1053crop.c = cropcap.defrect;
1054
1055/* Scale the width and height to 50 % of their original size
1056 and center the output. */
1057
1058crop.c.width /= 2;
1059crop.c.height /= 2;
1060crop.c.left += crop.c.width / 2;
1061crop.c.top += crop.c.height / 2;
1062
1063/* Ignore if cropping is not supported (EINVAL). */
1064
1065if (-1 == ioctl (fd, VIDIOC_S_CROP, &amp;crop)
1066 &amp;&amp; errno != EINVAL) {
1067 perror ("VIDIOC_S_CROP");
1068 exit (EXIT_FAILURE);
1069}
1070</programlisting>
1071 </example>
1072
1073 <example>
1074 <title>Current scaling factor and pixel aspect</title>
1075
1076 <para>(A video capture device is assumed.)</para>
1077
1078 <programlisting>
1079&v4l2-cropcap; cropcap;
1080&v4l2-crop; crop;
1081&v4l2-format; format;
1082double hscale, vscale;
1083double aspect;
1084int dwidth, dheight;
1085
1086memset (&amp;cropcap, 0, sizeof (cropcap));
1087cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1088
1089if (-1 == ioctl (fd, &VIDIOC-CROPCAP;, &amp;cropcap)) {
1090 perror ("VIDIOC_CROPCAP");
1091 exit (EXIT_FAILURE);
1092}
1093
1094memset (&amp;crop, 0, sizeof (crop));
1095crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1096
1097if (-1 == ioctl (fd, &VIDIOC-G-CROP;, &amp;crop)) {
1098 if (errno != EINVAL) {
1099 perror ("VIDIOC_G_CROP");
1100 exit (EXIT_FAILURE);
1101 }
1102
1103 /* Cropping not supported. */
1104 crop.c = cropcap.defrect;
1105}
1106
1107memset (&amp;format, 0, sizeof (format));
1108format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
1109
1110if (-1 == ioctl (fd, &VIDIOC-G-FMT;, &amp;format)) {
1111 perror ("VIDIOC_G_FMT");
1112 exit (EXIT_FAILURE);
1113}
1114
1115/* The scaling applied by the driver. */
1116
1117hscale = format.fmt.pix.width / (double) crop.c.width;
1118vscale = format.fmt.pix.height / (double) crop.c.height;
1119
1120aspect = cropcap.pixelaspect.numerator /
1121 (double) cropcap.pixelaspect.denominator;
1122aspect = aspect * hscale / vscale;
1123
1124/* Devices following ITU-R BT.601 do not capture
1125 square pixels. For playback on a computer monitor
1126 we should scale the images to this size. */
1127
1128dwidth = format.fmt.pix.width / aspect;
1129dheight = format.fmt.pix.height;
1130 </programlisting>
1131 </example>
1132 </section>
1133 </section>
1134
1135 <section id="streaming-par">
1136 <title>Streaming Parameters</title>
1137
1138 <para>Streaming parameters are intended to optimize the video
1139capture process as well as I/O. Presently applications can request a
1140high quality capture mode with the &VIDIOC-S-PARM; ioctl.</para>
1141
1142 <para>The current video standard determines a nominal number of
1143frames per second. If less than this number of frames is to be
1144captured or output, applications can request frame skipping or
1145duplicating on the driver side. This is especially useful when using
1146the &func-read; or &func-write;, which are not augmented by timestamps
1147or sequence counters, and to avoid unneccessary data copying.</para>
1148
1149 <para>Finally these ioctls can be used to determine the number of
1150buffers used internally by a driver in read/write mode. For
1151implications see the section discussing the &func-read;
1152function.</para>
1153
1154 <para>To get and set the streaming parameters applications call
1155the &VIDIOC-G-PARM; and &VIDIOC-S-PARM; ioctl, respectively. They take
1156a pointer to a &v4l2-streamparm;, which contains a union holding
1157separate parameters for input and output devices.</para>
1158
1159 <para>These ioctls are optional, drivers need not implement
1160them. If so, they return the &EINVAL;.</para>
1161 </section>
1162
1163 <!--
1164Local Variables:
1165mode: sgml
1166sgml-parent-document: "v4l2.sgml"
1167indent-tabs-mode: nil
1168End:
1169 -->
diff --git a/Documentation/DocBook/v4l/compat.xml b/Documentation/DocBook/v4l/compat.xml
new file mode 100644
index 000000000000..4d1902a54d61
--- /dev/null
+++ b/Documentation/DocBook/v4l/compat.xml
@@ -0,0 +1,2457 @@
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, teletext 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 V4L <filename>videodev</filename> module automatically
30assigns minor numbers to drivers in load order, depending on the
31registered device type. We recommend that V4L2 drivers by default
32register devices with the same numbers, but the system administrator
33can assign arbitrary minor numbers using driver module options. The
34major device number remains 81.</para>
35
36 <table id="v4l-dev">
37 <title>V4L Device Types, Names and Numbers</title>
38 <tgroup cols="3">
39 <thead>
40 <row>
41 <entry>Device Type</entry>
42 <entry>File Name</entry>
43 <entry>Minor Numbers</entry>
44 </row>
45 </thead>
46 <tbody valign="top">
47 <row>
48 <entry>Video capture and overlay</entry>
49 <entry><para><filename>/dev/video</filename> and
50<filename>/dev/bttv0</filename><footnote> <para>According to
51Documentation/devices.txt these should be symbolic links to
52<filename>/dev/video0</filename>. Note the original bttv interface is
53not compatible with V4L or V4L2.</para> </footnote>,
54<filename>/dev/video0</filename> to
55<filename>/dev/video63</filename></para></entry>
56 <entry>0-63</entry>
57 </row>
58 <row>
59 <entry>Radio receiver</entry>
60 <entry><para><filename>/dev/radio</filename><footnote>
61 <para>According to
62<filename>Documentation/devices.txt</filename> a symbolic link to
63<filename>/dev/radio0</filename>.</para>
64 </footnote>, <filename>/dev/radio0</filename> to
65<filename>/dev/radio63</filename></para></entry>
66 <entry>64-127</entry>
67 </row>
68 <row>
69 <entry>Teletext decoder</entry>
70 <entry><para><filename>/dev/vtx</filename>,
71<filename>/dev/vtx0</filename> to
72<filename>/dev/vtx31</filename></para></entry>
73 <entry>192-223</entry>
74 </row>
75 <row>
76 <entry>Raw VBI capture</entry>
77 <entry><para><filename>/dev/vbi</filename>,
78<filename>/dev/vbi0</filename> to
79<filename>/dev/vbi31</filename></para></entry>
80 <entry>224-255</entry>
81 </row>
82 </tbody>
83 </tgroup>
84 </table>
85
86 <para>V4L prohibits (or used to prohibit) multiple opens of a
87device file. V4L2 drivers <emphasis>may</emphasis> support multiple
88opens, see <xref linkend="open" /> for details and consequences.</para>
89
90 <para>V4L drivers respond to V4L2 ioctls with an &EINVAL;. The
91compatibility layer in the V4L2 <filename>videodev</filename> module
92can translate V4L ioctl requests to their V4L2 counterpart, however a
93V4L2 driver usually needs more preparation to become fully V4L
94compatible. This is covered in more detail in <xref
95 linkend="driver" />.</para>
96 </section>
97
98 <section>
99 <title>Querying Capabilities</title>
100
101 <para>The V4L <constant>VIDIOCGCAP</constant> ioctl is
102equivalent to V4L2's &VIDIOC-QUERYCAP;.</para>
103
104 <para>The <structfield>name</structfield> field in struct
105<structname>video_capability</structname> became
106<structfield>card</structfield> in &v4l2-capability;,
107<structfield>type</structfield> was replaced by
108<structfield>capabilities</structfield>. Note V4L2 does not
109distinguish between device types like this, better think of basic
110video input, video output and radio devices supporting a set of
111related functions like video capturing, video overlay and VBI
112capturing. See <xref linkend="open" /> for an
113introduction.<informaltable>
114 <tgroup cols="3">
115 <thead>
116 <row>
117 <entry>struct
118<structname>video_capability</structname>
119<structfield>type</structfield></entry>
120 <entry>&v4l2-capability;
121<structfield>capabilities</structfield> flags</entry>
122 <entry>Purpose</entry>
123 </row>
124 </thead>
125 <tbody valign="top">
126 <row>
127 <entry><constant>VID_TYPE_CAPTURE</constant></entry>
128 <entry><constant>V4L2_CAP_VIDEO_CAPTURE</constant></entry>
129 <entry>The <link linkend="capture">video
130capture</link> interface is supported.</entry>
131 </row>
132 <row>
133 <entry><constant>VID_TYPE_TUNER</constant></entry>
134 <entry><constant>V4L2_CAP_TUNER</constant></entry>
135 <entry>The device has a <link linkend="tuner">tuner or
136modulator</link>.</entry>
137 </row>
138 <row>
139 <entry><constant>VID_TYPE_TELETEXT</constant></entry>
140 <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
141 <entry>The <link linkend="raw-vbi">raw VBI
142capture</link> interface is supported.</entry>
143 </row>
144 <row>
145 <entry><constant>VID_TYPE_OVERLAY</constant></entry>
146 <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
147 <entry>The <link linkend="overlay">video
148overlay</link> interface is supported.</entry>
149 </row>
150 <row>
151 <entry><constant>VID_TYPE_CHROMAKEY</constant></entry>
152 <entry><constant>V4L2_FBUF_CAP_CHROMAKEY</constant> in
153field <structfield>capability</structfield> of
154&v4l2-framebuffer;</entry>
155 <entry>Whether chromakey overlay is supported. For
156more information on overlay see
157<xref linkend="overlay" />.</entry>
158 </row>
159 <row>
160 <entry><constant>VID_TYPE_CLIPPING</constant></entry>
161 <entry><constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant>
162and <constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant> in field
163<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
164 <entry>Whether clipping the overlaid image is
165supported, see <xref linkend="overlay" />.</entry>
166 </row>
167 <row>
168 <entry><constant>VID_TYPE_FRAMERAM</constant></entry>
169 <entry><constant>V4L2_FBUF_CAP_EXTERNOVERLAY</constant>
170<emphasis>not set</emphasis> in field
171<structfield>capability</structfield> of &v4l2-framebuffer;</entry>
172 <entry>Whether overlay overwrites frame buffer memory,
173see <xref linkend="overlay" />.</entry>
174 </row>
175 <row>
176 <entry><constant>VID_TYPE_SCALES</constant></entry>
177 <entry><constant>-</constant></entry>
178 <entry>This flag indicates if the hardware can scale
179images. The V4L2 API implies the scale factor by setting the cropping
180dimensions and image size with the &VIDIOC-S-CROP; and &VIDIOC-S-FMT;
181ioctl, respectively. The driver returns the closest sizes possible.
182For more information on cropping and scaling see <xref
183 linkend="crop" />.</entry>
184 </row>
185 <row>
186 <entry><constant>VID_TYPE_MONOCHROME</constant></entry>
187 <entry><constant>-</constant></entry>
188 <entry>Applications can enumerate the supported image
189formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
190supports grey scale capturing only. For more information on image
191formats see <xref linkend="pixfmt" />.</entry>
192 </row>
193 <row>
194 <entry><constant>VID_TYPE_SUBCAPTURE</constant></entry>
195 <entry><constant>-</constant></entry>
196 <entry>Applications can call the &VIDIOC-G-CROP; ioctl
197to determine if the device supports capturing a subsection of the full
198picture ("cropping" in V4L2). If not, the ioctl returns the &EINVAL;.
199For more information on cropping and scaling see <xref
200 linkend="crop" />.</entry>
201 </row>
202 <row>
203 <entry><constant>VID_TYPE_MPEG_DECODER</constant></entry>
204 <entry><constant>-</constant></entry>
205 <entry>Applications can enumerate the supported image
206formats with the &VIDIOC-ENUM-FMT; ioctl to determine if the device
207supports MPEG streams.</entry>
208 </row>
209 <row>
210 <entry><constant>VID_TYPE_MPEG_ENCODER</constant></entry>
211 <entry><constant>-</constant></entry>
212 <entry>See above.</entry>
213 </row>
214 <row>
215 <entry><constant>VID_TYPE_MJPEG_DECODER</constant></entry>
216 <entry><constant>-</constant></entry>
217 <entry>See above.</entry>
218 </row>
219 <row>
220 <entry><constant>VID_TYPE_MJPEG_ENCODER</constant></entry>
221 <entry><constant>-</constant></entry>
222 <entry>See above.</entry>
223 </row>
224 </tbody>
225 </tgroup>
226 </informaltable></para>
227
228 <para>The <structfield>audios</structfield> field was replaced
229by <structfield>capabilities</structfield> flag
230<constant>V4L2_CAP_AUDIO</constant>, indicating
231<emphasis>if</emphasis> the device has any audio inputs or outputs. To
232determine their number applications can enumerate audio inputs with
233the &VIDIOC-G-AUDIO; ioctl. The audio ioctls are described in <xref
234 linkend="audio" />.</para>
235
236 <para>The <structfield>maxwidth</structfield>,
237<structfield>maxheight</structfield>,
238<structfield>minwidth</structfield> and
239<structfield>minheight</structfield> fields were removed. Calling the
240&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT; ioctl with the desired dimensions
241returns the closest size possible, taking into account the current
242video standard, cropping and scaling limitations.</para>
243 </section>
244
245 <section>
246 <title>Video Sources</title>
247
248 <para>V4L provides the <constant>VIDIOCGCHAN</constant> and
249<constant>VIDIOCSCHAN</constant> ioctl using struct
250<structname>video_channel</structname> to enumerate
251the video inputs of a V4L device. The equivalent V4L2 ioctls
252are &VIDIOC-ENUMINPUT;, &VIDIOC-G-INPUT; and &VIDIOC-S-INPUT;
253using &v4l2-input; as discussed in <xref linkend="video" />.</para>
254
255 <para>The <structfield>channel</structfield> field counting
256inputs was renamed to <structfield>index</structfield>, the video
257input types were renamed as follows: <informaltable>
258 <tgroup cols="2">
259 <thead>
260 <row>
261 <entry>struct <structname>video_channel</structname>
262<structfield>type</structfield></entry>
263 <entry>&v4l2-input;
264<structfield>type</structfield></entry>
265 </row>
266 </thead>
267 <tbody valign="top">
268 <row>
269 <entry><constant>VIDEO_TYPE_TV</constant></entry>
270 <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
271 </row>
272 <row>
273 <entry><constant>VIDEO_TYPE_CAMERA</constant></entry>
274 <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
275 </row>
276 </tbody>
277 </tgroup>
278 </informaltable></para>
279
280 <para>Unlike the <structfield>tuners</structfield> field
281expressing the number of tuners of this input, V4L2 assumes each video
282input is connected to at most one tuner. However a tuner can have more
283than one input, &ie; RF connectors, and a device can have multiple
284tuners. The index number of the tuner associated with the input, if
285any, is stored in field <structfield>tuner</structfield> of
286&v4l2-input;. Enumeration of tuners is discussed in <xref
287 linkend="tuner" />.</para>
288
289 <para>The redundant <constant>VIDEO_VC_TUNER</constant> flag was
290dropped. Video inputs associated with a tuner are of type
291<constant>V4L2_INPUT_TYPE_TUNER</constant>. The
292<constant>VIDEO_VC_AUDIO</constant> flag was replaced by the
293<structfield>audioset</structfield> field. V4L2 considers devices with
294up to 32 audio inputs. Each set bit in the
295<structfield>audioset</structfield> field represents one audio input
296this video input combines with. For information about audio inputs and
297how to switch between them see <xref linkend="audio" />.</para>
298
299 <para>The <structfield>norm</structfield> field describing the
300supported video standards was replaced by
301<structfield>std</structfield>. The V4L specification mentions a flag
302<constant>VIDEO_VC_NORM</constant> indicating whether the standard can
303be changed. This flag was a later addition together with the
304<structfield>norm</structfield> field and has been removed in the
305meantime. V4L2 has a similar, albeit more comprehensive approach
306to video standards, see <xref linkend="standard" /> for more
307information.</para>
308 </section>
309
310 <section>
311 <title>Tuning</title>
312
313 <para>The V4L <constant>VIDIOCGTUNER</constant> and
314<constant>VIDIOCSTUNER</constant> ioctl and struct
315<structname>video_tuner</structname> can be used to enumerate the
316tuners of a V4L TV or radio device. The equivalent V4L2 ioctls are
317&VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; using &v4l2-tuner;. Tuners are
318covered in <xref linkend="tuner" />.</para>
319
320 <para>The <structfield>tuner</structfield> field counting tuners
321was renamed to <structfield>index</structfield>. The fields
322<structfield>name</structfield>, <structfield>rangelow</structfield>
323and <structfield>rangehigh</structfield> remained unchanged.</para>
324
325 <para>The <constant>VIDEO_TUNER_PAL</constant>,
326<constant>VIDEO_TUNER_NTSC</constant> and
327<constant>VIDEO_TUNER_SECAM</constant> flags indicating the supported
328video standards were dropped. This information is now contained in the
329associated &v4l2-input;. No replacement exists for the
330<constant>VIDEO_TUNER_NORM</constant> flag indicating whether the
331video standard can be switched. The <structfield>mode</structfield>
332field to select a different video standard was replaced by a whole new
333set of ioctls and structures described in <xref linkend="standard" />.
334Due to its ubiquity it should be mentioned the BTTV driver supports
335several standards in addition to the regular
336<constant>VIDEO_MODE_PAL</constant> (0),
337<constant>VIDEO_MODE_NTSC</constant>,
338<constant>VIDEO_MODE_SECAM</constant> and
339<constant>VIDEO_MODE_AUTO</constant> (3). Namely N/PAL Argentina,
340M/PAL, N/PAL, and NTSC Japan with numbers 3-6 (sic).</para>
341
342 <para>The <constant>VIDEO_TUNER_STEREO_ON</constant> flag
343indicating stereo reception became
344<constant>V4L2_TUNER_SUB_STEREO</constant> in field
345<structfield>rxsubchans</structfield>. This field also permits the
346detection of monaural and bilingual audio, see the definition of
347&v4l2-tuner; for details. Presently no replacement exists for the
348<constant>VIDEO_TUNER_RDS_ON</constant> and
349<constant>VIDEO_TUNER_MBS_ON</constant> flags.</para>
350
351 <para> The <constant>VIDEO_TUNER_LOW</constant> flag was renamed
352to <constant>V4L2_TUNER_CAP_LOW</constant> in the &v4l2-tuner;
353<structfield>capability</structfield> field.</para>
354
355 <para>The <constant>VIDIOCGFREQ</constant> and
356<constant>VIDIOCSFREQ</constant> ioctl to change the tuner frequency
357where renamed to &VIDIOC-G-FREQUENCY; and &VIDIOC-S-FREQUENCY;. They
358take a pointer to a &v4l2-frequency; instead of an unsigned long
359integer.</para>
360 </section>
361
362 <section id="v4l-image-properties">
363 <title>Image Properties</title>
364
365 <para>V4L2 has no equivalent of the
366<constant>VIDIOCGPICT</constant> and <constant>VIDIOCSPICT</constant>
367ioctl and struct <structname>video_picture</structname>. The following
368fields where replaced by V4L2 controls accessible with the
369&VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls:<informaltable>
370 <tgroup cols="2">
371 <thead>
372 <row>
373 <entry>struct <structname>video_picture</structname></entry>
374 <entry>V4L2 Control ID</entry>
375 </row>
376 </thead>
377 <tbody valign="top">
378 <row>
379 <entry><structfield>brightness</structfield></entry>
380 <entry><constant>V4L2_CID_BRIGHTNESS</constant></entry>
381 </row>
382 <row>
383 <entry><structfield>hue</structfield></entry>
384 <entry><constant>V4L2_CID_HUE</constant></entry>
385 </row>
386 <row>
387 <entry><structfield>colour</structfield></entry>
388 <entry><constant>V4L2_CID_SATURATION</constant></entry>
389 </row>
390 <row>
391 <entry><structfield>contrast</structfield></entry>
392 <entry><constant>V4L2_CID_CONTRAST</constant></entry>
393 </row>
394 <row>
395 <entry><structfield>whiteness</structfield></entry>
396 <entry><constant>V4L2_CID_WHITENESS</constant></entry>
397 </row>
398 </tbody>
399 </tgroup>
400 </informaltable></para>
401
402 <para>The V4L picture controls are assumed to range from 0 to
40365535 with no particular reset value. The V4L2 API permits arbitrary
404limits and defaults which can be queried with the &VIDIOC-QUERYCTRL;
405ioctl. For general information about controls see <xref
406linkend="control" />.</para>
407
408 <para>The <structfield>depth</structfield> (average number of
409bits per pixel) of a video image is implied by the selected image
410format. V4L2 does not explicitely provide such information assuming
411applications recognizing the format are aware of the image depth and
412others need not know. The <structfield>palette</structfield> field
413moved into the &v4l2-pix-format;:<informaltable>
414 <tgroup cols="2">
415 <thead>
416 <row>
417 <entry>struct <structname>video_picture</structname>
418<structfield>palette</structfield></entry>
419 <entry>&v4l2-pix-format;
420<structfield>pixfmt</structfield></entry>
421 </row>
422 </thead>
423 <tbody valign="top">
424 <row>
425 <entry><constant>VIDEO_PALETTE_GREY</constant></entry>
426 <entry><para><link
427linkend="V4L2-PIX-FMT-GREY"><constant>V4L2_PIX_FMT_GREY</constant></link></para></entry>
428 </row>
429 <row>
430 <entry><constant>VIDEO_PALETTE_HI240</constant></entry>
431 <entry><para><link
432linkend="pixfmt-reserved"><constant>V4L2_PIX_FMT_HI240</constant></link><footnote>
433 <para>This is a custom format used by the BTTV
434driver, not one of the V4L2 standard formats.</para>
435 </footnote></para></entry>
436 </row>
437 <row>
438 <entry><constant>VIDEO_PALETTE_RGB565</constant></entry>
439 <entry><para><link
440linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB565</constant></link></para></entry>
441 </row>
442 <row>
443 <entry><constant>VIDEO_PALETTE_RGB555</constant></entry>
444 <entry><para><link
445linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_RGB555</constant></link></para></entry>
446 </row>
447 <row>
448 <entry><constant>VIDEO_PALETTE_RGB24</constant></entry>
449 <entry><para><link
450linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entry>
451 </row>
452 <row>
453 <entry><constant>VIDEO_PALETTE_RGB32</constant></entry>
454 <entry><para><link
455linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote>
456 <para>Presumably all V4L RGB formats are
457little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue
458swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para>
459 </footnote></para></entry>
460 </row>
461 <row>
462 <entry><constant>VIDEO_PALETTE_YUV422</constant></entry>
463 <entry><para><link
464linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
465 </row>
466 <row>
467 <entry><para><constant>VIDEO_PALETTE_YUYV</constant><footnote>
468 <para><constant>VIDEO_PALETTE_YUV422</constant>
469and <constant>VIDEO_PALETTE_YUYV</constant> are the same formats. Some
470V4L drivers respond to one, some to the other.</para>
471 </footnote></para></entry>
472 <entry><para><link
473linkend="V4L2-PIX-FMT-YUYV"><constant>V4L2_PIX_FMT_YUYV</constant></link></para></entry>
474 </row>
475 <row>
476 <entry><constant>VIDEO_PALETTE_UYVY</constant></entry>
477 <entry><para><link
478linkend="V4L2-PIX-FMT-UYVY"><constant>V4L2_PIX_FMT_UYVY</constant></link></para></entry>
479 </row>
480 <row>
481 <entry><constant>VIDEO_PALETTE_YUV420</constant></entry>
482 <entry>None</entry>
483 </row>
484 <row>
485 <entry><constant>VIDEO_PALETTE_YUV411</constant></entry>
486 <entry><para><link
487linkend="V4L2-PIX-FMT-Y41P"><constant>V4L2_PIX_FMT_Y41P</constant></link><footnote>
488 <para>Not to be confused with
489<constant>V4L2_PIX_FMT_YUV411P</constant>, which is a planar
490format.</para> </footnote></para></entry>
491 </row>
492 <row>
493 <entry><constant>VIDEO_PALETTE_RAW</constant></entry>
494 <entry><para>None<footnote> <para>V4L explains this
495as: "RAW capture (BT848)"</para> </footnote></para></entry>
496 </row>
497 <row>
498 <entry><constant>VIDEO_PALETTE_YUV422P</constant></entry>
499 <entry><para><link
500linkend="V4L2-PIX-FMT-YUV422P"><constant>V4L2_PIX_FMT_YUV422P</constant></link></para></entry>
501 </row>
502 <row>
503 <entry><constant>VIDEO_PALETTE_YUV411P</constant></entry>
504 <entry><para><link
505linkend="V4L2-PIX-FMT-YUV411P"><constant>V4L2_PIX_FMT_YUV411P</constant></link><footnote>
506 <para>Not to be confused with
507<constant>V4L2_PIX_FMT_Y41P</constant>, which is a packed
508format.</para> </footnote></para></entry>
509 </row>
510 <row>
511 <entry><constant>VIDEO_PALETTE_YUV420P</constant></entry>
512 <entry><para><link
513linkend="V4L2-PIX-FMT-YVU420"><constant>V4L2_PIX_FMT_YVU420</constant></link></para></entry>
514 </row>
515 <row>
516 <entry><constant>VIDEO_PALETTE_YUV410P</constant></entry>
517 <entry><para><link
518linkend="V4L2-PIX-FMT-YVU410"><constant>V4L2_PIX_FMT_YVU410</constant></link></para></entry>
519 </row>
520 </tbody>
521 </tgroup>
522 </informaltable></para>
523
524 <para>V4L2 image formats are defined in <xref
525linkend="pixfmt" />. The image format can be selected with the
526&VIDIOC-S-FMT; ioctl.</para>
527 </section>
528
529 <section>
530 <title>Audio</title>
531
532 <para>The <constant>VIDIOCGAUDIO</constant> and
533<constant>VIDIOCSAUDIO</constant> ioctl and struct
534<structname>video_audio</structname> are used to enumerate the
535audio inputs of a V4L device. The equivalent V4L2 ioctls are
536&VIDIOC-G-AUDIO; and &VIDIOC-S-AUDIO; using &v4l2-audio; as
537discussed in <xref linkend="audio" />.</para>
538
539 <para>The <structfield>audio</structfield> "channel number"
540field counting audio inputs was renamed to
541<structfield>index</structfield>.</para>
542
543 <para>On <constant>VIDIOCSAUDIO</constant> the
544<structfield>mode</structfield> field selects <emphasis>one</emphasis>
545of the <constant>VIDEO_SOUND_MONO</constant>,
546<constant>VIDEO_SOUND_STEREO</constant>,
547<constant>VIDEO_SOUND_LANG1</constant> or
548<constant>VIDEO_SOUND_LANG2</constant> audio demodulation modes. When
549the current audio standard is BTSC
550<constant>VIDEO_SOUND_LANG2</constant> refers to SAP and
551<constant>VIDEO_SOUND_LANG1</constant> is meaningless. Also
552undocumented in the V4L specification, there is no way to query the
553selected mode. On <constant>VIDIOCGAUDIO</constant> the driver returns
554the <emphasis>actually received</emphasis> audio programmes in this
555field. In the V4L2 API this information is stored in the &v4l2-tuner;
556<structfield>rxsubchans</structfield> and
557<structfield>audmode</structfield> fields, respectively. See <xref
558linkend="tuner" /> for more information on tuners. Related to audio
559modes &v4l2-audio; also reports if this is a mono or stereo
560input, regardless if the source is a tuner.</para>
561
562 <para>The following fields where replaced by V4L2 controls
563accessible with the &VIDIOC-QUERYCTRL;, &VIDIOC-G-CTRL; and
564&VIDIOC-S-CTRL; ioctls:<informaltable>
565 <tgroup cols="2">
566 <thead>
567 <row>
568 <entry>struct
569<structname>video_audio</structname></entry>
570 <entry>V4L2 Control ID</entry>
571 </row>
572 </thead>
573 <tbody valign="top">
574 <row>
575 <entry><structfield>volume</structfield></entry>
576 <entry><constant>V4L2_CID_AUDIO_VOLUME</constant></entry>
577 </row>
578 <row>
579 <entry><structfield>bass</structfield></entry>
580 <entry><constant>V4L2_CID_AUDIO_BASS</constant></entry>
581 </row>
582 <row>
583 <entry><structfield>treble</structfield></entry>
584 <entry><constant>V4L2_CID_AUDIO_TREBLE</constant></entry>
585 </row>
586 <row>
587 <entry><structfield>balance</structfield></entry>
588 <entry><constant>V4L2_CID_AUDIO_BALANCE</constant></entry>
589 </row>
590 </tbody>
591 </tgroup>
592 </informaltable></para>
593
594 <para>To determine which of these controls are supported by a
595driver V4L provides the <structfield>flags</structfield>
596<constant>VIDEO_AUDIO_VOLUME</constant>,
597<constant>VIDEO_AUDIO_BASS</constant>,
598<constant>VIDEO_AUDIO_TREBLE</constant> and
599<constant>VIDEO_AUDIO_BALANCE</constant>. In the V4L2 API the
600&VIDIOC-QUERYCTRL; ioctl reports if the respective control is
601supported. Accordingly the <constant>VIDEO_AUDIO_MUTABLE</constant>
602and <constant>VIDEO_AUDIO_MUTE</constant> flags where replaced by the
603boolean <constant>V4L2_CID_AUDIO_MUTE</constant> control.</para>
604
605 <para>All V4L2 controls have a <structfield>step</structfield>
606attribute replacing the struct <structname>video_audio</structname>
607<structfield>step</structfield> field. The V4L audio controls are
608assumed to range from 0 to 65535 with no particular reset value. The
609V4L2 API permits arbitrary limits and defaults which can be queried
610with the &VIDIOC-QUERYCTRL; ioctl. For general information about
611controls see <xref linkend="control" />.</para>
612 </section>
613
614 <section>
615 <title>Frame Buffer Overlay</title>
616
617 <para>The V4L2 ioctls equivalent to
618<constant>VIDIOCGFBUF</constant> and <constant>VIDIOCSFBUF</constant>
619are &VIDIOC-G-FBUF; and &VIDIOC-S-FBUF;. The
620<structfield>base</structfield> field of struct
621<structname>video_buffer</structname> remained unchanged, except V4L2
622defines a flag to indicate non-destructive overlays instead of a
623<constant>NULL</constant> pointer. All other fields moved into the
624&v4l2-pix-format; <structfield>fmt</structfield> substructure of
625&v4l2-framebuffer;. The <structfield>depth</structfield> field was
626replaced by <structfield>pixelformat</structfield>. See <xref
627 linkend="pixfmt-rgb" /> for a list of RGB formats and their
628respective color depths.</para>
629
630 <para>Instead of the special ioctls
631<constant>VIDIOCGWIN</constant> and <constant>VIDIOCSWIN</constant>
632V4L2 uses the general-purpose data format negotiation ioctls
633&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
634&v4l2-format; as argument. Here the <structfield>win</structfield>
635member of the <structfield>fmt</structfield> union is used, a
636&v4l2-window;.</para>
637
638 <para>The <structfield>x</structfield>,
639<structfield>y</structfield>, <structfield>width</structfield> and
640<structfield>height</structfield> fields of struct
641<structname>video_window</structname> moved into &v4l2-rect;
642substructure <structfield>w</structfield> of struct
643<structname>v4l2_window</structname>. The
644<structfield>chromakey</structfield>,
645<structfield>clips</structfield>, and
646<structfield>clipcount</structfield> fields remained unchanged. Struct
647<structname>video_clip</structname> was renamed to &v4l2-clip;, also
648containing a struct <structname>v4l2_rect</structname>, but the
649semantics are still the same.</para>
650
651 <para>The <constant>VIDEO_WINDOW_INTERLACE</constant> flag was
652dropped. Instead applications must set the
653<structfield>field</structfield> field to
654<constant>V4L2_FIELD_ANY</constant> or
655<constant>V4L2_FIELD_INTERLACED</constant>. The
656<constant>VIDEO_WINDOW_CHROMAKEY</constant> flag moved into
657&v4l2-framebuffer;, under the new name
658<constant>V4L2_FBUF_FLAG_CHROMAKEY</constant>.</para>
659
660 <para>In V4L, storing a bitmap pointer in
661<structfield>clips</structfield> and setting
662<structfield>clipcount</structfield> to
663<constant>VIDEO_CLIP_BITMAP</constant> (-1) requests bitmap
664clipping, using a fixed size bitmap of 1024 &times; 625 bits. Struct
665<structname>v4l2_window</structname> has a separate
666<structfield>bitmap</structfield> pointer field for this purpose and
667the bitmap size is determined by <structfield>w.width</structfield> and
668<structfield>w.height</structfield>.</para>
669
670 <para>The <constant>VIDIOCCAPTURE</constant> ioctl to enable or
671disable overlay was renamed to &VIDIOC-OVERLAY;.</para>
672 </section>
673
674 <section>
675 <title>Cropping</title>
676
677 <para>To capture only a subsection of the full picture V4L
678defines the <constant>VIDIOCGCAPTURE</constant> and
679<constant>VIDIOCSCAPTURE</constant> ioctls using struct
680<structname>video_capture</structname>. The equivalent V4L2 ioctls are
681&VIDIOC-G-CROP; and &VIDIOC-S-CROP; using &v4l2-crop;, and the related
682&VIDIOC-CROPCAP; ioctl. This is a rather complex matter, see
683<xref linkend="crop" /> for details.</para>
684
685 <para>The <structfield>x</structfield>,
686<structfield>y</structfield>, <structfield>width</structfield> and
687<structfield>height</structfield> fields moved into &v4l2-rect;
688substructure <structfield>c</structfield> of struct
689<structname>v4l2_crop</structname>. The
690<structfield>decimation</structfield> field was dropped. In the V4L2
691API the scaling factor is implied by the size of the cropping
692rectangle and the size of the captured or overlaid image.</para>
693
694 <para>The <constant>VIDEO_CAPTURE_ODD</constant>
695and <constant>VIDEO_CAPTURE_EVEN</constant> flags to capture only the
696odd or even field, respectively, were replaced by
697<constant>V4L2_FIELD_TOP</constant> and
698<constant>V4L2_FIELD_BOTTOM</constant> in the field named
699<structfield>field</structfield> of &v4l2-pix-format; and
700&v4l2-window;. These structures are used to select a capture or
701overlay format with the &VIDIOC-S-FMT; ioctl.</para>
702 </section>
703
704 <section>
705 <title>Reading Images, Memory Mapping</title>
706
707 <section>
708 <title>Capturing using the read method</title>
709
710 <para>There is no essential difference between reading images
711from a V4L or V4L2 device using the &func-read; function, however V4L2
712drivers are not required to support this I/O method. Applications can
713determine if the function is available with the &VIDIOC-QUERYCAP;
714ioctl. All V4L2 devices exchanging data with applications must support
715the &func-select; and &func-poll; functions.</para>
716
717 <para>To select an image format and size, V4L provides the
718<constant>VIDIOCSPICT</constant> and <constant>VIDIOCSWIN</constant>
719ioctls. V4L2 uses the general-purpose data format negotiation ioctls
720&VIDIOC-G-FMT; and &VIDIOC-S-FMT;. They take a pointer to a
721&v4l2-format; as argument, here the &v4l2-pix-format; named
722<structfield>pix</structfield> of its <structfield>fmt</structfield>
723union is used.</para>
724
725 <para>For more information about the V4L2 read interface see
726<xref linkend="rw" />.</para>
727 </section>
728 <section>
729 <title>Capturing using memory mapping</title>
730
731 <para>Applications can read from V4L devices by mapping
732buffers in device memory, or more often just buffers allocated in
733DMA-able system memory, into their address space. This avoids the data
734copying overhead of the read method. V4L2 supports memory mapping as
735well, with a few differences.</para>
736
737 <informaltable>
738 <tgroup cols="2">
739 <thead>
740 <row>
741 <entry>V4L</entry>
742 <entry>V4L2</entry>
743 </row>
744 </thead>
745 <tbody valign="top">
746 <row>
747 <entry></entry>
748 <entry>The image format must be selected before
749buffers are allocated, with the &VIDIOC-S-FMT; ioctl. When no format
750is selected the driver may use the last, possibly by another
751application requested format.</entry>
752 </row>
753 <row>
754 <entry><para>Applications cannot change the number of
755buffers. The it is built into the driver, unless it has a module
756option to change the number when the driver module is
757loaded.</para></entry>
758 <entry><para>The &VIDIOC-REQBUFS; ioctl allocates the
759desired number of buffers, this is a required step in the initialization
760sequence.</para></entry>
761 </row>
762 <row>
763 <entry><para>Drivers map all buffers as one contiguous
764range of memory. The <constant>VIDIOCGMBUF</constant> ioctl is
765available to query the number of buffers, the offset of each buffer
766from the start of the virtual file, and the overall amount of memory
767used, which can be used as arguments for the &func-mmap;
768function.</para></entry>
769 <entry><para>Buffers are individually mapped. The
770offset and size of each buffer can be determined with the
771&VIDIOC-QUERYBUF; ioctl.</para></entry>
772 </row>
773 <row>
774 <entry><para>The <constant>VIDIOCMCAPTURE</constant>
775ioctl prepares a buffer for capturing. It also determines the image
776format for this buffer. The ioctl returns immediately, eventually with
777an &EAGAIN; if no video signal had been detected. When the driver
778supports more than one buffer applications can call the ioctl multiple
779times and thus have multiple outstanding capture
780requests.</para><para>The <constant>VIDIOCSYNC</constant> ioctl
781suspends execution until a particular buffer has been
782filled.</para></entry>
783 <entry><para>Drivers maintain an incoming and outgoing
784queue. &VIDIOC-QBUF; enqueues any empty buffer into the incoming
785queue. Filled buffers are dequeued from the outgoing queue with the
786&VIDIOC-DQBUF; ioctl. To wait until filled buffers become available this
787function, &func-select; or &func-poll; can be used. The
788&VIDIOC-STREAMON; ioctl must be called once after enqueuing one or
789more buffers to start capturing. Its counterpart
790&VIDIOC-STREAMOFF; stops capturing and dequeues all buffers from both
791queues. Applications can query the signal status, if known, with the
792&VIDIOC-ENUMINPUT; ioctl.</para></entry>
793 </row>
794 </tbody>
795 </tgroup>
796 </informaltable>
797
798 <para>For a more in-depth discussion of memory mapping and
799examples, see <xref linkend="mmap" />.</para>
800 </section>
801 </section>
802
803 <section>
804 <title>Reading Raw VBI Data</title>
805
806 <para>Originally the V4L API did not specify a raw VBI capture
807interface, only the device file <filename>/dev/vbi</filename> was
808reserved for this purpose. The only driver supporting this interface
809was the BTTV driver, de-facto defining the V4L VBI interface. Reading
810from the device yields a raw VBI image with the following
811parameters:<informaltable>
812 <tgroup cols="2">
813 <thead>
814 <row>
815 <entry>&v4l2-vbi-format;</entry>
816 <entry>V4L, BTTV driver</entry>
817 </row>
818 </thead>
819 <tbody valign="top">
820 <row>
821 <entry>sampling_rate</entry>
822 <entry>28636363&nbsp;Hz NTSC (or any other 525-line
823standard); 35468950&nbsp;Hz PAL and SECAM (625-line standards)</entry>
824 </row>
825 <row>
826 <entry>offset</entry>
827 <entry>?</entry>
828 </row>
829 <row>
830 <entry>samples_per_line</entry>
831 <entry>2048</entry>
832 </row>
833 <row>
834 <entry>sample_format</entry>
835 <entry>V4L2_PIX_FMT_GREY. The last four bytes (a
836machine endianess integer) contain a frame counter.</entry>
837 </row>
838 <row>
839 <entry>start[]</entry>
840 <entry>10, 273 NTSC; 22, 335 PAL and SECAM</entry>
841 </row>
842 <row>
843 <entry>count[]</entry>
844 <entry><para>16, 16<footnote><para>Old driver
845versions used different values, eventually the custom
846<constant>BTTV_VBISIZE</constant> ioctl was added to query the
847correct values.</para></footnote></para></entry>
848 </row>
849 <row>
850 <entry>flags</entry>
851 <entry>0</entry>
852 </row>
853 </tbody>
854 </tgroup>
855 </informaltable></para>
856
857 <para>Undocumented in the V4L specification, in Linux 2.3 the
858<constant>VIDIOCGVBIFMT</constant> and
859<constant>VIDIOCSVBIFMT</constant> ioctls using struct
860<structname>vbi_format</structname> were added to determine the VBI
861image parameters. These ioctls are only partially compatible with the
862V4L2 VBI interface specified in <xref linkend="raw-vbi" />.</para>
863
864 <para>An <structfield>offset</structfield> field does not
865exist, <structfield>sample_format</structfield> is supposed to be
866<constant>VIDEO_PALETTE_RAW</constant>, equivalent to
867<constant>V4L2_PIX_FMT_GREY</constant>. The remaining fields are
868probably equivalent to &v4l2-vbi-format;.</para>
869
870 <para>Apparently only the Zoran (ZR 36120) driver implements
871these ioctls. The semantics differ from those specified for V4L2 in two
872ways. The parameters are reset on &func-open; and
873<constant>VIDIOCSVBIFMT</constant> always returns an &EINVAL; if the
874parameters are invalid.</para>
875 </section>
876
877 <section>
878 <title>Miscellaneous</title>
879
880 <para>V4L2 has no equivalent of the
881<constant>VIDIOCGUNIT</constant> ioctl. Applications can find the VBI
882device associated with a video capture device (or vice versa) by
883reopening the device and requesting VBI data. For details see
884<xref linkend="open" />.</para>
885
886 <para>No replacement exists for <constant>VIDIOCKEY</constant>,
887and the V4L functions for microcode programming. A new interface for
888MPEG compression and playback devices is documented in <xref
889 linkend="extended-controls" />.</para>
890 </section>
891
892 </section>
893
894 <section id="hist-v4l2">
895 <title>Changes of the V4L2 API</title>
896
897 <para>Soon after the V4L API was added to the kernel it was
898criticised as too inflexible. In August 1998 Bill Dirks proposed a
899number of improvements and began to work on documentation, example
900drivers and applications. With the help of other volunteers this
901eventually became the V4L2 API, not just an extension but a
902replacement for the V4L API. However it took another four years and
903two stable kernel releases until the new API was finally accepted for
904inclusion into the kernel in its present form.</para>
905
906 <section>
907 <title>Early Versions</title>
908 <para>1998-08-20: First version.</para>
909
910 <para>1998-08-27: The &func-select; function was introduced.</para>
911
912 <para>1998-09-10: New video standard interface.</para>
913
914 <para>1998-09-18: The <constant>VIDIOC_NONCAP</constant> ioctl
915was replaced by the otherwise meaningless <constant>O_TRUNC</constant>
916&func-open; flag, and the aliases <constant>O_NONCAP</constant> and
917<constant>O_NOIO</constant> were defined. Applications can set this
918flag if they intend to access controls only, as opposed to capture
919applications which need exclusive access. The
920<constant>VIDEO_STD_XXX</constant> identifiers are now ordinals
921instead of flags, and the <function>video_std_construct()</function>
922helper function takes id and transmission arguments.</para>
923
924 <para>1998-09-28: Revamped video standard. Made video controls
925individually enumerable.</para>
926
927 <para>1998-10-02: The <structfield>id</structfield> field was
928removed from struct <structname>video_standard</structname> and the
929color subcarrier fields were renamed. The &VIDIOC-QUERYSTD; ioctl was
930renamed to &VIDIOC-ENUMSTD;, &VIDIOC-G-INPUT; to &VIDIOC-ENUMINPUT;. A
931first draft of the Codec API was released.</para>
932
933 <para>1998-11-08: Many minor changes. Most symbols have been
934renamed. Some material changes to &v4l2-capability;.</para>
935
936 <para>1998-11-12: The read/write directon of some ioctls was misdefined.</para>
937
938 <para>1998-11-14: <constant>V4L2_PIX_FMT_RGB24</constant>
939changed to <constant>V4L2_PIX_FMT_BGR24</constant>, and
940<constant>V4L2_PIX_FMT_RGB32</constant> changed to
941<constant>V4L2_PIX_FMT_BGR32</constant>. Audio controls are now
942accessible with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls under
943names starting with <constant>V4L2_CID_AUDIO</constant>. The
944<constant>V4L2_MAJOR</constant> define was removed from
945<filename>videodev.h</filename> since it was only used once in the
946<filename>videodev</filename> kernel module. The
947<constant>YUV422</constant> and <constant>YUV411</constant> planar
948image formats were added.</para>
949
950 <para>1998-11-28: A few ioctl symbols changed. Interfaces for codecs and
951video output devices were added.</para>
952
953 <para>1999-01-14: A raw VBI capture interface was added.</para>
954
955 <para>1999-01-19: The <constant>VIDIOC_NEXTBUF</constant> ioctl
956 was removed.</para>
957 </section>
958
959 <section>
960 <title>V4L2 Version 0.16 1999-01-31</title>
961 <para>1999-01-27: There is now one QBUF ioctl, VIDIOC_QWBUF and VIDIOC_QRBUF
962are gone. VIDIOC_QBUF takes a v4l2_buffer as a parameter. Added
963digital zoom (cropping) controls.</para>
964 </section>
965
966 <!-- Where's 0.17? mhs couldn't find that videodev.h, perhaps Bill
967 forgot to bump the version number or never released it. -->
968
969 <section>
970 <title>V4L2 Version 0.18 1999-03-16</title>
971 <para>Added a v4l to V4L2 ioctl compatibility layer to
972videodev.c. Driver writers, this changes how you implement your ioctl
973handler. See the Driver Writer's Guide. Added some more control id
974codes.</para>
975 </section>
976
977 <section>
978 <title>V4L2 Version 0.19 1999-06-05</title>
979 <para>1999-03-18: Fill in the category and catname fields of
980v4l2_queryctrl objects before passing them to the driver. Required a
981minor change to the VIDIOC_QUERYCTRL handlers in the sample
982drivers.</para>
983 <para>1999-03-31: Better compatibility for v4l memory capture
984ioctls. Requires changes to drivers to fully support new compatibility
985features, see Driver Writer's Guide and v4l2cap.c. Added new control
986IDs: V4L2_CID_HFLIP, _VFLIP. Changed V4L2_PIX_FMT_YUV422P to _YUV422P,
987and _YUV411P to _YUV411P.</para>
988 <para>1999-04-04: Added a few more control IDs.</para>
989 <para>1999-04-07: Added the button control type.</para>
990 <para>1999-05-02: Fixed a typo in videodev.h, and added the
991V4L2_CTRL_FLAG_GRAYED (later V4L2_CTRL_FLAG_GRABBED) flag.</para>
992 <para>1999-05-20: Definition of VIDIOC_G_CTRL was wrong causing
993a malfunction of this ioctl.</para>
994 <para>1999-06-05: Changed the value of
995V4L2_CID_WHITENESS.</para>
996 </section>
997
998 <section>
999 <title>V4L2 Version 0.20 (1999-09-10)</title>
1000
1001 <para>Version 0.20 introduced a number of changes which were
1002<emphasis>not backward compatible</emphasis> with 0.19 and earlier
1003versions. Purpose of these changes was to simplify the API, while
1004making it more extensible and following common Linux driver API
1005conventions.</para>
1006
1007 <orderedlist>
1008 <listitem>
1009 <para>Some typos in <constant>V4L2_FMT_FLAG</constant>
1010symbols were fixed. &v4l2-clip; was changed for compatibility with
1011v4l. (1999-08-30)</para>
1012 </listitem>
1013
1014 <listitem>
1015 <para><constant>V4L2_TUNER_SUB_LANG1</constant> was added.
1016(1999-09-05)</para>
1017 </listitem>
1018
1019 <listitem>
1020 <para>All ioctl() commands that used an integer argument now
1021take a pointer to an integer. Where it makes sense, ioctls will return
1022the actual new value in the integer pointed to by the argument, a
1023common convention in the V4L2 API. The affected ioctls are:
1024VIDIOC_PREVIEW, VIDIOC_STREAMON, VIDIOC_STREAMOFF, VIDIOC_S_FREQ,
1025VIDIOC_S_INPUT, VIDIOC_S_OUTPUT, VIDIOC_S_EFFECT. For example
1026<programlisting>
1027err = ioctl (fd, VIDIOC_XXX, V4L2_XXX);
1028</programlisting> becomes <programlisting>
1029int a = V4L2_XXX; err = ioctl(fd, VIDIOC_XXX, &amp;a);
1030</programlisting>
1031 </para>
1032 </listitem>
1033
1034 <listitem>
1035 <para>All the different get- and set-format commands were
1036swept into one &VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctl taking a union
1037and a type field selecting the union member as parameter. Purpose is to
1038simplify the API by eliminating several ioctls and to allow new and
1039driver private data streams without adding new ioctls.</para>
1040
1041 <para>This change obsoletes the following ioctls:
1042<constant>VIDIOC_S_INFMT</constant>,
1043<constant>VIDIOC_G_INFMT</constant>,
1044<constant>VIDIOC_S_OUTFMT</constant>,
1045<constant>VIDIOC_G_OUTFMT</constant>,
1046<constant>VIDIOC_S_VBIFMT</constant> and
1047<constant>VIDIOC_G_VBIFMT</constant>. The image format structure
1048<structname>v4l2_format</structname> was renamed to &v4l2-pix-format;,
1049while &v4l2-format; is now the envelopping structure for all format
1050negotiations.</para>
1051 </listitem>
1052
1053 <listitem>
1054 <para>Similar to the changes above, the
1055<constant>VIDIOC_G_PARM</constant> and
1056<constant>VIDIOC_S_PARM</constant> ioctls were merged with
1057<constant>VIDIOC_G_OUTPARM</constant> and
1058<constant>VIDIOC_S_OUTPARM</constant>. A
1059<structfield>type</structfield> field in the new &v4l2-streamparm;
1060selects the respective union member.</para>
1061
1062 <para>This change obsoletes the
1063<constant>VIDIOC_G_OUTPARM</constant> and
1064<constant>VIDIOC_S_OUTPARM</constant> ioctls.</para>
1065 </listitem>
1066
1067 <listitem>
1068 <para>Control enumeration was simplified, and two new
1069control flags were introduced and one dropped. The
1070<structfield>catname</structfield> field was replaced by a
1071<structfield>group</structfield> field.</para>
1072
1073 <para>Drivers can now flag unsupported and temporarily
1074unavailable controls with <constant>V4L2_CTRL_FLAG_DISABLED</constant>
1075and <constant>V4L2_CTRL_FLAG_GRABBED</constant> respectively. The
1076<structfield>group</structfield> name indicates a possibly narrower
1077classification than the <structfield>category</structfield>. In other
1078words, there may be multiple groups within a category. Controls within
1079a group would typically be drawn within a group box. Controls in
1080different categories might have a greater separation, or may even
1081appear in separate windows.</para>
1082 </listitem>
1083
1084 <listitem>
1085 <para>The &v4l2-buffer; <structfield>timestamp</structfield>
1086was changed to a 64 bit integer, containing the sampling or output
1087time of the frame in nanoseconds. Additionally timestamps will be in
1088absolute system time, not starting from zero at the beginning of a
1089stream. The data type name for timestamps is stamp_t, defined as a
1090signed 64-bit integer. Output devices should not send a buffer out
1091until the time in the timestamp field has arrived. I would like to
1092follow SGI's lead, and adopt a multimedia timestamping system like
1093their UST (Unadjusted System Time). See
1094http://reality.sgi.com/cpirazzi_engr/lg/time/intro.html. [This link is
1095no longer valid.] UST uses timestamps that are 64-bit signed integers
1096(not struct timeval's) and given in nanosecond units. The UST clock
1097starts at zero when the system is booted and runs continuously and
1098uniformly. It takes a little over 292 years for UST to overflow. There
1099is no way to set the UST clock. The regular Linux time-of-day clock
1100can be changed periodically, which would cause errors if it were being
1101used for timestamping a multimedia stream. A real UST style clock will
1102require some support in the kernel that is not there yet. But in
1103anticipation, I will change the timestamp field to a 64-bit integer,
1104and I will change the v4l2_masterclock_gettime() function (used only
1105by drivers) to return a 64-bit integer.</para>
1106 </listitem>
1107
1108 <listitem>
1109 <para>A <structfield>sequence</structfield> field was added
1110to &v4l2-buffer;. The <structfield>sequence</structfield> field counts
1111captured frames, it is ignored by output devices. When a capture
1112driver drops a frame, the sequence number of that frame is
1113skipped.</para>
1114 </listitem>
1115 </orderedlist>
1116 </section>
1117
1118 <section>
1119 <title>V4L2 Version 0.20 incremental changes</title>
1120 <!-- Version number didn't change anymore, reason unknown. -->
1121
1122 <para>1999-12-23: In &v4l2-vbi-format; the
1123<structfield>reserved1</structfield> field became
1124<structfield>offset</structfield>. Previously drivers were required to
1125clear the <structfield>reserved1</structfield> field.</para>
1126
1127 <para>2000-01-13: The
1128 <constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant> flag was added.</para>
1129
1130 <para>2000-07-31: The <filename>linux/poll.h</filename> header
1131is now included by <filename>videodev.h</filename> for compatibility
1132with the original <filename>videodev.h</filename> file.</para>
1133
1134 <para>2000-11-20: <constant>V4L2_TYPE_VBI_OUTPUT</constant> and
1135<constant>V4L2_PIX_FMT_Y41P</constant> were added.</para>
1136
1137 <para>2000-11-25: <constant>V4L2_TYPE_VBI_INPUT</constant> was
1138added.</para>
1139
1140 <para>2000-12-04: A couple typos in symbol names were fixed.</para>
1141
1142 <para>2001-01-18: To avoid namespace conflicts the
1143<constant>fourcc</constant> macro defined in the
1144<filename>videodev.h</filename> header file was renamed to
1145<constant>v4l2_fourcc</constant>.</para>
1146
1147 <para>2001-01-25: A possible driver-level compatibility problem
1148between the <filename>videodev.h</filename> file in Linux 2.4.0 and
1149the <filename>videodev.h</filename> file included in the
1150<filename>videodevX</filename> patch was fixed. Users of an earlier
1151version of <filename>videodevX</filename> on Linux 2.4.0 should
1152recompile their V4L and V4L2 drivers.</para>
1153
1154 <para>2001-01-26: A possible kernel-level incompatibility
1155between the <filename>videodev.h</filename> file in the
1156<filename>videodevX</filename> patch and the
1157<filename>videodev.h</filename> file in Linux 2.2.x with devfs patches
1158applied was fixed.</para>
1159
1160 <para>2001-03-02: Certain V4L ioctls which pass data in both
1161direction although they are defined with read-only parameter, did not
1162work correctly through the backward compatibility layer.
1163[Solution?]</para>
1164
1165 <para>2001-04-13: Big endian 16-bit RGB formats were added.</para>
1166
1167 <para>2001-09-17: New YUV formats and the &VIDIOC-G-FREQUENCY; and
1168&VIDIOC-S-FREQUENCY; ioctls were added. (The old
1169<constant>VIDIOC_G_FREQ</constant> and
1170<constant>VIDIOC_S_FREQ</constant> ioctls did not take multiple tuners
1171into account.)</para>
1172
1173 <para>2000-09-18: <constant>V4L2_BUF_TYPE_VBI</constant> was
1174added. This may <emphasis>break compatibility</emphasis> as the
1175&VIDIOC-G-FMT; and &VIDIOC-S-FMT; ioctls may fail now if the struct
1176<structname>v4l2_fmt</structname> <structfield>type</structfield>
1177field does not contain <constant>V4L2_BUF_TYPE_VBI</constant>. In the
1178documentation of the &v4l2-vbi-format;
1179<structfield>offset</structfield> field the ambiguous phrase "rising
1180edge" was changed to "leading edge".</para>
1181 </section>
1182
1183 <section>
1184 <title>V4L2 Version 0.20 2000-11-23</title>
1185
1186 <para>A number of changes were made to the raw VBI
1187interface.</para>
1188
1189 <orderedlist>
1190 <listitem>
1191 <para>Figures clarifying the line numbering scheme were
1192added to the V4L2 API specification. The
1193<structfield>start</structfield>[0] and
1194<structfield>start</structfield>[1] fields no longer count line
1195numbers beginning at zero. Rationale: a) The previous definition was
1196unclear. b) The <structfield>start</structfield>[] values are ordinal
1197numbers. c) There is no point in inventing a new line numbering
1198scheme. We now use line number as defined by ITU-R, period.
1199Compatibility: Add one to the start values. Applications depending on
1200the previous semantics may not function correctly.</para>
1201 </listitem>
1202
1203 <listitem>
1204 <para>The restriction "count[0] &gt; 0 and count[1] &gt; 0"
1205has been relaxed to "(count[0] + count[1]) &gt; 0". Rationale:
1206Drivers may allocate resources at scan line granularity and some data
1207services are transmitted only on the first field. The comment that
1208both <structfield>count</structfield> values will usually be equal is
1209misleading and pointless and has been removed. This change
1210<emphasis>breaks compatibility</emphasis> with earlier versions:
1211Drivers may return EINVAL, applications may not function
1212correctly.</para>
1213 </listitem>
1214
1215 <listitem>
1216 <para>Drivers are again permitted to return negative
1217(unknown) start values as proposed earlier. Why this feature was
1218dropped is unclear. This change may <emphasis>break
1219compatibility</emphasis> with applications depending on the start
1220values being positive. The use of <constant>EBUSY</constant> and
1221<constant>EINVAL</constant> error codes with the &VIDIOC-S-FMT; ioctl
1222was clarified. The &EBUSY; was finally documented, and the
1223<structfield>reserved2</structfield> field which was previously
1224mentioned only in the <filename>videodev.h</filename> header
1225file.</para>
1226 </listitem>
1227
1228 <listitem>
1229 <para>New buffer types
1230<constant>V4L2_TYPE_VBI_INPUT</constant> and
1231<constant>V4L2_TYPE_VBI_OUTPUT</constant> were added. The former is an
1232alias for the old <constant>V4L2_TYPE_VBI</constant>, the latter was
1233missing in the <filename>videodev.h</filename> file.</para>
1234 </listitem>
1235 </orderedlist>
1236 </section>
1237
1238 <section>
1239 <title>V4L2 Version 0.20 2002-07-25</title>
1240 <para>Added sliced VBI interface proposal.</para>
1241 </section>
1242
1243 <section>
1244 <title>V4L2 in Linux 2.5.46, 2002-10</title>
1245
1246 <para>Around October-November 2002, prior to an announced
1247feature freeze of Linux 2.5, the API was revised, drawing from
1248experience with V4L2 0.20. This unnamed version was finally merged
1249into Linux 2.5.46.</para>
1250
1251 <orderedlist>
1252 <listitem>
1253 <para>As specified in <xref linkend="related" />, drivers
1254must make related device functions available under all minor device
1255numbers.</para>
1256 </listitem>
1257
1258 <listitem>
1259 <para>The &func-open; function requires access mode
1260<constant>O_RDWR</constant> regardless of the device type. All V4L2
1261drivers exchanging data with applications must support the
1262<constant>O_NONBLOCK</constant> flag. The <constant>O_NOIO</constant>
1263flag, a V4L2 symbol which aliased the meaningless
1264<constant>O_TRUNC</constant> to indicate accesses without data
1265exchange (panel applications) was dropped. Drivers must stay in "panel
1266mode" until the application attempts to initiate a data exchange, see
1267<xref linkend="open" />.</para>
1268 </listitem>
1269
1270 <listitem>
1271 <para>The &v4l2-capability; changed dramatically. Note that
1272also the size of the structure changed, which is encoded in the ioctl
1273request code, thus older V4L2 devices will respond with an &EINVAL; to
1274the new &VIDIOC-QUERYCAP; ioctl.</para>
1275
1276 <para>There are new fields to identify the driver, a new RDS
1277device function <constant>V4L2_CAP_RDS_CAPTURE</constant>, the
1278<constant>V4L2_CAP_AUDIO</constant> flag indicates if the device has
1279any audio connectors, another I/O capability
1280<constant>V4L2_CAP_ASYNCIO</constant> can be flagged. In response to
1281these changes the <structfield>type</structfield> field became a bit
1282set and was merged into the <structfield>flags</structfield> field.
1283<constant>V4L2_FLAG_TUNER</constant> was renamed to
1284<constant>V4L2_CAP_TUNER</constant>,
1285<constant>V4L2_CAP_VIDEO_OVERLAY</constant> replaced
1286<constant>V4L2_FLAG_PREVIEW</constant> and
1287<constant>V4L2_CAP_VBI_CAPTURE</constant> and
1288<constant>V4L2_CAP_VBI_OUTPUT</constant> replaced
1289<constant>V4L2_FLAG_DATA_SERVICE</constant>.
1290<constant>V4L2_FLAG_READ</constant> and
1291<constant>V4L2_FLAG_WRITE</constant> were merged into
1292<constant>V4L2_CAP_READWRITE</constant>.</para>
1293
1294 <para>The redundant fields
1295<structfield>inputs</structfield>, <structfield>outputs</structfield>
1296and <structfield>audios</structfield> were removed. These properties
1297can be determined as described in <xref linkend="video" /> and <xref
1298linkend="audio" />.</para>
1299
1300 <para>The somewhat volatile and therefore barely useful
1301fields <structfield>maxwidth</structfield>,
1302<structfield>maxheight</structfield>,
1303<structfield>minwidth</structfield>,
1304<structfield>minheight</structfield>,
1305<structfield>maxframerate</structfield> were removed. This information
1306is available as described in <xref linkend="format" /> and
1307<xref linkend="standard" />.</para>
1308
1309 <para><constant>V4L2_FLAG_SELECT</constant> was removed. We
1310believe the select() function is important enough to require support
1311of it in all V4L2 drivers exchanging data with applications. The
1312redundant <constant>V4L2_FLAG_MONOCHROME</constant> flag was removed,
1313this information is available as described in <xref
1314 linkend="format" />.</para>
1315 </listitem>
1316
1317 <listitem>
1318 <para>In &v4l2-input; the
1319<structfield>assoc_audio</structfield> field and the
1320<structfield>capability</structfield> field and its only flag
1321<constant>V4L2_INPUT_CAP_AUDIO</constant> was replaced by the new
1322<structfield>audioset</structfield> field. Instead of linking one
1323video input to one audio input this field reports all audio inputs
1324this video input combines with.</para>
1325
1326 <para>New fields are <structfield>tuner</structfield>
1327(reversing the former link from tuners to video inputs),
1328<structfield>std</structfield> and
1329<structfield>status</structfield>.</para>
1330
1331 <para>Accordingly &v4l2-output; lost its
1332<structfield>capability</structfield> and
1333<structfield>assoc_audio</structfield> fields.
1334<structfield>audioset</structfield>,
1335<structfield>modulator</structfield> and
1336<structfield>std</structfield> where added instead.</para>
1337 </listitem>
1338
1339 <listitem>
1340 <para>The &v4l2-audio; field
1341<structfield>audio</structfield> was renamed to
1342<structfield>index</structfield>, for consistency with other
1343structures. A new capability flag
1344<constant>V4L2_AUDCAP_STEREO</constant> was added to indicated if the
1345audio input in question supports stereo sound.
1346<constant>V4L2_AUDCAP_EFFECTS</constant> and the corresponding
1347<constant>V4L2_AUDMODE</constant> flags where removed. This can be
1348easily implemented using controls. (However the same applies to AVL
1349which is still there.)</para>
1350
1351 <para>Again for consistency the &v4l2-audioout; field
1352<structfield>audio</structfield> was renamed to
1353<structfield>index</structfield>.</para>
1354 </listitem>
1355
1356 <listitem>
1357 <para>The &v4l2-tuner;
1358<structfield>input</structfield> field was replaced by an
1359<structfield>index</structfield> field, permitting devices with
1360multiple tuners. The link between video inputs and tuners is now
1361reversed, inputs point to their tuner. The
1362<structfield>std</structfield> substructure became a
1363simple set (more about this below) and moved into &v4l2-input;. A
1364<structfield>type</structfield> field was added.</para>
1365
1366 <para>Accordingly in &v4l2-modulator; the
1367<structfield>output</structfield> was replaced by an
1368<structfield>index</structfield> field.</para>
1369
1370 <para>In &v4l2-frequency; the
1371<structfield>port</structfield> field was replaced by a
1372<structfield>tuner</structfield> field containing the respective tuner
1373or modulator index number. A tuner <structfield>type</structfield>
1374field was added and the <structfield>reserved</structfield> field
1375became larger for future extensions (satellite tuners in
1376particular).</para>
1377 </listitem>
1378
1379 <listitem>
1380 <para>The idea of completely transparent video standards was
1381dropped. Experience showed that applications must be able to work with
1382video standards beyond presenting the user a menu. Instead of
1383enumerating supported standards with an ioctl applications can now
1384refer to standards by &v4l2-std-id; and symbols defined in the
1385<filename>videodev2.h</filename> header file. For details see <xref
1386 linkend="standard" />. The &VIDIOC-G-STD; and
1387&VIDIOC-S-STD; now take a pointer to this type as argument.
1388&VIDIOC-QUERYSTD; was added to autodetect the received standard, if
1389the hardware has this capability. In &v4l2-standard; an
1390<structfield>index</structfield> field was added for &VIDIOC-ENUMSTD;.
1391A &v4l2-std-id; field named <structfield>id</structfield> was added as
1392machine readable identifier, also replacing the
1393<structfield>transmission</structfield> field. The misleading
1394<structfield>framerate</structfield> field was renamed
1395to <structfield>frameperiod</structfield>. The now obsolete
1396<structfield>colorstandard</structfield> information, originally
1397needed to distguish between variations of standards, were
1398removed.</para>
1399
1400 <para>Struct <structname>v4l2_enumstd</structname> ceased to
1401be. &VIDIOC-ENUMSTD; now takes a pointer to a &v4l2-standard;
1402directly. The information which standards are supported by a
1403particular video input or output moved into &v4l2-input; and
1404&v4l2-output; fields named <structfield>std</structfield>,
1405respectively.</para>
1406 </listitem>
1407
1408 <listitem>
1409 <para>The &v4l2-queryctrl; fields
1410<structfield>category</structfield> and
1411<structfield>group</structfield> did not catch on and/or were not
1412implemented as expected and therefore removed.</para>
1413 </listitem>
1414
1415 <listitem>
1416 <para>The &VIDIOC-TRY-FMT; ioctl was added to negotiate data
1417formats as with &VIDIOC-S-FMT;, but without the overhead of
1418programming the hardware and regardless of I/O in progress.</para>
1419
1420 <para>In &v4l2-format; the <structfield>fmt</structfield>
1421union was extended to contain &v4l2-window;. All image format
1422negotiations are now possible with <constant>VIDIOC_G_FMT</constant>,
1423<constant>VIDIOC_S_FMT</constant> and
1424<constant>VIDIOC_TRY_FMT</constant>; ioctl. The
1425<constant>VIDIOC_G_WIN</constant> and
1426<constant>VIDIOC_S_WIN</constant> ioctls to prepare for a video
1427overlay were removed. The <structfield>type</structfield> field
1428changed to type &v4l2-buf-type; and the buffer type names changed as
1429follows.<informaltable>
1430 <tgroup cols="2">
1431 <thead>
1432 <row>
1433 <entry>Old defines</entry>
1434 <entry>&v4l2-buf-type;</entry>
1435 </row>
1436 </thead>
1437 <tbody valign="top">
1438 <row>
1439 <entry><constant>V4L2_BUF_TYPE_CAPTURE</constant></entry>
1440 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
1441 </row>
1442 <row>
1443 <entry><constant>V4L2_BUF_TYPE_CODECIN</constant></entry>
1444 <entry>Omitted for now</entry>
1445 </row>
1446 <row>
1447 <entry><constant>V4L2_BUF_TYPE_CODECOUT</constant></entry>
1448 <entry>Omitted for now</entry>
1449 </row>
1450 <row>
1451 <entry><constant>V4L2_BUF_TYPE_EFFECTSIN</constant></entry>
1452 <entry>Omitted for now</entry>
1453 </row>
1454 <row>
1455 <entry><constant>V4L2_BUF_TYPE_EFFECTSIN2</constant></entry>
1456 <entry>Omitted for now</entry>
1457 </row>
1458 <row>
1459 <entry><constant>V4L2_BUF_TYPE_EFFECTSOUT</constant></entry>
1460 <entry>Omitted for now</entry>
1461 </row>
1462 <row>
1463 <entry><constant>V4L2_BUF_TYPE_VIDEOOUT</constant></entry>
1464 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
1465 </row>
1466 <row>
1467 <entry><constant>-</constant></entry>
1468 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
1469 </row>
1470 <row>
1471 <entry><constant>-</constant></entry>
1472 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
1473 </row>
1474 <row>
1475 <entry><constant>-</constant></entry>
1476 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
1477 </row>
1478 <row>
1479 <entry><constant>-</constant></entry>
1480 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
1481 </row>
1482 <row>
1483 <entry><constant>-</constant></entry>
1484 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
1485 </row>
1486 <row>
1487 <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry>
1488 <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
1489 </row>
1490 </tbody>
1491 </tgroup>
1492 </informaltable></para>
1493 </listitem>
1494
1495 <listitem>
1496 <para>In &v4l2-fmtdesc; a &v4l2-buf-type; field named
1497<structfield>type</structfield> was added as in &v4l2-format;. The
1498<constant>VIDIOC_ENUM_FBUFFMT</constant> ioctl is no longer needed and
1499was removed. These calls can be replaced by &VIDIOC-ENUM-FMT; with
1500type <constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>.</para>
1501 </listitem>
1502
1503 <listitem>
1504 <para>In &v4l2-pix-format; the
1505<structfield>depth</structfield> field was removed, assuming
1506applications which recognize the format by its four-character-code
1507already know the color depth, and others do not care about it. The
1508same rationale lead to the removal of the
1509<constant>V4L2_FMT_FLAG_COMPRESSED</constant> flag. The
1510<constant>V4L2_FMT_FLAG_SWCONVECOMPRESSED</constant> flag was removed
1511because drivers are not supposed to convert images in kernel space. A
1512user library of conversion functions should be provided instead. The
1513<constant>V4L2_FMT_FLAG_BYTESPERLINE</constant> flag was redundant.
1514Applications can set the <structfield>bytesperline</structfield> field
1515to zero to get a reasonable default. Since the remaining flags were
1516replaced as well, the <structfield>flags</structfield> field itself
1517was removed.</para>
1518 <para>The interlace flags were replaced by a &v4l2-field;
1519value in a newly added <structfield>field</structfield>
1520field.<informaltable>
1521 <tgroup cols="2">
1522 <thead>
1523 <row>
1524 <entry>Old flag</entry>
1525 <entry>&v4l2-field;</entry>
1526 </row>
1527 </thead>
1528 <tbody valign="top">
1529 <row>
1530 <entry><constant>V4L2_FMT_FLAG_NOT_INTERLACED</constant></entry>
1531 <entry>?</entry>
1532 </row>
1533 <row>
1534 <entry><constant>V4L2_FMT_FLAG_INTERLACED</constant>
1535= <constant>V4L2_FMT_FLAG_COMBINED</constant></entry>
1536 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
1537 </row>
1538 <row>
1539 <entry><constant>V4L2_FMT_FLAG_TOPFIELD</constant>
1540= <constant>V4L2_FMT_FLAG_ODDFIELD</constant></entry>
1541 <entry><constant>V4L2_FIELD_TOP</constant></entry>
1542 </row>
1543 <row>
1544 <entry><constant>V4L2_FMT_FLAG_BOTFIELD</constant>
1545= <constant>V4L2_FMT_FLAG_EVENFIELD</constant></entry>
1546 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
1547 </row>
1548 <row>
1549 <entry><constant>-</constant></entry>
1550 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
1551 </row>
1552 <row>
1553 <entry><constant>-</constant></entry>
1554 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1555 </row>
1556 <row>
1557 <entry><constant>-</constant></entry>
1558 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1559 </row>
1560 </tbody>
1561 </tgroup>
1562 </informaltable></para>
1563
1564 <para>The color space flags were replaced by a
1565&v4l2-colorspace; value in a newly added
1566<structfield>colorspace</structfield> field, where one of
1567<constant>V4L2_COLORSPACE_SMPTE170M</constant>,
1568<constant>V4L2_COLORSPACE_BT878</constant>,
1569<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant> or
1570<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant> replaces
1571<constant>V4L2_FMT_CS_601YUV</constant>.</para>
1572 </listitem>
1573
1574 <listitem>
1575 <para>In &v4l2-requestbuffers; the
1576<structfield>type</structfield> field was properly defined as
1577&v4l2-buf-type;. Buffer types changed as mentioned above. A new
1578<structfield>memory</structfield> field of type &v4l2-memory; was
1579added to distinguish between I/O methods using buffers allocated
1580by the driver or the application. See <xref linkend="io" /> for
1581details.</para>
1582 </listitem>
1583
1584 <listitem>
1585 <para>In &v4l2-buffer; the <structfield>type</structfield>
1586field was properly defined as &v4l2-buf-type;. Buffer types changed as
1587mentioned above. A <structfield>field</structfield> field of type
1588&v4l2-field; was added to indicate if a buffer contains a top or
1589bottom field. The old field flags were removed. Since no unadjusted
1590system time clock was added to the kernel as planned, the
1591<structfield>timestamp</structfield> field changed back from type
1592stamp_t, an unsigned 64 bit integer expressing the sample time in
1593nanoseconds, to struct <structname>timeval</structname>. With the
1594addition of a second memory mapping method the
1595<structfield>offset</structfield> field moved into union
1596<structfield>m</structfield>, and a new
1597<structfield>memory</structfield> field of type &v4l2-memory; was
1598added to distinguish between I/O methods. See <xref linkend="io" />
1599for details.</para>
1600
1601 <para>The <constant>V4L2_BUF_REQ_CONTIG</constant>
1602flag was used by the V4L compatibility layer, after changes to this
1603code it was no longer needed. The
1604<constant>V4L2_BUF_ATTR_DEVICEMEM</constant> flag would indicate if
1605the buffer was indeed allocated in device memory rather than DMA-able
1606system memory. It was barely useful and so was removed.</para>
1607 </listitem>
1608
1609 <listitem>
1610 <para>In &v4l2-framebuffer; the
1611<structfield>base[3]</structfield> array anticipating double- and
1612triple-buffering in off-screen video memory, however without defining
1613a synchronization mechanism, was replaced by a single pointer. The
1614<constant>V4L2_FBUF_CAP_SCALEUP</constant> and
1615<constant>V4L2_FBUF_CAP_SCALEDOWN</constant> flags were removed.
1616Applications can determine this capability more accurately using the
1617new cropping and scaling interface. The
1618<constant>V4L2_FBUF_CAP_CLIPPING</constant> flag was replaced by
1619<constant>V4L2_FBUF_CAP_LIST_CLIPPING</constant> and
1620<constant>V4L2_FBUF_CAP_BITMAP_CLIPPING</constant>.</para>
1621 </listitem>
1622
1623 <listitem>
1624 <para>In &v4l2-clip; the <structfield>x</structfield>,
1625<structfield>y</structfield>, <structfield>width</structfield> and
1626<structfield>height</structfield> field moved into a
1627<structfield>c</structfield> substructure of type &v4l2-rect;. The
1628<structfield>x</structfield> and <structfield>y</structfield> fields
1629were renamed to <structfield>left</structfield> and
1630<structfield>top</structfield>, &ie; offsets to a context dependent
1631origin.</para>
1632 </listitem>
1633
1634 <listitem>
1635 <para>In &v4l2-window; the <structfield>x</structfield>,
1636<structfield>y</structfield>, <structfield>width</structfield> and
1637<structfield>height</structfield> field moved into a
1638<structfield>w</structfield> substructure as above. A
1639<structfield>field</structfield> field of type %v4l2-field; was added
1640to distinguish between field and frame (interlaced) overlay.</para>
1641 </listitem>
1642
1643 <listitem>
1644 <para>The digital zoom interface, including struct
1645<structname>v4l2_zoomcap</structname>, struct
1646<structname>v4l2_zoom</structname>,
1647<constant>V4L2_ZOOM_NONCAP</constant> and
1648<constant>V4L2_ZOOM_WHILESTREAMING</constant> was replaced by a new
1649cropping and scaling interface. The previously unused struct
1650<structname>v4l2_cropcap</structname> and
1651<structname>v4l2_crop</structname> where redefined for this purpose.
1652See <xref linkend="crop" /> for details.</para>
1653 </listitem>
1654
1655 <listitem>
1656 <para>In &v4l2-vbi-format; the
1657<structfield>SAMPLE_FORMAT</structfield> field now contains a
1658four-character-code as used to identify video image formats and
1659<constant>V4L2_PIX_FMT_GREY</constant> replaces the
1660<constant>V4L2_VBI_SF_UBYTE</constant> define. The
1661<structfield>reserved</structfield> field was extended.</para>
1662 </listitem>
1663
1664 <listitem>
1665 <para>In &v4l2-captureparm; the type of the
1666<structfield>timeperframe</structfield> field changed from unsigned
1667long to &v4l2-fract;. This allows the accurate expression of multiples
1668of the NTSC-M frame rate 30000 / 1001. A new field
1669<structfield>readbuffers</structfield> was added to control the driver
1670behaviour in read I/O mode.</para>
1671
1672 <para>Similar changes were made to &v4l2-outputparm;.</para>
1673 </listitem>
1674
1675 <listitem>
1676 <para>The struct <structname>v4l2_performance</structname>
1677and <constant>VIDIOC_G_PERF</constant> ioctl were dropped. Except when
1678using the <link linkend="rw">read/write I/O method</link>, which is
1679limited anyway, this information is already available to
1680applications.</para>
1681 </listitem>
1682
1683 <listitem>
1684 <para>The example transformation from RGB to YCbCr color
1685space in the old V4L2 documentation was inaccurate, this has been
1686corrected in <xref linkend="pixfmt" />.<!-- 0.5670G should be
16870.587, and 127/112 != 255/224 --></para>
1688 </listitem>
1689 </orderedlist>
1690 </section>
1691
1692 <section>
1693 <title>V4L2 2003-06-19</title>
1694
1695 <orderedlist>
1696 <listitem>
1697 <para>A new capability flag
1698<constant>V4L2_CAP_RADIO</constant> was added for radio devices. Prior
1699to this change radio devices would identify solely by having exactly one
1700tuner whose type field reads <constant>V4L2_TUNER_RADIO</constant>.</para>
1701 </listitem>
1702
1703 <listitem>
1704 <para>An optional driver access priority mechanism was
1705added, see <xref linkend="app-pri" /> for details.</para>
1706 </listitem>
1707
1708 <listitem>
1709 <para>The audio input and output interface was found to be
1710incomplete.</para>
1711 <para>Previously the &VIDIOC-G-AUDIO;
1712ioctl would enumerate the available audio inputs. An ioctl to
1713determine the current audio input, if more than one combines with the
1714current video input, did not exist. So
1715<constant>VIDIOC_G_AUDIO</constant> was renamed to
1716<constant>VIDIOC_G_AUDIO_OLD</constant>, this ioctl will be removed in
1717the future. The &VIDIOC-ENUMAUDIO; ioctl was added to enumerate
1718audio inputs, while &VIDIOC-G-AUDIO; now reports the current audio
1719input.</para>
1720 <para>The same changes were made to &VIDIOC-G-AUDOUT; and
1721&VIDIOC-ENUMAUDOUT;.</para>
1722 <para>Until further the "videodev" module will automatically
1723translate between the old and new ioctls, but drivers and applications
1724must be updated to successfully compile again.</para>
1725 </listitem>
1726
1727 <listitem>
1728 <para>The &VIDIOC-OVERLAY; ioctl was incorrectly defined with
1729write-read parameter. It was changed to write-only, while the write-read
1730version was renamed to <constant>VIDIOC_OVERLAY_OLD</constant>. The old
1731ioctl will be removed in the future. Until further the "videodev"
1732kernel module will automatically translate to the new version, so drivers
1733must be recompiled, but not applications.</para>
1734 </listitem>
1735
1736 <listitem>
1737 <para><xref linkend="overlay" /> incorrectly stated that
1738clipping rectangles define regions where the video can be seen.
1739Correct is that clipping rectangles define regions where
1740<emphasis>no</emphasis> video shall be displayed and so the graphics
1741surface can be seen.</para>
1742 </listitem>
1743
1744 <listitem>
1745 <para>The &VIDIOC-S-PARM; and &VIDIOC-S-CTRL; ioctls were
1746defined with write-only parameter, inconsistent with other ioctls
1747modifying their argument. They were changed to write-read, while a
1748<constant>_OLD</constant> suffix was added to the write-only versions.
1749The old ioctls will be removed in the future. Drivers and
1750applications assuming a constant parameter need an update.</para>
1751 </listitem>
1752 </orderedlist>
1753 </section>
1754
1755 <section>
1756 <title>V4L2 2003-11-05</title>
1757 <orderedlist>
1758 <listitem>
1759 <para>In <xref linkend="pixfmt-rgb" /> the following pixel
1760formats were incorrectly transferred from Bill Dirks' V4L2
1761specification. Descriptions below refer to bytes in memory, in
1762ascending address order.<informaltable>
1763 <tgroup cols="3">
1764 <thead>
1765 <row>
1766 <entry>Symbol</entry>
1767 <entry>In this document prior to revision
17680.5</entry>
1769 <entry>Corrected</entry>
1770 </row>
1771 </thead>
1772 <tbody valign="top">
1773 <row>
1774 <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
1775 <entry>B, G, R</entry>
1776 <entry>R, G, B</entry>
1777 </row>
1778 <row>
1779 <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
1780 <entry>R, G, B</entry>
1781 <entry>B, G, R</entry>
1782 </row>
1783 <row>
1784 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
1785 <entry>B, G, R, X</entry>
1786 <entry>R, G, B, X</entry>
1787 </row>
1788 <row>
1789 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
1790 <entry>R, G, B, X</entry>
1791 <entry>B, G, R, X</entry>
1792 </row>
1793 </tbody>
1794 </tgroup>
1795 </informaltable> The
1796<constant>V4L2_PIX_FMT_BGR24</constant> example was always
1797correct.</para>
1798 <para>In <xref linkend="v4l-image-properties" /> the mapping
1799of the V4L <constant>VIDEO_PALETTE_RGB24</constant> and
1800<constant>VIDEO_PALETTE_RGB32</constant> formats to V4L2 pixel formats
1801was accordingly corrected.</para>
1802 </listitem>
1803
1804 <listitem>
1805 <para>Unrelated to the fixes above, drivers may still
1806interpret some V4L2 RGB pixel formats differently. These issues have
1807yet to be addressed, for details see <xref
1808 linkend="pixfmt-rgb" />.</para>
1809 </listitem>
1810 </orderedlist>
1811 </section>
1812
1813 <section>
1814 <title>V4L2 in Linux 2.6.6, 2004-05-09</title>
1815 <orderedlist>
1816 <listitem>
1817 <para>The &VIDIOC-CROPCAP; ioctl was incorrectly defined
1818with read-only parameter. It is now defined as write-read ioctl, while
1819the read-only version was renamed to
1820<constant>VIDIOC_CROPCAP_OLD</constant>. The old ioctl will be removed
1821in the future.</para>
1822 </listitem>
1823 </orderedlist>
1824 </section>
1825
1826 <section>
1827 <title>V4L2 in Linux 2.6.8</title>
1828 <orderedlist>
1829 <listitem>
1830 <para>A new field <structfield>input</structfield> (former
1831<structfield>reserved[0]</structfield>) was added to the &v4l2-buffer;
1832structure. Purpose of this field is to alternate between video inputs
1833(&eg; cameras) in step with the video capturing process. This function
1834must be enabled with the new <constant>V4L2_BUF_FLAG_INPUT</constant>
1835flag. The <structfield>flags</structfield> field is no longer
1836read-only.</para>
1837 </listitem>
1838 </orderedlist>
1839 </section>
1840
1841 <section>
1842 <title>V4L2 spec erratum 2004-08-01</title>
1843
1844 <orderedlist>
1845 <listitem>
1846 <para>The return value of the
1847<xref linkend="func-open" /> function was incorrectly documented.</para>
1848 </listitem>
1849
1850 <listitem>
1851 <para>Audio output ioctls end in -AUDOUT, not -AUDIOOUT.</para>
1852 </listitem>
1853
1854 <listitem>
1855 <para>In the Current Audio Input example the
1856<constant>VIDIOC_G_AUDIO</constant> ioctl took the wrong
1857argument.</para>
1858 </listitem>
1859
1860 <listitem>
1861 <para>The documentation of the &VIDIOC-QBUF; and
1862&VIDIOC-DQBUF; ioctls did not mention the &v4l2-buffer;
1863<structfield>memory</structfield> field. It was also missing from
1864examples. Also on the <constant>VIDIOC_DQBUF</constant> page the &EIO;
1865was not documented.</para>
1866 </listitem>
1867 </orderedlist>
1868 </section>
1869
1870 <section>
1871 <title>V4L2 in Linux 2.6.14</title>
1872 <orderedlist>
1873 <listitem>
1874 <para>A new sliced VBI interface was added. It is documented
1875in <xref linkend="sliced" /> and replaces the interface first
1876proposed in V4L2 specification 0.8.</para>
1877 </listitem>
1878 </orderedlist>
1879 </section>
1880
1881 <section>
1882 <title>V4L2 in Linux 2.6.15</title>
1883 <orderedlist>
1884 <listitem>
1885 <para>The &VIDIOC-LOG-STATUS; ioctl was added.</para>
1886 </listitem>
1887
1888 <listitem>
1889 <para>New video standards
1890<constant>V4L2_STD_NTSC_443</constant>,
1891<constant>V4L2_STD_SECAM_LC</constant>,
1892<constant>V4L2_STD_SECAM_DK</constant> (a set of SECAM D, K and K1),
1893and <constant>V4L2_STD_ATSC</constant> (a set of
1894<constant>V4L2_STD_ATSC_8_VSB</constant> and
1895<constant>V4L2_STD_ATSC_16_VSB</constant>) were defined. Note the
1896<constant>V4L2_STD_525_60</constant> set now includes
1897<constant>V4L2_STD_NTSC_443</constant>. See also <xref
1898 linkend="v4l2-std-id" />.</para>
1899 </listitem>
1900
1901 <listitem>
1902 <para>The <constant>VIDIOC_G_COMP</constant> and
1903<constant>VIDIOC_S_COMP</constant> ioctl were renamed to
1904<constant>VIDIOC_G_MPEGCOMP</constant> and
1905<constant>VIDIOC_S_MPEGCOMP</constant> respectively. Their argument
1906was replaced by a struct
1907<structname>v4l2_mpeg_compression</structname> pointer. (The
1908<constant>VIDIOC_G_MPEGCOMP</constant> and
1909<constant>VIDIOC_S_MPEGCOMP</constant> ioctls where removed in Linux
19102.6.25.)</para>
1911 </listitem>
1912 </orderedlist>
1913 </section>
1914
1915 <section>
1916 <title>V4L2 spec erratum 2005-11-27</title>
1917 <para>The capture example in <xref linkend="capture-example" />
1918called the &VIDIOC-S-CROP; ioctl without checking if cropping is
1919supported. In the video standard selection example in
1920<xref linkend="standard" /> the &VIDIOC-S-STD; call used the wrong
1921argument type.</para>
1922 </section>
1923
1924 <section>
1925 <title>V4L2 spec erratum 2006-01-10</title>
1926 <orderedlist>
1927 <listitem>
1928 <para>The <constant>V4L2_IN_ST_COLOR_KILL</constant> flag in
1929&v4l2-input; not only indicates if the color killer is enabled, but
1930also if it is active. (The color killer disables color decoding when
1931it detects no color in the video signal to improve the image
1932quality.)</para>
1933 </listitem>
1934
1935 <listitem>
1936 <para>&VIDIOC-S-PARM; is a write-read ioctl, not write-only as
1937stated on its reference page. The ioctl changed in 2003 as noted above.</para>
1938 </listitem>
1939 </orderedlist>
1940 </section>
1941
1942 <section>
1943 <title>V4L2 spec erratum 2006-02-03</title>
1944 <orderedlist>
1945 <listitem>
1946 <para>In &v4l2-captureparm; and &v4l2-outputparm; the
1947<structfield>timeperframe</structfield> field gives the time in
1948seconds, not microseconds.</para>
1949 </listitem>
1950 </orderedlist>
1951 </section>
1952
1953 <section>
1954 <title>V4L2 spec erratum 2006-02-04</title>
1955 <orderedlist>
1956 <listitem>
1957 <para>The <structfield>clips</structfield> field in
1958&v4l2-window; must point to an array of &v4l2-clip;, not a linked
1959list, because drivers ignore the struct
1960<structname>v4l2_clip</structname>.<structfield>next</structfield>
1961pointer.</para>
1962 </listitem>
1963 </orderedlist>
1964 </section>
1965
1966 <section>
1967 <title>V4L2 in Linux 2.6.17</title>
1968 <orderedlist>
1969 <listitem>
1970 <para>New video standard macros were added:
1971<constant>V4L2_STD_NTSC_M_KR</constant> (NTSC M South Korea), and the
1972sets <constant>V4L2_STD_MN</constant>,
1973<constant>V4L2_STD_B</constant>, <constant>V4L2_STD_GH</constant> and
1974<constant>V4L2_STD_DK</constant>. The
1975<constant>V4L2_STD_NTSC</constant> and
1976<constant>V4L2_STD_SECAM</constant> sets now include
1977<constant>V4L2_STD_NTSC_M_KR</constant> and
1978<constant>V4L2_STD_SECAM_LC</constant> respectively.</para>
1979 </listitem>
1980
1981 <listitem>
1982 <para>A new <constant>V4L2_TUNER_MODE_LANG1_LANG2</constant>
1983was defined to record both languages of a bilingual program. The
1984use of <constant>V4L2_TUNER_MODE_STEREO</constant> for this purpose
1985is deprecated now. See the &VIDIOC-G-TUNER; section for
1986details.</para>
1987 </listitem>
1988 </orderedlist>
1989 </section>
1990
1991 <section>
1992 <title>V4L2 spec erratum 2006-09-23 (Draft 0.15)</title>
1993 <orderedlist>
1994 <listitem>
1995 <para>In various places
1996<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> and
1997<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant> of the sliced VBI
1998interface were not mentioned along with other buffer types.</para>
1999 </listitem>
2000
2001 <listitem>
2002 <para>In <xref linkend="vidioc-g-audio" /> it was clarified
2003that the &v4l2-audio; <structfield>mode</structfield> field is a flags
2004field.</para>
2005 </listitem>
2006
2007 <listitem>
2008 <para><xref linkend="vidioc-querycap" /> did not mention the
2009sliced VBI and radio capability flags.</para>
2010 </listitem>
2011
2012 <listitem>
2013 <para>In <xref linkend="vidioc-g-frequency" /> it was
2014clarified that applications must initialize the tuner
2015<structfield>type</structfield> field of &v4l2-frequency; before
2016calling &VIDIOC-S-FREQUENCY;.</para>
2017 </listitem>
2018
2019 <listitem>
2020 <para>The <structfield>reserved</structfield> array
2021in &v4l2-requestbuffers; has 2 elements, not 32.</para>
2022 </listitem>
2023
2024 <listitem>
2025 <para>In <xref linkend="output" /> and <xref
2026 linkend="raw-vbi" /> the device file names
2027<filename>/dev/vout</filename> which never caught on were replaced
2028by <filename>/dev/video</filename>.</para>
2029 </listitem>
2030
2031 <listitem>
2032 <para>With Linux 2.6.15 the possible range for VBI device minor
2033numbers was extended from 224-239 to 224-255. Accordingly device file names
2034<filename>/dev/vbi0</filename> to <filename>/dev/vbi31</filename> are
2035possible now.</para>
2036 </listitem>
2037 </orderedlist>
2038 </section>
2039
2040 <section>
2041 <title>V4L2 in Linux 2.6.18</title>
2042 <orderedlist>
2043 <listitem>
2044 <para>New ioctls &VIDIOC-G-EXT-CTRLS;, &VIDIOC-S-EXT-CTRLS;
2045and &VIDIOC-TRY-EXT-CTRLS; were added, a flag to skip unsupported
2046controls with &VIDIOC-QUERYCTRL;, new control types
2047<constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
2048<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant> (<xref
2049 linkend="v4l2-ctrl-type" />), and new control flags
2050<constant>V4L2_CTRL_FLAG_READ_ONLY</constant>,
2051<constant>V4L2_CTRL_FLAG_UPDATE</constant>,
2052<constant>V4L2_CTRL_FLAG_INACTIVE</constant> and
2053<constant>V4L2_CTRL_FLAG_SLIDER</constant> (<xref
2054 linkend="control-flags" />). See <xref
2055 linkend="extended-controls" /> for details.</para>
2056 </listitem>
2057 </orderedlist>
2058 </section>
2059
2060 <section>
2061 <title>V4L2 in Linux 2.6.19</title>
2062 <orderedlist>
2063 <listitem>
2064 <para>In &v4l2-sliced-vbi-cap; a buffer type field was added
2065replacing a reserved field. Note on architectures where the size of
2066enum types differs from int types the size of the structure changed.
2067The &VIDIOC-G-SLICED-VBI-CAP; ioctl was redefined from being read-only
2068to write-read. Applications must initialize the type field and clear
2069the reserved fields now. These changes may <emphasis>break the
2070compatibility</emphasis> with older drivers and applications.</para>
2071 </listitem>
2072
2073 <listitem>
2074 <para>The ioctls &VIDIOC-ENUM-FRAMESIZES; and
2075&VIDIOC-ENUM-FRAMEINTERVALS; were added.</para>
2076 </listitem>
2077
2078 <listitem>
2079 <para>A new pixel format <constant>V4L2_PIX_FMT_RGB444</constant> (<xref
2080linkend="rgb-formats" />) was added.</para>
2081 </listitem>
2082 </orderedlist>
2083 </section>
2084
2085 <section>
2086 <title>V4L2 spec erratum 2006-10-12 (Draft 0.17)</title>
2087 <orderedlist>
2088 <listitem>
2089 <para><constant>V4L2_PIX_FMT_HM12</constant> (<xref
2090linkend="reserved-formats" />) is a YUV 4:2:0, not 4:2:2 format.</para>
2091 </listitem>
2092 </orderedlist>
2093 </section>
2094
2095 <section>
2096 <title>V4L2 in Linux 2.6.21</title>
2097 <orderedlist>
2098 <listitem>
2099 <para>The <filename>videodev2.h</filename> header file is
2100now dual licensed under GNU General Public License version two or
2101later, and under a 3-clause BSD-style license.</para>
2102 </listitem>
2103 </orderedlist>
2104 </section>
2105
2106 <section>
2107 <title>V4L2 in Linux 2.6.22</title>
2108 <orderedlist>
2109 <listitem>
2110 <para>Two new field orders
2111 <constant>V4L2_FIELD_INTERLACED_TB</constant> and
2112 <constant>V4L2_FIELD_INTERLACED_BT</constant> were
2113 added. See <xref linkend="v4l2-field" /> for details.</para>
2114 </listitem>
2115
2116 <listitem>
2117 <para>Three new clipping/blending methods with a global or
2118straight or inverted local alpha value were added to the video overlay
2119interface. See the description of the &VIDIOC-G-FBUF; and
2120&VIDIOC-S-FBUF; ioctls for details.</para>
2121 <para>A new <structfield>global_alpha</structfield> field
2122was added to <link
2123linkend="v4l2-window"><structname>v4l2_window</structname></link>,
2124extending the structure. This may <emphasis>break
2125compatibility</emphasis> with applications using a struct
2126<structname>v4l2_window</structname> directly. However the <link
2127linkend="vidioc-g-fmt">VIDIOC_G/S/TRY_FMT</link> ioctls, which take a
2128pointer to a <link linkend="v4l2-format">v4l2_format</link> parent
2129structure with padding bytes at the end, are not affected.</para>
2130 </listitem>
2131
2132 <listitem>
2133 <para>The format of the <structfield>chromakey</structfield>
2134field in &v4l2-window; changed from "host order RGB32" to a pixel
2135value in the same format as the framebuffer. This may <emphasis>break
2136compatibility</emphasis> with existing applications. Drivers
2137supporting the "host order RGB32" format are not known.</para>
2138 </listitem>
2139
2140 </orderedlist>
2141 </section>
2142
2143 <section>
2144 <title>V4L2 in Linux 2.6.24</title>
2145 <orderedlist>
2146 <listitem>
2147 <para>The pixel formats
2148<constant>V4L2_PIX_FMT_PAL8</constant>,
2149<constant>V4L2_PIX_FMT_YUV444</constant>,
2150<constant>V4L2_PIX_FMT_YUV555</constant>,
2151<constant>V4L2_PIX_FMT_YUV565</constant> and
2152<constant>V4L2_PIX_FMT_YUV32</constant> were added.</para>
2153 </listitem>
2154 </orderedlist>
2155 </section>
2156
2157 <section>
2158 <title>V4L2 in Linux 2.6.25</title>
2159 <orderedlist>
2160 <listitem>
2161 <para>The pixel formats <link linkend="V4L2-PIX-FMT-Y16">
2162<constant>V4L2_PIX_FMT_Y16</constant></link> and <link
2163linkend="V4L2-PIX-FMT-SBGGR16">
2164<constant>V4L2_PIX_FMT_SBGGR16</constant></link> were added.</para>
2165 </listitem>
2166 <listitem>
2167 <para>New <link linkend="control">controls</link>
2168<constant>V4L2_CID_POWER_LINE_FREQUENCY</constant>,
2169<constant>V4L2_CID_HUE_AUTO</constant>,
2170<constant>V4L2_CID_WHITE_BALANCE_TEMPERATURE</constant>,
2171<constant>V4L2_CID_SHARPNESS</constant> and
2172<constant>V4L2_CID_BACKLIGHT_COMPENSATION</constant> were added. The
2173controls <constant>V4L2_CID_BLACK_LEVEL</constant>,
2174<constant>V4L2_CID_WHITENESS</constant>,
2175<constant>V4L2_CID_HCENTER</constant> and
2176<constant>V4L2_CID_VCENTER</constant> were deprecated.
2177</para>
2178 </listitem>
2179 <listitem>
2180 <para>A <link linkend="camera-controls">Camera controls
2181class</link> was added, with the new controls
2182<constant>V4L2_CID_EXPOSURE_AUTO</constant>,
2183<constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>,
2184<constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>,
2185<constant>V4L2_CID_PAN_RELATIVE</constant>,
2186<constant>V4L2_CID_TILT_RELATIVE</constant>,
2187<constant>V4L2_CID_PAN_RESET</constant>,
2188<constant>V4L2_CID_TILT_RESET</constant>,
2189<constant>V4L2_CID_PAN_ABSOLUTE</constant>,
2190<constant>V4L2_CID_TILT_ABSOLUTE</constant>,
2191<constant>V4L2_CID_FOCUS_ABSOLUTE</constant>,
2192<constant>V4L2_CID_FOCUS_RELATIVE</constant> and
2193<constant>V4L2_CID_FOCUS_AUTO</constant>.</para>
2194 </listitem>
2195 <listitem>
2196 <para>The <constant>VIDIOC_G_MPEGCOMP</constant> and
2197<constant>VIDIOC_S_MPEGCOMP</constant> ioctls, which were superseded
2198by the <link linkend="extended-controls">extended controls</link>
2199interface in Linux 2.6.18, where finally removed from the
2200<filename>videodev2.h</filename> header file.</para>
2201 </listitem>
2202 </orderedlist>
2203 </section>
2204
2205 <section>
2206 <title>V4L2 in Linux 2.6.26</title>
2207 <orderedlist>
2208 <listitem>
2209 <para>The pixel formats
2210<constant>V4L2_PIX_FMT_Y16</constant> and
2211<constant>V4L2_PIX_FMT_SBGGR16</constant> were added.</para>
2212 </listitem>
2213 <listitem>
2214 <para>Added user controls
2215<constant>V4L2_CID_CHROMA_AGC</constant> and
2216<constant>V4L2_CID_COLOR_KILLER</constant>.</para>
2217 </listitem>
2218 </orderedlist>
2219 </section>
2220
2221 <section>
2222 <title>V4L2 in Linux 2.6.27</title>
2223 <orderedlist>
2224 <listitem>
2225 <para>The &VIDIOC-S-HW-FREQ-SEEK; ioctl and the
2226<constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability were added.</para>
2227 </listitem>
2228 <listitem>
2229 <para>The pixel formats
2230<constant>V4L2_PIX_FMT_YVYU</constant>,
2231<constant>V4L2_PIX_FMT_PCA501</constant>,
2232<constant>V4L2_PIX_FMT_PCA505</constant>,
2233<constant>V4L2_PIX_FMT_PCA508</constant>,
2234<constant>V4L2_PIX_FMT_PCA561</constant>,
2235<constant>V4L2_PIX_FMT_SGBRG8</constant>,
2236<constant>V4L2_PIX_FMT_PAC207</constant> and
2237<constant>V4L2_PIX_FMT_PJPG</constant> were added.</para>
2238 </listitem>
2239 </orderedlist>
2240 </section>
2241
2242 <section>
2243 <title>V4L2 in Linux 2.6.28</title>
2244 <orderedlist>
2245 <listitem>
2246 <para>Added <constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant> and
2247<constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant> MPEG audio encodings.</para>
2248 </listitem>
2249 <listitem>
2250 <para>Added <constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant> MPEG
2251video encoding.</para>
2252 </listitem>
2253 <listitem>
2254 <para>The pixel formats
2255<constant>V4L2_PIX_FMT_SGRBG10</constant> and
2256<constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant> were added.</para>
2257 </listitem>
2258 </orderedlist>
2259 </section>
2260
2261 <section>
2262 <title>V4L2 in Linux 2.6.29</title>
2263 <orderedlist>
2264 <listitem>
2265 <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed
2266to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT;
2267was introduced in its place. The old struct <structname>v4l2_chip_ident</structname>
2268was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para>
2269 </listitem>
2270 <listitem>
2271 <para>The pixel formats
2272<constant>V4L2_PIX_FMT_VYUY</constant>,
2273<constant>V4L2_PIX_FMT_NV16</constant> and
2274<constant>V4L2_PIX_FMT_NV61</constant> were added.</para>
2275 </listitem>
2276 <listitem>
2277 <para>Added camera controls
2278<constant>V4L2_CID_ZOOM_ABSOLUTE</constant>,
2279<constant>V4L2_CID_ZOOM_RELATIVE</constant>,
2280<constant>V4L2_CID_ZOOM_CONTINUOUS</constant> and
2281<constant>V4L2_CID_PRIVACY</constant>.</para>
2282 </listitem>
2283 </orderedlist>
2284 </section>
2285 <section>
2286 <title>V4L2 in Linux 2.6.30</title>
2287 <orderedlist>
2288 <listitem>
2289 <para>New control flag <constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant> was added.</para>
2290 </listitem>
2291 <listitem>
2292 <para>New control <constant>V4L2_CID_COLORFX</constant> was added.</para>
2293 </listitem>
2294 </orderedlist>
2295 </section>
2296 <section>
2297 <title>V4L2 in Linux 2.6.32</title>
2298 <orderedlist>
2299 <listitem>
2300 <para>In order to be easier to compare a V4L2 API and a kernel
2301version, now V4L2 API is numbered using the Linux Kernel version numeration.</para>
2302 </listitem>
2303 <listitem>
2304 <para>Finalized the RDS capture API. See <xref linkend="rds" /> for
2305more information.</para>
2306 </listitem>
2307 <listitem>
2308 <para>Added new capabilities for modulators and RDS encoders.</para>
2309 </listitem>
2310 <listitem>
2311 <para>Add description for libv4l API.</para>
2312 </listitem>
2313 <listitem>
2314 <para>Added support for string controls via new type <constant>V4L2_CTRL_TYPE_STRING</constant>.</para>
2315 </listitem>
2316 <listitem>
2317 <para>Added <constant>V4L2_CID_BAND_STOP_FILTER</constant> documentation.</para>
2318 </listitem>
2319 <listitem>
2320 <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para>
2321 </listitem>
2322 <listitem>
2323 <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para>
2324 </listitem>
2325 </orderedlist>
2326 </section>
2327 </section>
2328
2329 <section id="other">
2330 <title>Relation of V4L2 to other Linux multimedia APIs</title>
2331
2332 <section id="xvideo">
2333 <title>X Video Extension</title>
2334
2335 <para>The X Video Extension (abbreviated XVideo or just Xv) is
2336an extension of the X Window system, implemented for example by the
2337XFree86 project. Its scope is similar to V4L2, an API to video capture
2338and output devices for X clients. Xv allows applications to display
2339live video in a window, send window contents to a TV output, and
2340capture or output still images in XPixmaps<footnote>
2341 <para>This is not implemented in XFree86.</para>
2342 </footnote>. With their implementation XFree86 makes the
2343extension available across many operating systems and
2344architectures.</para>
2345
2346 <para>Because the driver is embedded into the X server Xv has a
2347number of advantages over the V4L2 <link linkend="overlay">video
2348overlay interface</link>. The driver can easily determine the overlay
2349target, &ie; visible graphics memory or off-screen buffers for a
2350destructive overlay. It can program the RAMDAC for a non-destructive
2351overlay, scaling or color-keying, or the clipping functions of the
2352video capture hardware, always in sync with drawing operations or
2353windows moving or changing their stacking order.</para>
2354
2355 <para>To combine the advantages of Xv and V4L a special Xv
2356driver exists in XFree86 and XOrg, just programming any overlay capable
2357Video4Linux device it finds. To enable it
2358<filename>/etc/X11/XF86Config</filename> must contain these lines:</para>
2359 <para><screen>
2360Section "Module"
2361 Load "v4l"
2362EndSection</screen></para>
2363
2364 <para>As of XFree86 4.2 this driver still supports only V4L
2365ioctls, however it should work just fine with all V4L2 devices through
2366the V4L2 backward-compatibility layer. Since V4L2 permits multiple
2367opens it is possible (if supported by the V4L2 driver) to capture
2368video while an X client requested video overlay. Restrictions of
2369simultaneous capturing and overlay are discussed in <xref
2370 linkend="overlay" /> apply.</para>
2371
2372 <para>Only marginally related to V4L2, XFree86 extended Xv to
2373support hardware YUV to RGB conversion and scaling for faster video
2374playback, and added an interface to MPEG-2 decoding hardware. This API
2375is useful to display images captured with V4L2 devices.</para>
2376 </section>
2377
2378 <section>
2379 <title>Digital Video</title>
2380
2381 <para>V4L2 does not support digital terrestrial, cable or
2382satellite broadcast. A separate project aiming at digital receivers
2383exists. You can find its homepage at <ulink
2384url="http://linuxtv.org">http://linuxtv.org</ulink>. The Linux DVB API
2385has no connection to the V4L2 API except that drivers for hybrid
2386hardware may support both.</para>
2387 </section>
2388
2389 <section>
2390 <title>Audio Interfaces</title>
2391
2392 <para>[to do - OSS/ALSA]</para>
2393 </section>
2394 </section>
2395
2396 <section id="experimental">
2397 <title>Experimental API Elements</title>
2398
2399 <para>The following V4L2 API elements are currently experimental
2400and may change in the future.</para>
2401
2402 <itemizedlist>
2403 <listitem>
2404 <para>Video Output Overlay (OSD) Interface, <xref
2405 linkend="osd" />.</para>
2406 </listitem>
2407 <listitem>
2408 <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>,
2409 &v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para>
2410 </listitem>
2411 <listitem>
2412 <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>,
2413&VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para>
2414 </listitem>
2415 <listitem>
2416 <para>&VIDIOC-ENUM-FRAMESIZES; and
2417&VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para>
2418 </listitem>
2419 <listitem>
2420 <para>&VIDIOC-G-ENC-INDEX; ioctl.</para>
2421 </listitem>
2422 <listitem>
2423 <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD;
2424ioctls.</para>
2425 </listitem>
2426 <listitem>
2427 <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
2428ioctls.</para>
2429 </listitem>
2430 <listitem>
2431 <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
2432 </listitem>
2433 </itemizedlist>
2434 </section>
2435
2436 <section id="obsolete">
2437 <title>Obsolete API Elements</title>
2438
2439 <para>The following V4L2 API elements were superseded by new
2440interfaces and should not be implemented in new drivers.</para>
2441
2442 <itemizedlist>
2443 <listitem>
2444 <para><constant>VIDIOC_G_MPEGCOMP</constant> and
2445<constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls,
2446<xref linkend="extended-controls" />.</para>
2447 </listitem>
2448 </itemizedlist>
2449 </section>
2450
2451 <!--
2452Local Variables:
2453mode: sgml
2454sgml-parent-document: "v4l2.sgml"
2455indent-tabs-mode: nil
2456End:
2457 -->
diff --git a/Documentation/DocBook/v4l/controls.xml b/Documentation/DocBook/v4l/controls.xml
new file mode 100644
index 000000000000..f492accb691d
--- /dev/null
+++ b/Documentation/DocBook/v4l/controls.xml
@@ -0,0 +1,2049 @@
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_COLOR_KILLER</constant></entry>
271 <entry>boolean</entry>
272 <entry>Enable the color killer (&ie; force a black &amp; white image in case of a weak video signal).</entry>
273 </row>
274 <row id="v4l2-colorfx">
275 <entry><constant>V4L2_CID_COLORFX</constant></entry>
276 <entry>enum</entry>
277 <entry>Selects a color effect. Possible values for
278<constant>enum v4l2_colorfx</constant> are:
279<constant>V4L2_COLORFX_NONE</constant> (0),
280<constant>V4L2_COLORFX_BW</constant> (1) and
281<constant>V4L2_COLORFX_SEPIA</constant> (2).</entry>
282 </row>
283 <row>
284 <entry><constant>V4L2_CID_LASTP1</constant></entry>
285 <entry></entry>
286 <entry>End of the predefined control IDs (currently
287<constant>V4L2_CID_COLORFX</constant> + 1).</entry>
288 </row>
289 <row>
290 <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry>
291 <entry></entry>
292 <entry>ID of the first custom (driver specific) control.
293Applications depending on particular custom controls should check the
294driver name and version, see <xref linkend="querycap" />.</entry>
295 </row>
296 </tbody>
297 </tgroup>
298 </table>
299
300 <para>Applications can enumerate the available controls with the
301&VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls, get and set a
302control value with the &VIDIOC-G-CTRL; and &VIDIOC-S-CTRL; ioctls.
303Drivers must implement <constant>VIDIOC_QUERYCTRL</constant>,
304<constant>VIDIOC_G_CTRL</constant> and
305<constant>VIDIOC_S_CTRL</constant> when the device has one or more
306controls, <constant>VIDIOC_QUERYMENU</constant> when it has one or
307more menu type controls.</para>
308
309 <example>
310 <title>Enumerating all controls</title>
311
312 <programlisting>
313&v4l2-queryctrl; queryctrl;
314&v4l2-querymenu; querymenu;
315
316static void
317enumerate_menu (void)
318{
319 printf (" Menu items:\n");
320
321 memset (&amp;querymenu, 0, sizeof (querymenu));
322 querymenu.id = queryctrl.id;
323
324 for (querymenu.index = queryctrl.minimum;
325 querymenu.index &lt;= queryctrl.maximum;
326 querymenu.index++) {
327 if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {
328 printf (" %s\n", querymenu.name);
329 } else {
330 perror ("VIDIOC_QUERYMENU");
331 exit (EXIT_FAILURE);
332 }
333 }
334}
335
336memset (&amp;queryctrl, 0, sizeof (queryctrl));
337
338for (queryctrl.id = V4L2_CID_BASE;
339 queryctrl.id &lt; V4L2_CID_LASTP1;
340 queryctrl.id++) {
341 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
342 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
343 continue;
344
345 printf ("Control %s\n", queryctrl.name);
346
347 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
348 enumerate_menu ();
349 } else {
350 if (errno == EINVAL)
351 continue;
352
353 perror ("VIDIOC_QUERYCTRL");
354 exit (EXIT_FAILURE);
355 }
356}
357
358for (queryctrl.id = V4L2_CID_PRIVATE_BASE;;
359 queryctrl.id++) {
360 if (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
361 if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED)
362 continue;
363
364 printf ("Control %s\n", queryctrl.name);
365
366 if (queryctrl.type == V4L2_CTRL_TYPE_MENU)
367 enumerate_menu ();
368 } else {
369 if (errno == EINVAL)
370 break;
371
372 perror ("VIDIOC_QUERYCTRL");
373 exit (EXIT_FAILURE);
374 }
375}
376</programlisting>
377 </example>
378
379 <example>
380 <title>Changing controls</title>
381
382 <programlisting>
383&v4l2-queryctrl; queryctrl;
384&v4l2-control; control;
385
386memset (&amp;queryctrl, 0, sizeof (queryctrl));
387queryctrl.id = V4L2_CID_BRIGHTNESS;
388
389if (-1 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;queryctrl)) {
390 if (errno != EINVAL) {
391 perror ("VIDIOC_QUERYCTRL");
392 exit (EXIT_FAILURE);
393 } else {
394 printf ("V4L2_CID_BRIGHTNESS is not supported\n");
395 }
396} else if (queryctrl.flags &amp; V4L2_CTRL_FLAG_DISABLED) {
397 printf ("V4L2_CID_BRIGHTNESS is not supported\n");
398} else {
399 memset (&amp;control, 0, sizeof (control));
400 control.id = V4L2_CID_BRIGHTNESS;
401 control.value = queryctrl.default_value;
402
403 if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)) {
404 perror ("VIDIOC_S_CTRL");
405 exit (EXIT_FAILURE);
406 }
407}
408
409memset (&amp;control, 0, sizeof (control));
410control.id = V4L2_CID_CONTRAST;
411
412if (0 == ioctl (fd, &VIDIOC-G-CTRL;, &amp;control)) {
413 control.value += 1;
414
415 /* The driver may clamp the value or return ERANGE, ignored here */
416
417 if (-1 == ioctl (fd, &VIDIOC-S-CTRL;, &amp;control)
418 &amp;&amp; errno != ERANGE) {
419 perror ("VIDIOC_S_CTRL");
420 exit (EXIT_FAILURE);
421 }
422/* Ignore if V4L2_CID_CONTRAST is unsupported */
423} else if (errno != EINVAL) {
424 perror ("VIDIOC_G_CTRL");
425 exit (EXIT_FAILURE);
426}
427
428control.id = V4L2_CID_AUDIO_MUTE;
429control.value = TRUE; /* silence */
430
431/* Errors ignored */
432ioctl (fd, VIDIOC_S_CTRL, &amp;control);
433</programlisting>
434 </example>
435 </section>
436
437 <section id="extended-controls">
438 <title>Extended Controls</title>
439
440 <section>
441 <title>Introduction</title>
442
443 <para>The control mechanism as originally designed was meant
444to be used for user settings (brightness, saturation, etc). However,
445it turned out to be a very useful model for implementing more
446complicated driver APIs where each driver implements only a subset of
447a larger API.</para>
448
449 <para>The MPEG encoding API was the driving force behind
450designing and implementing this extended control mechanism: the MPEG
451standard is quite large and the currently supported hardware MPEG
452encoders each only implement a subset of this standard. Further more,
453many parameters relating to how the video is encoded into an MPEG
454stream are specific to the MPEG encoding chip since the MPEG standard
455only defines the format of the resulting MPEG stream, not how the
456video is actually encoded into that format.</para>
457
458 <para>Unfortunately, the original control API lacked some
459features needed for these new uses and so it was extended into the
460(not terribly originally named) extended control API.</para>
461
462 <para>Even though the MPEG encoding API was the first effort
463to use the Extended Control API, nowadays there are also other classes
464of Extended Controls, such as Camera Controls and FM Transmitter Controls.
465The Extended Controls API as well as all Extended Controls classes are
466described in the following text.</para>
467 </section>
468
469 <section>
470 <title>The Extended Control API</title>
471
472 <para>Three new ioctls are available: &VIDIOC-G-EXT-CTRLS;,
473&VIDIOC-S-EXT-CTRLS; and &VIDIOC-TRY-EXT-CTRLS;. These ioctls act on
474arrays of controls (as opposed to the &VIDIOC-G-CTRL; and
475&VIDIOC-S-CTRL; ioctls that act on a single control). This is needed
476since it is often required to atomically change several controls at
477once.</para>
478
479 <para>Each of the new ioctls expects a pointer to a
480&v4l2-ext-controls;. This structure contains a pointer to the control
481array, a count of the number of controls in that array and a control
482class. Control classes are used to group similar controls into a
483single class. For example, control class
484<constant>V4L2_CTRL_CLASS_USER</constant> contains all user controls
485(&ie; all controls that can also be set using the old
486<constant>VIDIOC_S_CTRL</constant> ioctl). Control class
487<constant>V4L2_CTRL_CLASS_MPEG</constant> contains all controls
488relating to MPEG encoding, etc.</para>
489
490 <para>All controls in the control array must belong to the
491specified control class. An error is returned if this is not the
492case.</para>
493
494 <para>It is also possible to use an empty control array (count
495== 0) to check whether the specified control class is
496supported.</para>
497
498 <para>The control array is a &v4l2-ext-control; array. The
499<structname>v4l2_ext_control</structname> structure is very similar to
500&v4l2-control;, except for the fact that it also allows for 64-bit
501values and pointers to be passed.</para>
502
503 <para>It is important to realize that due to the flexibility of
504controls it is necessary to check whether the control you want to set
505actually is supported in the driver and what the valid range of values
506is. So use the &VIDIOC-QUERYCTRL; and &VIDIOC-QUERYMENU; ioctls to
507check this. Also note that it is possible that some of the menu
508indices in a control of type <constant>V4L2_CTRL_TYPE_MENU</constant>
509may not be supported (<constant>VIDIOC_QUERYMENU</constant> will
510return an error). A good example is the list of supported MPEG audio
511bitrates. Some drivers only support one or two bitrates, others
512support a wider range.</para>
513 </section>
514
515 <section>
516 <title>Enumerating Extended Controls</title>
517
518 <para>The recommended way to enumerate over the extended
519controls is by using &VIDIOC-QUERYCTRL; in combination with the
520<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag:</para>
521
522 <informalexample>
523 <programlisting>
524&v4l2-queryctrl; qctrl;
525
526qctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL;
527while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
528 /* ... */
529 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
530}
531</programlisting>
532 </informalexample>
533
534 <para>The initial control ID is set to 0 ORed with the
535<constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant> flag. The
536<constant>VIDIOC_QUERYCTRL</constant> ioctl will return the first
537control with a higher ID than the specified one. When no such controls
538are found an error is returned.</para>
539
540 <para>If you want to get all controls within a specific control
541class, then you can set the initial
542<structfield>qctrl.id</structfield> value to the control class and add
543an extra check to break out of the loop when a control of another
544control class is found:</para>
545
546 <informalexample>
547 <programlisting>
548qctrl.id = V4L2_CTRL_CLASS_MPEG | V4L2_CTRL_FLAG_NEXT_CTRL;
549while (0 == ioctl (fd, &VIDIOC-QUERYCTRL;, &amp;qctrl)) {
550 if (V4L2_CTRL_ID2CLASS (qctrl.id) != V4L2_CTRL_CLASS_MPEG)
551 break;
552 /* ... */
553 qctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL;
554 }
555</programlisting>
556 </informalexample>
557
558 <para>The 32-bit <structfield>qctrl.id</structfield> value is
559subdivided into three bit ranges: the top 4 bits are reserved for
560flags (&eg; <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>) and are not
561actually part of the ID. The remaining 28 bits form the control ID, of
562which the most significant 12 bits define the control class and the
563least significant 16 bits identify the control within the control
564class. It is guaranteed that these last 16 bits are always non-zero
565for controls. The range of 0x1000 and up are reserved for
566driver-specific controls. The macro
567<constant>V4L2_CTRL_ID2CLASS(id)</constant> returns the control class
568ID based on a control ID.</para>
569
570 <para>If the driver does not support extended controls, then
571<constant>VIDIOC_QUERYCTRL</constant> will fail when used in
572combination with <constant>V4L2_CTRL_FLAG_NEXT_CTRL</constant>. In
573that case the old method of enumerating control should be used (see
5741.8). But if it is supported, then it is guaranteed to enumerate over
575all controls, including driver-private controls.</para>
576 </section>
577
578 <section>
579 <title>Creating Control Panels</title>
580
581 <para>It is possible to create control panels for a graphical
582user interface where the user can select the various controls.
583Basically you will have to iterate over all controls using the method
584described above. Each control class starts with a control of type
585<constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant>.
586<constant>VIDIOC_QUERYCTRL</constant> will return the name of this
587control class which can be used as the title of a tab page within a
588control panel.</para>
589
590 <para>The flags field of &v4l2-queryctrl; also contains hints on
591the behavior of the control. See the &VIDIOC-QUERYCTRL; documentation
592for more details.</para>
593 </section>
594
595 <section id="mpeg-controls">
596 <title>MPEG Control Reference</title>
597
598 <para>Below all controls within the MPEG control class are
599described. First the generic controls, then controls specific for
600certain hardware.</para>
601
602 <section>
603 <title>Generic MPEG Controls</title>
604
605 <table pgwide="1" frame="none" id="mpeg-control-id">
606 <title>MPEG Control IDs</title>
607 <tgroup cols="4">
608 <colspec colname="c1" colwidth="1*" />
609 <colspec colname="c2" colwidth="6*" />
610 <colspec colname="c3" colwidth="2*" />
611 <colspec colname="c4" colwidth="6*" />
612 <spanspec namest="c1" nameend="c2" spanname="id" />
613 <spanspec namest="c2" nameend="c4" spanname="descr" />
614 <thead>
615 <row>
616 <entry spanname="id" align="left">ID</entry>
617 <entry align="left">Type</entry>
618 </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
619 </row>
620 </thead>
621 <tbody valign="top">
622 <row><entry></entry></row>
623 <row>
624 <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant>&nbsp;</entry>
625 <entry>class</entry>
626 </row><row><entry spanname="descr">The MPEG class
627descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
628description of this control class. This description can be used as the
629caption of a Tab page in a GUI, for example.</entry>
630 </row>
631 <row><entry></entry></row>
632 <row id="v4l2-mpeg-stream-type">
633 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_TYPE</constant>&nbsp;</entry>
634 <entry>enum&nbsp;v4l2_mpeg_stream_type</entry>
635 </row><row><entry spanname="descr">The MPEG-1, -2 or -4
636output stream type. One cannot assume anything here. Each hardware
637MPEG encoder tends to support different subsets of the available MPEG
638stream types. The currently defined stream types are:</entry>
639 </row>
640 <row>
641 <entrytbl spanname="descr" cols="2">
642 <tbody valign="top">
643 <row>
644 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_PS</constant>&nbsp;</entry>
645 <entry>MPEG-2 program stream</entry>
646 </row>
647 <row>
648 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_TS</constant>&nbsp;</entry>
649 <entry>MPEG-2 transport stream</entry>
650 </row>
651 <row>
652 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_SS</constant>&nbsp;</entry>
653 <entry>MPEG-1 system stream</entry>
654 </row>
655 <row>
656 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_DVD</constant>&nbsp;</entry>
657 <entry>MPEG-2 DVD-compatible stream</entry>
658 </row>
659 <row>
660 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG1_VCD</constant>&nbsp;</entry>
661 <entry>MPEG-1 VCD-compatible stream</entry>
662 </row>
663 <row>
664 <entry><constant>V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD</constant>&nbsp;</entry>
665 <entry>MPEG-2 SVCD-compatible stream</entry>
666 </row>
667 </tbody>
668 </entrytbl>
669 </row>
670 <row><entry></entry></row>
671 <row>
672 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PMT</constant>&nbsp;</entry>
673 <entry>integer</entry>
674 </row><row><entry spanname="descr">Program Map Table
675Packet ID for the MPEG transport stream (default 16)</entry>
676 </row>
677 <row><entry></entry></row>
678 <row>
679 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_AUDIO</constant>&nbsp;</entry>
680 <entry>integer</entry>
681 </row><row><entry spanname="descr">Audio Packet ID for
682the MPEG transport stream (default 256)</entry>
683 </row>
684 <row><entry></entry></row>
685 <row>
686 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_VIDEO</constant>&nbsp;</entry>
687 <entry>integer</entry>
688 </row><row><entry spanname="descr">Video Packet ID for
689the MPEG transport stream (default 260)</entry>
690 </row>
691 <row><entry></entry></row>
692 <row>
693 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PID_PCR</constant>&nbsp;</entry>
694 <entry>integer</entry>
695 </row><row><entry spanname="descr">Packet ID for the
696MPEG transport stream carrying PCR fields (default 259)</entry>
697 </row>
698 <row><entry></entry></row>
699 <row>
700 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_AUDIO</constant>&nbsp;</entry>
701 <entry>integer</entry>
702 </row><row><entry spanname="descr">Audio ID for MPEG
703PES</entry>
704 </row>
705 <row><entry></entry></row>
706 <row>
707 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_PES_ID_VIDEO</constant>&nbsp;</entry>
708 <entry>integer</entry>
709 </row><row><entry spanname="descr">Video ID for MPEG
710PES</entry>
711 </row>
712 <row><entry></entry></row>
713 <row id="v4l2-mpeg-stream-vbi-fmt">
714 <entry spanname="id"><constant>V4L2_CID_MPEG_STREAM_VBI_FMT</constant>&nbsp;</entry>
715 <entry>enum&nbsp;v4l2_mpeg_stream_vbi_fmt</entry>
716 </row><row><entry spanname="descr">Some cards can embed
717VBI data (&eg; Closed Caption, Teletext) into the MPEG stream. This
718control selects whether VBI data should be embedded, and if so, what
719embedding method should be used. The list of possible VBI formats
720depends on the driver. The currently defined VBI format types
721are:</entry>
722 </row>
723 <row>
724 <entrytbl spanname="descr" cols="2">
725 <tbody valign="top">
726 <row>
727 <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_NONE</constant>&nbsp;</entry>
728 <entry>No VBI in the MPEG stream</entry>
729 </row>
730 <row>
731 <entry><constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant>&nbsp;</entry>
732 <entry>VBI in private packets, IVTV format (documented
733in the kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>)</entry>
734 </row>
735 </tbody>
736 </entrytbl>
737 </row>
738 <row><entry></entry></row>
739 <row id="v4l2-mpeg-audio-sampling-freq">
740 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ</constant>&nbsp;</entry>
741 <entry>enum&nbsp;v4l2_mpeg_audio_sampling_freq</entry>
742 </row><row><entry spanname="descr">MPEG Audio sampling
743frequency. Possible values are:</entry>
744 </row>
745 <row>
746 <entrytbl spanname="descr" cols="2">
747 <tbody valign="top">
748 <row>
749 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100</constant>&nbsp;</entry>
750 <entry>44.1 kHz</entry>
751 </row>
752 <row>
753 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000</constant>&nbsp;</entry>
754 <entry>48 kHz</entry>
755 </row>
756 <row>
757 <entry><constant>V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000</constant>&nbsp;</entry>
758 <entry>32 kHz</entry>
759 </row>
760 </tbody>
761 </entrytbl>
762 </row>
763 <row><entry></entry></row>
764 <row id="v4l2-mpeg-audio-encoding">
765 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_ENCODING</constant>&nbsp;</entry>
766 <entry>enum&nbsp;v4l2_mpeg_audio_encoding</entry>
767 </row><row><entry spanname="descr">MPEG Audio encoding.
768Possible values are:</entry>
769 </row>
770 <row>
771 <entrytbl spanname="descr" cols="2">
772 <tbody valign="top">
773 <row>
774 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_1</constant>&nbsp;</entry>
775 <entry>MPEG-1/2 Layer I encoding</entry>
776 </row>
777 <row>
778 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_2</constant>&nbsp;</entry>
779 <entry>MPEG-1/2 Layer II encoding</entry>
780 </row>
781 <row>
782 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_LAYER_3</constant>&nbsp;</entry>
783 <entry>MPEG-1/2 Layer III encoding</entry>
784 </row>
785 <row>
786 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AAC</constant>&nbsp;</entry>
787 <entry>MPEG-2/4 AAC (Advanced Audio Coding)</entry>
788 </row>
789 <row>
790 <entry><constant>V4L2_MPEG_AUDIO_ENCODING_AC3</constant>&nbsp;</entry>
791 <entry>AC-3 aka ATSC A/52 encoding</entry>
792 </row>
793 </tbody>
794 </entrytbl>
795 </row>
796 <row><entry></entry></row>
797 <row id="v4l2-mpeg-audio-l1-bitrate">
798 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L1_BITRATE</constant>&nbsp;</entry>
799 <entry>enum&nbsp;v4l2_mpeg_audio_l1_bitrate</entry>
800 </row><row><entry spanname="descr">MPEG-1/2 Layer I bitrate.
801Possible values are:</entry>
802 </row>
803 <row>
804 <entrytbl spanname="descr" cols="2">
805 <tbody valign="top">
806 <row>
807 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_32K</constant>&nbsp;</entry>
808 <entry>32 kbit/s</entry></row>
809 <row>
810 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_64K</constant>&nbsp;</entry>
811 <entry>64 kbit/s</entry>
812 </row>
813 <row>
814 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_96K</constant>&nbsp;</entry>
815 <entry>96 kbit/s</entry>
816 </row>
817 <row>
818 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_128K</constant>&nbsp;</entry>
819 <entry>128 kbit/s</entry>
820 </row>
821 <row>
822 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_160K</constant>&nbsp;</entry>
823 <entry>160 kbit/s</entry>
824 </row>
825 <row>
826 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_192K</constant>&nbsp;</entry>
827 <entry>192 kbit/s</entry>
828 </row>
829 <row>
830 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_224K</constant>&nbsp;</entry>
831 <entry>224 kbit/s</entry>
832 </row>
833 <row>
834 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_256K</constant>&nbsp;</entry>
835 <entry>256 kbit/s</entry>
836 </row>
837 <row>
838 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_288K</constant>&nbsp;</entry>
839 <entry>288 kbit/s</entry>
840 </row>
841 <row>
842 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_320K</constant>&nbsp;</entry>
843 <entry>320 kbit/s</entry>
844 </row>
845 <row>
846 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_352K</constant>&nbsp;</entry>
847 <entry>352 kbit/s</entry>
848 </row>
849 <row>
850 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_384K</constant>&nbsp;</entry>
851 <entry>384 kbit/s</entry>
852 </row>
853 <row>
854 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_416K</constant>&nbsp;</entry>
855 <entry>416 kbit/s</entry>
856 </row>
857 <row>
858 <entry><constant>V4L2_MPEG_AUDIO_L1_BITRATE_448K</constant>&nbsp;</entry>
859 <entry>448 kbit/s</entry>
860 </row>
861 </tbody>
862 </entrytbl>
863 </row>
864 <row><entry></entry></row>
865 <row id="v4l2-mpeg-audio-l2-bitrate">
866 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L2_BITRATE</constant>&nbsp;</entry>
867 <entry>enum&nbsp;v4l2_mpeg_audio_l2_bitrate</entry>
868 </row><row><entry spanname="descr">MPEG-1/2 Layer II bitrate.
869Possible values are:</entry>
870 </row>
871 <row>
872 <entrytbl spanname="descr" cols="2">
873 <tbody valign="top">
874 <row>
875 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_32K</constant>&nbsp;</entry>
876 <entry>32 kbit/s</entry>
877 </row>
878 <row>
879 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_48K</constant>&nbsp;</entry>
880 <entry>48 kbit/s</entry>
881 </row>
882 <row>
883 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_56K</constant>&nbsp;</entry>
884 <entry>56 kbit/s</entry>
885 </row>
886 <row>
887 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_64K</constant>&nbsp;</entry>
888 <entry>64 kbit/s</entry>
889 </row>
890 <row>
891 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_80K</constant>&nbsp;</entry>
892 <entry>80 kbit/s</entry>
893 </row>
894 <row>
895 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_96K</constant>&nbsp;</entry>
896 <entry>96 kbit/s</entry>
897 </row>
898 <row>
899 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_112K</constant>&nbsp;</entry>
900 <entry>112 kbit/s</entry>
901 </row>
902 <row>
903 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_128K</constant>&nbsp;</entry>
904 <entry>128 kbit/s</entry>
905 </row>
906 <row>
907 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_160K</constant>&nbsp;</entry>
908 <entry>160 kbit/s</entry>
909 </row>
910 <row>
911 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_192K</constant>&nbsp;</entry>
912 <entry>192 kbit/s</entry>
913 </row>
914 <row>
915 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_224K</constant>&nbsp;</entry>
916 <entry>224 kbit/s</entry>
917 </row>
918 <row>
919 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_256K</constant>&nbsp;</entry>
920 <entry>256 kbit/s</entry>
921 </row>
922 <row>
923 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_320K</constant>&nbsp;</entry>
924 <entry>320 kbit/s</entry>
925 </row>
926 <row>
927 <entry><constant>V4L2_MPEG_AUDIO_L2_BITRATE_384K</constant>&nbsp;</entry>
928 <entry>384 kbit/s</entry>
929 </row>
930 </tbody>
931 </entrytbl>
932 </row>
933 <row><entry></entry></row>
934 <row id="v4l2-mpeg-audio-l3-bitrate">
935 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_L3_BITRATE</constant>&nbsp;</entry>
936 <entry>enum&nbsp;v4l2_mpeg_audio_l3_bitrate</entry>
937 </row><row><entry spanname="descr">MPEG-1/2 Layer III bitrate.
938Possible values are:</entry>
939 </row>
940 <row>
941 <entrytbl spanname="descr" cols="2">
942 <tbody valign="top">
943 <row>
944 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_32K</constant>&nbsp;</entry>
945 <entry>32 kbit/s</entry>
946 </row>
947 <row>
948 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_40K</constant>&nbsp;</entry>
949 <entry>40 kbit/s</entry>
950 </row>
951 <row>
952 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_48K</constant>&nbsp;</entry>
953 <entry>48 kbit/s</entry>
954 </row>
955 <row>
956 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_56K</constant>&nbsp;</entry>
957 <entry>56 kbit/s</entry>
958 </row>
959 <row>
960 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_64K</constant>&nbsp;</entry>
961 <entry>64 kbit/s</entry>
962 </row>
963 <row>
964 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_80K</constant>&nbsp;</entry>
965 <entry>80 kbit/s</entry>
966 </row>
967 <row>
968 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_96K</constant>&nbsp;</entry>
969 <entry>96 kbit/s</entry>
970 </row>
971 <row>
972 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_112K</constant>&nbsp;</entry>
973 <entry>112 kbit/s</entry>
974 </row>
975 <row>
976 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_128K</constant>&nbsp;</entry>
977 <entry>128 kbit/s</entry>
978 </row>
979 <row>
980 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_160K</constant>&nbsp;</entry>
981 <entry>160 kbit/s</entry>
982 </row>
983 <row>
984 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_192K</constant>&nbsp;</entry>
985 <entry>192 kbit/s</entry>
986 </row>
987 <row>
988 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_224K</constant>&nbsp;</entry>
989 <entry>224 kbit/s</entry>
990 </row>
991 <row>
992 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_256K</constant>&nbsp;</entry>
993 <entry>256 kbit/s</entry>
994 </row>
995 <row>
996 <entry><constant>V4L2_MPEG_AUDIO_L3_BITRATE_320K</constant>&nbsp;</entry>
997 <entry>320 kbit/s</entry>
998 </row>
999 </tbody>
1000 </entrytbl>
1001 </row>
1002 <row><entry></entry></row>
1003 <row>
1004 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AAC_BITRATE</constant>&nbsp;</entry>
1005 <entry>integer</entry>
1006 </row><row><entry spanname="descr">AAC bitrate in bits per second.</entry>
1007 </row>
1008 <row><entry></entry></row>
1009 <row id="v4l2-mpeg-audio-ac3-bitrate">
1010 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_AC3_BITRATE</constant>&nbsp;</entry>
1011 <entry>enum&nbsp;v4l2_mpeg_audio_ac3_bitrate</entry>
1012 </row><row><entry spanname="descr">AC-3 bitrate.
1013Possible values are:</entry>
1014 </row>
1015 <row>
1016 <entrytbl spanname="descr" cols="2">
1017 <tbody valign="top">
1018 <row>
1019 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_32K</constant>&nbsp;</entry>
1020 <entry>32 kbit/s</entry>
1021 </row>
1022 <row>
1023 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_40K</constant>&nbsp;</entry>
1024 <entry>40 kbit/s</entry>
1025 </row>
1026 <row>
1027 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_48K</constant>&nbsp;</entry>
1028 <entry>48 kbit/s</entry>
1029 </row>
1030 <row>
1031 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_56K</constant>&nbsp;</entry>
1032 <entry>56 kbit/s</entry>
1033 </row>
1034 <row>
1035 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_64K</constant>&nbsp;</entry>
1036 <entry>64 kbit/s</entry>
1037 </row>
1038 <row>
1039 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_80K</constant>&nbsp;</entry>
1040 <entry>80 kbit/s</entry>
1041 </row>
1042 <row>
1043 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_96K</constant>&nbsp;</entry>
1044 <entry>96 kbit/s</entry>
1045 </row>
1046 <row>
1047 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_112K</constant>&nbsp;</entry>
1048 <entry>112 kbit/s</entry>
1049 </row>
1050 <row>
1051 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_128K</constant>&nbsp;</entry>
1052 <entry>128 kbit/s</entry>
1053 </row>
1054 <row>
1055 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_160K</constant>&nbsp;</entry>
1056 <entry>160 kbit/s</entry>
1057 </row>
1058 <row>
1059 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_192K</constant>&nbsp;</entry>
1060 <entry>192 kbit/s</entry>
1061 </row>
1062 <row>
1063 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_224K</constant>&nbsp;</entry>
1064 <entry>224 kbit/s</entry>
1065 </row>
1066 <row>
1067 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_256K</constant>&nbsp;</entry>
1068 <entry>256 kbit/s</entry>
1069 </row>
1070 <row>
1071 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_320K</constant>&nbsp;</entry>
1072 <entry>320 kbit/s</entry>
1073 </row>
1074 <row>
1075 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_384K</constant>&nbsp;</entry>
1076 <entry>384 kbit/s</entry>
1077 </row>
1078 <row>
1079 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_448K</constant>&nbsp;</entry>
1080 <entry>448 kbit/s</entry>
1081 </row>
1082 <row>
1083 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_512K</constant>&nbsp;</entry>
1084 <entry>512 kbit/s</entry>
1085 </row>
1086 <row>
1087 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_576K</constant>&nbsp;</entry>
1088 <entry>576 kbit/s</entry>
1089 </row>
1090 <row>
1091 <entry><constant>V4L2_MPEG_AUDIO_AC3_BITRATE_640K</constant>&nbsp;</entry>
1092 <entry>640 kbit/s</entry>
1093 </row>
1094 </tbody>
1095 </entrytbl>
1096 </row>
1097 <row><entry></entry></row>
1098 <row id="v4l2-mpeg-audio-mode">
1099 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE</constant>&nbsp;</entry>
1100 <entry>enum&nbsp;v4l2_mpeg_audio_mode</entry>
1101 </row><row><entry spanname="descr">MPEG Audio mode.
1102Possible values are:</entry>
1103 </row>
1104 <row>
1105 <entrytbl spanname="descr" cols="2">
1106 <tbody valign="top">
1107 <row>
1108 <entry><constant>V4L2_MPEG_AUDIO_MODE_STEREO</constant>&nbsp;</entry>
1109 <entry>Stereo</entry>
1110 </row>
1111 <row>
1112 <entry><constant>V4L2_MPEG_AUDIO_MODE_JOINT_STEREO</constant>&nbsp;</entry>
1113 <entry>Joint Stereo</entry>
1114 </row>
1115 <row>
1116 <entry><constant>V4L2_MPEG_AUDIO_MODE_DUAL</constant>&nbsp;</entry>
1117 <entry>Bilingual</entry>
1118 </row>
1119 <row>
1120 <entry><constant>V4L2_MPEG_AUDIO_MODE_MONO</constant>&nbsp;</entry>
1121 <entry>Mono</entry>
1122 </row>
1123 </tbody>
1124 </entrytbl>
1125 </row>
1126 <row><entry></entry></row>
1127 <row id="v4l2-mpeg-audio-mode-extension">
1128 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MODE_EXTENSION</constant>&nbsp;</entry>
1129 <entry>enum&nbsp;v4l2_mpeg_audio_mode_extension</entry>
1130 </row><row><entry spanname="descr">Joint Stereo
1131audio mode extension. In Layer I and II they indicate which subbands
1132are in intensity stereo. All other subbands are coded in stereo. Layer
1133III is not (yet) supported. Possible values
1134are:</entry>
1135 </row>
1136 <row>
1137 <entrytbl spanname="descr" cols="2">
1138 <tbody valign="top">
1139 <row>
1140 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4</constant>&nbsp;</entry>
1141 <entry>Subbands 4-31 in intensity stereo</entry>
1142 </row>
1143 <row>
1144 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8</constant>&nbsp;</entry>
1145 <entry>Subbands 8-31 in intensity stereo</entry>
1146 </row>
1147 <row>
1148 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12</constant>&nbsp;</entry>
1149 <entry>Subbands 12-31 in intensity stereo</entry>
1150 </row>
1151 <row>
1152 <entry><constant>V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16</constant>&nbsp;</entry>
1153 <entry>Subbands 16-31 in intensity stereo</entry>
1154 </row>
1155 </tbody>
1156 </entrytbl>
1157 </row>
1158 <row><entry></entry></row>
1159 <row id="v4l2-mpeg-audio-emphasis">
1160 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_EMPHASIS</constant>&nbsp;</entry>
1161 <entry>enum&nbsp;v4l2_mpeg_audio_emphasis</entry>
1162 </row><row><entry spanname="descr">Audio Emphasis.
1163Possible values are:</entry>
1164 </row>
1165 <row>
1166 <entrytbl spanname="descr" cols="2">
1167 <tbody valign="top">
1168 <row>
1169 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_NONE</constant>&nbsp;</entry>
1170 <entry>None</entry>
1171 </row>
1172 <row>
1173 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS</constant>&nbsp;</entry>
1174 <entry>50/15 microsecond emphasis</entry>
1175 </row>
1176 <row>
1177 <entry><constant>V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17</constant>&nbsp;</entry>
1178 <entry>CCITT J.17</entry>
1179 </row>
1180 </tbody>
1181 </entrytbl>
1182 </row>
1183 <row><entry></entry></row>
1184 <row id="v4l2-mpeg-audio-crc">
1185 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_CRC</constant>&nbsp;</entry>
1186 <entry>enum&nbsp;v4l2_mpeg_audio_crc</entry>
1187 </row><row><entry spanname="descr">CRC method. Possible
1188values are:</entry>
1189 </row>
1190 <row>
1191 <entrytbl spanname="descr" cols="2">
1192 <tbody valign="top">
1193 <row>
1194 <entry><constant>V4L2_MPEG_AUDIO_CRC_NONE</constant>&nbsp;</entry>
1195 <entry>None</entry>
1196 </row>
1197 <row>
1198 <entry><constant>V4L2_MPEG_AUDIO_CRC_CRC16</constant>&nbsp;</entry>
1199 <entry>16 bit parity check</entry>
1200 </row>
1201 </tbody>
1202 </entrytbl>
1203 </row>
1204 <row><entry></entry></row>
1205 <row>
1206 <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_MUTE</constant>&nbsp;</entry>
1207 <entry>boolean</entry>
1208 </row><row><entry spanname="descr">Mutes the audio when
1209capturing. This is not done by muting audio hardware, which can still
1210produce a slight hiss, but in the encoder itself, guaranteeing a fixed
1211and reproducable audio bitstream. 0 = unmuted, 1 = muted.</entry>
1212 </row>
1213 <row><entry></entry></row>
1214 <row id="v4l2-mpeg-video-encoding">
1215 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant>&nbsp;</entry>
1216 <entry>enum&nbsp;v4l2_mpeg_video_encoding</entry>
1217 </row><row><entry spanname="descr">MPEG Video encoding
1218method. Possible values are:</entry>
1219 </row>
1220 <row>
1221 <entrytbl spanname="descr" cols="2">
1222 <tbody valign="top">
1223 <row>
1224 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_1</constant>&nbsp;</entry>
1225 <entry>MPEG-1 Video encoding</entry>
1226 </row>
1227 <row>
1228 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_2</constant>&nbsp;</entry>
1229 <entry>MPEG-2 Video encoding</entry>
1230 </row>
1231 <row>
1232 <entry><constant>V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC</constant>&nbsp;</entry>
1233 <entry>MPEG-4 AVC (H.264) Video encoding</entry>
1234 </row>
1235 </tbody>
1236 </entrytbl>
1237 </row>
1238 <row><entry></entry></row>
1239 <row id="v4l2-mpeg-video-aspect">
1240 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ASPECT</constant>&nbsp;</entry>
1241 <entry>enum&nbsp;v4l2_mpeg_video_aspect</entry>
1242 </row><row><entry spanname="descr">Video aspect.
1243Possible values are:</entry>
1244 </row>
1245 <row>
1246 <entrytbl spanname="descr" cols="2">
1247 <tbody valign="top">
1248 <row>
1249 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_1x1</constant>&nbsp;</entry>
1250 </row>
1251 <row>
1252 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_4x3</constant>&nbsp;</entry>
1253 </row>
1254 <row>
1255 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_16x9</constant>&nbsp;</entry>
1256 </row>
1257 <row>
1258 <entry><constant>V4L2_MPEG_VIDEO_ASPECT_221x100</constant>&nbsp;</entry>
1259 </row>
1260 </tbody>
1261 </entrytbl>
1262 </row>
1263 <row><entry></entry></row>
1264 <row>
1265 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_B_FRAMES</constant>&nbsp;</entry>
1266 <entry>integer</entry>
1267 </row><row><entry spanname="descr">Number of B-Frames
1268(default 2)</entry>
1269 </row>
1270 <row><entry></entry></row>
1271 <row>
1272 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_SIZE</constant>&nbsp;</entry>
1273 <entry>integer</entry>
1274 </row><row><entry spanname="descr">GOP size (default
127512)</entry>
1276 </row>
1277 <row><entry></entry></row>
1278 <row>
1279 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_GOP_CLOSURE</constant>&nbsp;</entry>
1280 <entry>boolean</entry>
1281 </row><row><entry spanname="descr">GOP closure (default
12821)</entry>
1283 </row>
1284 <row><entry></entry></row>
1285 <row>
1286 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_PULLDOWN</constant>&nbsp;</entry>
1287 <entry>boolean</entry>
1288 </row><row><entry spanname="descr">Enable 3:2 pulldown
1289(default 0)</entry>
1290 </row>
1291 <row><entry></entry></row>
1292 <row id="v4l2-mpeg-video-bitrate-mode">
1293 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_MODE</constant>&nbsp;</entry>
1294 <entry>enum&nbsp;v4l2_mpeg_video_bitrate_mode</entry>
1295 </row><row><entry spanname="descr">Video bitrate mode.
1296Possible values are:</entry>
1297 </row>
1298 <row>
1299 <entrytbl spanname="descr" cols="2">
1300 <tbody valign="top">
1301 <row>
1302 <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_VBR</constant>&nbsp;</entry>
1303 <entry>Variable bitrate</entry>
1304 </row>
1305 <row>
1306 <entry><constant>V4L2_MPEG_VIDEO_BITRATE_MODE_CBR</constant>&nbsp;</entry>
1307 <entry>Constant bitrate</entry>
1308 </row>
1309 </tbody>
1310 </entrytbl>
1311 </row>
1312 <row><entry></entry></row>
1313 <row>
1314 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE</constant>&nbsp;</entry>
1315 <entry>integer</entry>
1316 </row><row><entry spanname="descr">Video bitrate in bits
1317per second.</entry>
1318 </row>
1319 <row><entry></entry></row>
1320 <row>
1321 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_BITRATE_PEAK</constant>&nbsp;</entry>
1322 <entry>integer</entry>
1323 </row><row><entry spanname="descr">Peak video bitrate in
1324bits per second. Must be larger or equal to the average video bitrate.
1325It is ignored if the video bitrate mode is set to constant
1326bitrate.</entry>
1327 </row>
1328 <row><entry></entry></row>
1329 <row>
1330 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION</constant>&nbsp;</entry>
1331 <entry>integer</entry>
1332 </row><row><entry spanname="descr">For every captured
1333frame, skip this many subsequent frames (default 0).</entry>
1334 </row>
1335 <row><entry></entry></row>
1336 <row>
1337 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE</constant>&nbsp;</entry>
1338 <entry>boolean</entry>
1339 </row>
1340 <row><entry spanname="descr">"Mutes" the video to a
1341fixed color when capturing. This is useful for testing, to produce a
1342fixed video bitstream. 0 = unmuted, 1 = muted.</entry>
1343 </row>
1344 <row><entry></entry></row>
1345 <row>
1346 <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_MUTE_YUV</constant>&nbsp;</entry>
1347 <entry>integer</entry>
1348 </row><row><entry spanname="descr">Sets the "mute" color
1349of the video. The supplied 32-bit integer is interpreted as follows (bit
13500 = least significant bit):</entry>
1351 </row>
1352 <row>
1353 <entrytbl spanname="descr" cols="2">
1354 <tbody valign="top">
1355 <row>
1356 <entry>Bit 0:7</entry>
1357 <entry>V chrominance information</entry>
1358 </row>
1359 <row>
1360 <entry>Bit 8:15</entry>
1361 <entry>U chrominance information</entry>
1362 </row>
1363 <row>
1364 <entry>Bit 16:23</entry>
1365 <entry>Y luminance information</entry>
1366 </row>
1367 <row>
1368 <entry>Bit 24:31</entry>
1369 <entry>Must be zero.</entry>
1370 </row>
1371 </tbody>
1372 </entrytbl>
1373 </row>
1374 </tbody>
1375 </tgroup>
1376 </table>
1377 </section>
1378
1379 <section>
1380 <title>CX2341x MPEG Controls</title>
1381
1382 <para>The following MPEG class controls deal with MPEG
1383encoding settings that are specific to the Conexant CX23415 and
1384CX23416 MPEG encoding chips.</para>
1385
1386 <table pgwide="1" frame="none" id="cx2341x-control-id">
1387 <title>CX2341x Control IDs</title>
1388 <tgroup cols="4">
1389 <colspec colname="c1" colwidth="1*" />
1390 <colspec colname="c2" colwidth="6*" />
1391 <colspec colname="c3" colwidth="2*" />
1392 <colspec colname="c4" colwidth="6*" />
1393 <spanspec namest="c1" nameend="c2" spanname="id" />
1394 <spanspec namest="c2" nameend="c4" spanname="descr" />
1395 <thead>
1396 <row>
1397 <entry spanname="id" align="left">ID</entry>
1398 <entry align="left">Type</entry>
1399 </row><row><entry spanname="descr" align="left">Description</entry>
1400 </row>
1401 </thead>
1402 <tbody valign="top">
1403 <row><entry></entry></row>
1404 <row id="v4l2-mpeg-cx2341x-video-spatial-filter-mode">
1405 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE</constant>&nbsp;</entry>
1406 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_spatial_filter_mode</entry>
1407 </row><row><entry spanname="descr">Sets the Spatial
1408Filter mode (default <constant>MANUAL</constant>). Possible values
1409are:</entry>
1410 </row>
1411 <row>
1412 <entrytbl spanname="descr" cols="2">
1413 <tbody valign="top">
1414 <row>
1415 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
1416 <entry>Choose the filter manually</entry>
1417 </row>
1418 <row>
1419 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
1420 <entry>Choose the filter automatically</entry>
1421 </row>
1422 </tbody>
1423 </entrytbl>
1424 </row>
1425 <row><entry></entry></row>
1426 <row>
1427 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER</constant>&nbsp;</entry>
1428 <entry>integer&nbsp;(0-15)</entry>
1429 </row><row><entry spanname="descr">The setting for the
1430Spatial Filter. 0 = off, 15 = maximum. (Default is 0.)</entry>
1431 </row>
1432 <row><entry></entry></row>
1433 <row id="luma-spatial-filter-type">
1434 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
1435 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</entry>
1436 </row><row><entry spanname="descr">Select the algorithm
1437to use for the Luma Spatial Filter (default
1438<constant>1D_HOR</constant>). Possible values:</entry>
1439 </row>
1440 <row>
1441 <entrytbl spanname="descr" cols="2">
1442 <tbody valign="top">
1443 <row>
1444 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
1445 <entry>No filter</entry>
1446 </row>
1447 <row>
1448 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
1449 <entry>One-dimensional horizontal</entry>
1450 </row>
1451 <row>
1452 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT</constant>&nbsp;</entry>
1453 <entry>One-dimensional vertical</entry>
1454 </row>
1455 <row>
1456 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE</constant>&nbsp;</entry>
1457 <entry>Two-dimensional separable</entry>
1458 </row>
1459 <row>
1460 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE</constant>&nbsp;</entry>
1461 <entry>Two-dimensional symmetrical
1462non-separable</entry>
1463 </row>
1464 </tbody>
1465 </entrytbl>
1466 </row>
1467 <row><entry></entry></row>
1468 <row id="chroma-spatial-filter-type">
1469 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE</constant>&nbsp;</entry>
1470 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</entry>
1471 </row><row><entry spanname="descr">Select the algorithm
1472for the Chroma Spatial Filter (default <constant>1D_HOR</constant>).
1473Possible values are:</entry>
1474 </row>
1475 <row>
1476 <entrytbl spanname="descr" cols="2">
1477 <tbody valign="top">
1478 <row>
1479 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF</constant>&nbsp;</entry>
1480 <entry>No filter</entry>
1481 </row>
1482 <row>
1483 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR</constant>&nbsp;</entry>
1484 <entry>One-dimensional horizontal</entry>
1485 </row>
1486 </tbody>
1487 </entrytbl>
1488 </row>
1489 <row><entry></entry></row>
1490 <row id="v4l2-mpeg-cx2341x-video-temporal-filter-mode">
1491 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE</constant>&nbsp;</entry>
1492 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_temporal_filter_mode</entry>
1493 </row><row><entry spanname="descr">Sets the Temporal
1494Filter mode (default <constant>MANUAL</constant>). Possible values
1495are:</entry>
1496 </row>
1497 <row>
1498 <entrytbl spanname="descr" cols="2">
1499 <tbody valign="top">
1500 <row>
1501 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL</constant>&nbsp;</entry>
1502 <entry>Choose the filter manually</entry>
1503 </row>
1504 <row>
1505 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO</constant>&nbsp;</entry>
1506 <entry>Choose the filter automatically</entry>
1507 </row>
1508 </tbody>
1509 </entrytbl>
1510 </row>
1511 <row><entry></entry></row>
1512 <row>
1513 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER</constant>&nbsp;</entry>
1514 <entry>integer&nbsp;(0-31)</entry>
1515 </row><row><entry spanname="descr">The setting for the
1516Temporal Filter. 0 = off, 31 = maximum. (Default is 8 for full-scale
1517capturing and 0 for scaled capturing.)</entry>
1518 </row>
1519 <row><entry></entry></row>
1520 <row id="v4l2-mpeg-cx2341x-video-median-filter-type">
1521 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE</constant>&nbsp;</entry>
1522 <entry>enum&nbsp;v4l2_mpeg_cx2341x_video_median_filter_type</entry>
1523 </row><row><entry spanname="descr">Median Filter Type
1524(default <constant>OFF</constant>). Possible values are:</entry>
1525 </row>
1526 <row>
1527 <entrytbl spanname="descr" cols="2">
1528 <tbody valign="top">
1529 <row>
1530 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF</constant>&nbsp;</entry>
1531 <entry>No filter</entry>
1532 </row>
1533 <row>
1534 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR</constant>&nbsp;</entry>
1535 <entry>Horizontal filter</entry>
1536 </row>
1537 <row>
1538 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT</constant>&nbsp;</entry>
1539 <entry>Vertical filter</entry>
1540 </row>
1541 <row>
1542 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT</constant>&nbsp;</entry>
1543 <entry>Horizontal and vertical filter</entry>
1544 </row>
1545 <row>
1546 <entry><constant>V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG</constant>&nbsp;</entry>
1547 <entry>Diagonal filter</entry>
1548 </row>
1549 </tbody>
1550 </entrytbl>
1551 </row>
1552 <row><entry></entry></row>
1553 <row>
1554 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
1555 <entry>integer&nbsp;(0-255)</entry>
1556 </row><row><entry spanname="descr">Threshold above which
1557the luminance median filter is enabled (default 0)</entry>
1558 </row>
1559 <row><entry></entry></row>
1560 <row>
1561 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
1562 <entry>integer&nbsp;(0-255)</entry>
1563 </row><row><entry spanname="descr">Threshold below which
1564the luminance median filter is enabled (default 255)</entry>
1565 </row>
1566 <row><entry></entry></row>
1567 <row>
1568 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM</constant>&nbsp;</entry>
1569 <entry>integer&nbsp;(0-255)</entry>
1570 </row><row><entry spanname="descr">Threshold above which
1571the chroma median filter is enabled (default 0)</entry>
1572 </row>
1573 <row><entry></entry></row>
1574 <row>
1575 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP</constant>&nbsp;</entry>
1576 <entry>integer&nbsp;(0-255)</entry>
1577 </row><row><entry spanname="descr">Threshold below which
1578the chroma median filter is enabled (default 255)</entry>
1579 </row>
1580 <row><entry></entry></row>
1581 <row>
1582 <entry spanname="id"><constant>V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS</constant>&nbsp;</entry>
1583 <entry>boolean</entry>
1584 </row>
1585 <row><entry spanname="descr">The CX2341X MPEG encoder
1586can insert one empty MPEG-2 PES packet into the stream between every
1587four video frames. The packet size is 2048 bytes, including the
1588packet_start_code_prefix and stream_id fields. The stream_id is 0xBF
1589(private stream 2). The payload consists of 0x00 bytes, to be filled
1590in by the application. 0 = do not insert, 1 = insert packets.</entry>
1591 </row>
1592 </tbody>
1593 </tgroup>
1594 </table>
1595 </section>
1596 </section>
1597
1598 <section id="camera-controls">
1599 <title>Camera Control Reference</title>
1600
1601 <para>The Camera class includes controls for mechanical (or
1602equivalent digital) features of a device such as controllable lenses
1603or sensors.</para>
1604
1605 <table pgwide="1" frame="none" id="camera-control-id">
1606 <title>Camera Control IDs</title>
1607 <tgroup cols="4">
1608 <colspec colname="c1" colwidth="1*" />
1609 <colspec colname="c2" colwidth="6*" />
1610 <colspec colname="c3" colwidth="2*" />
1611 <colspec colname="c4" colwidth="6*" />
1612 <spanspec namest="c1" nameend="c2" spanname="id" />
1613 <spanspec namest="c2" nameend="c4" spanname="descr" />
1614 <thead>
1615 <row>
1616 <entry spanname="id" align="left">ID</entry>
1617 <entry align="left">Type</entry>
1618 </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
1619 </row>
1620 </thead>
1621 <tbody valign="top">
1622 <row><entry></entry></row>
1623 <row>
1624 <entry spanname="id"><constant>V4L2_CID_CAMERA_CLASS</constant>&nbsp;</entry>
1625 <entry>class</entry>
1626 </row><row><entry spanname="descr">The Camera class
1627descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
1628description of this control class.</entry>
1629 </row>
1630 <row><entry></entry></row>
1631
1632 <row id="v4l2-exposure-auto-type">
1633 <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO</constant>&nbsp;</entry>
1634 <entry>enum&nbsp;v4l2_exposure_auto_type</entry>
1635 </row><row><entry spanname="descr">Enables automatic
1636adjustments of the exposure time and/or iris aperture. The effect of
1637manual changes of the exposure time or iris aperture while these
1638features are enabled is undefined, drivers should ignore such
1639requests. Possible values are:</entry>
1640 </row>
1641 <row>
1642 <entrytbl spanname="descr" cols="2">
1643 <tbody valign="top">
1644 <row>
1645 <entry><constant>V4L2_EXPOSURE_AUTO</constant>&nbsp;</entry>
1646 <entry>Automatic exposure time, automatic iris
1647aperture.</entry>
1648 </row>
1649 <row>
1650 <entry><constant>V4L2_EXPOSURE_MANUAL</constant>&nbsp;</entry>
1651 <entry>Manual exposure time, manual iris.</entry>
1652 </row>
1653 <row>
1654 <entry><constant>V4L2_EXPOSURE_SHUTTER_PRIORITY</constant>&nbsp;</entry>
1655 <entry>Manual exposure time, auto iris.</entry>
1656 </row>
1657 <row>
1658 <entry><constant>V4L2_EXPOSURE_APERTURE_PRIORITY</constant>&nbsp;</entry>
1659 <entry>Auto exposure time, manual iris.</entry>
1660 </row>
1661 </tbody>
1662 </entrytbl>
1663 </row>
1664 <row><entry></entry></row>
1665
1666 <row>
1667 <entry spanname="id"><constant>V4L2_CID_EXPOSURE_ABSOLUTE</constant>&nbsp;</entry>
1668 <entry>integer</entry>
1669 </row><row><entry spanname="descr">Determines the exposure
1670time of the camera sensor. The exposure time is limited by the frame
1671interval. Drivers should interpret the values as 100 &micro;s units,
1672where the value 1 stands for 1/10000th of a second, 10000 for 1 second
1673and 100000 for 10 seconds.</entry>
1674 </row>
1675 <row><entry></entry></row>
1676
1677 <row>
1678 <entry spanname="id"><constant>V4L2_CID_EXPOSURE_AUTO_PRIORITY</constant>&nbsp;</entry>
1679 <entry>boolean</entry>
1680 </row><row><entry spanname="descr">When
1681<constant>V4L2_CID_EXPOSURE_AUTO</constant> is set to
1682<constant>AUTO</constant> or <constant>APERTURE_PRIORITY</constant>,
1683this control determines if the device may dynamically vary the frame
1684rate. By default this feature is disabled (0) and the frame rate must
1685remain constant.</entry>
1686 </row>
1687 <row><entry></entry></row>
1688
1689 <row>
1690 <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant>&nbsp;</entry>
1691 <entry>integer</entry>
1692 </row><row><entry spanname="descr">This control turns the
1693camera horizontally by the specified amount. The unit is undefined. A
1694positive value moves the camera to the right (clockwise when viewed
1695from above), a negative value to the left. A value of zero does not
1696cause motion. This is a write-only control.</entry>
1697 </row>
1698 <row><entry></entry></row>
1699
1700 <row>
1701 <entry spanname="id"><constant>V4L2_CID_TILT_RELATIVE</constant>&nbsp;</entry>
1702 <entry>integer</entry>
1703 </row><row><entry spanname="descr">This control turns the
1704camera vertically by the specified amount. The unit is undefined. A
1705positive value moves the camera up, a negative value down. A value of
1706zero does not cause motion. This is a write-only control.</entry>
1707 </row>
1708 <row><entry></entry></row>
1709
1710 <row>
1711 <entry spanname="id"><constant>V4L2_CID_PAN_RESET</constant>&nbsp;</entry>
1712 <entry>button</entry>
1713 </row><row><entry spanname="descr">When this control is set,
1714the camera moves horizontally to the default position.</entry>
1715 </row>
1716 <row><entry></entry></row>
1717
1718 <row>
1719 <entry spanname="id"><constant>V4L2_CID_TILT_RESET</constant>&nbsp;</entry>
1720 <entry>button</entry>
1721 </row><row><entry spanname="descr">When this control is set,
1722the camera moves vertically to the default position.</entry>
1723 </row>
1724 <row><entry></entry></row>
1725
1726 <row>
1727 <entry spanname="id"><constant>V4L2_CID_PAN_ABSOLUTE</constant>&nbsp;</entry>
1728 <entry>integer</entry>
1729 </row><row><entry spanname="descr">This control
1730turns the camera horizontally to the specified position. Positive
1731values move the camera to the right (clockwise when viewed from above),
1732negative values to the left. Drivers should interpret the values as arc
1733seconds, with valid values between -180 * 3600 and +180 * 3600
1734inclusive.</entry>
1735 </row>
1736 <row><entry></entry></row>
1737
1738 <row>
1739 <entry spanname="id"><constant>V4L2_CID_TILT_ABSOLUTE</constant>&nbsp;</entry>
1740 <entry>integer</entry>
1741 </row><row><entry spanname="descr">This control
1742turns the camera vertically to the specified position. Positive values
1743move the camera up, negative values down. Drivers should interpret the
1744values as arc seconds, with valid values between -180 * 3600 and +180
1745* 3600 inclusive.</entry>
1746 </row>
1747 <row><entry></entry></row>
1748
1749 <row>
1750 <entry spanname="id"><constant>V4L2_CID_FOCUS_ABSOLUTE</constant>&nbsp;</entry>
1751 <entry>integer</entry>
1752 </row><row><entry spanname="descr">This control sets the
1753focal point of the camera to the specified position. The unit is
1754undefined. Positive values set the focus closer to the camera,
1755negative values towards infinity.</entry>
1756 </row>
1757 <row><entry></entry></row>
1758
1759 <row>
1760 <entry spanname="id"><constant>V4L2_CID_FOCUS_RELATIVE</constant>&nbsp;</entry>
1761 <entry>integer</entry>
1762 </row><row><entry spanname="descr">This control moves the
1763focal point of the camera by the specified amount. The unit is
1764undefined. Positive values move the focus closer to the camera,
1765negative values towards infinity. This is a write-only control.</entry>
1766 </row>
1767 <row><entry></entry></row>
1768
1769 <row>
1770 <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant>&nbsp;</entry>
1771 <entry>boolean</entry>
1772 </row><row><entry spanname="descr">Enables automatic focus
1773adjustments. The effect of manual focus adjustments while this feature
1774is enabled is undefined, drivers should ignore such requests.</entry>
1775 </row>
1776 <row><entry></entry></row>
1777
1778 <row>
1779 <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant>&nbsp;</entry>
1780 <entry>integer</entry>
1781 </row><row><entry spanname="descr">Specify the objective lens
1782focal length as an absolute value. The zoom unit is driver-specific and its
1783value should be a positive integer.</entry>
1784 </row>
1785 <row><entry></entry></row>
1786
1787 <row>
1788 <entry spanname="id"><constant>V4L2_CID_ZOOM_RELATIVE</constant>&nbsp;</entry>
1789 <entry>integer</entry>
1790 </row><row><entry spanname="descr">Specify the objective lens
1791focal length relatively to the current value. Positive values move the zoom
1792lens group towards the telephoto direction, negative values towards the
1793wide-angle direction. The zoom unit is driver-specific. This is a write-only control.</entry>
1794 </row>
1795 <row><entry></entry></row>
1796
1797 <row>
1798 <entry spanname="id"><constant>V4L2_CID_ZOOM_CONTINUOUS</constant>&nbsp;</entry>
1799 <entry>integer</entry>
1800 </row><row><entry spanname="descr">Move the objective lens group
1801at the specified speed until it reaches physical device limits or until an
1802explicit request to stop the movement. A positive value moves the zoom lens
1803group towards the telephoto direction. A value of zero stops the zoom lens
1804group movement. A negative value moves the zoom lens group towards the
1805wide-angle direction. The zoom speed unit is driver-specific.</entry>
1806 </row>
1807 <row><entry></entry></row>
1808
1809 <row>
1810 <entry spanname="id"><constant>V4L2_CID_PRIVACY</constant>&nbsp;</entry>
1811 <entry>boolean</entry>
1812 </row><row><entry spanname="descr">Prevent video from being acquired
1813by the camera. When this control is set to <constant>TRUE</constant> (1), no
1814image can be captured by the camera. Common means to enforce privacy are
1815mechanical obturation of the sensor and firmware image processing, but the
1816device is not restricted to these methods. Devices that implement the privacy
1817control must support read access and may support write access.</entry>
1818 </row>
1819
1820 <row>
1821 <entry spanname="id"><constant>V4L2_CID_BAND_STOP_FILTER</constant>&nbsp;</entry>
1822 <entry>integer</entry>
1823 </row><row><entry spanname="descr">Switch the band-stop filter of a
1824camera sensor on or off, or specify its strength. Such band-stop filters can
1825be used, for example, to filter out the fluorescent light component.</entry>
1826 </row>
1827 <row><entry></entry></row>
1828 </tbody>
1829 </tgroup>
1830 </table>
1831 </section>
1832
1833 <section id="fm-tx-controls">
1834 <title>FM Transmitter Control Reference</title>
1835
1836 <para>The FM Transmitter (FM_TX) class includes controls for common features of
1837FM transmissions capable devices. Currently this class includes parameters for audio
1838compression, pilot tone generation, audio deviation limiter, RDS transmission and
1839tuning power features.</para>
1840
1841 <table pgwide="1" frame="none" id="fm-tx-control-id">
1842 <title>FM_TX Control IDs</title>
1843
1844 <tgroup cols="4">
1845 <colspec colname="c1" colwidth="1*" />
1846 <colspec colname="c2" colwidth="6*" />
1847 <colspec colname="c3" colwidth="2*" />
1848 <colspec colname="c4" colwidth="6*" />
1849 <spanspec namest="c1" nameend="c2" spanname="id" />
1850 <spanspec namest="c2" nameend="c4" spanname="descr" />
1851 <thead>
1852 <row>
1853 <entry spanname="id" align="left">ID</entry>
1854 <entry align="left">Type</entry>
1855 </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry>
1856 </row>
1857 </thead>
1858 <tbody valign="top">
1859 <row><entry></entry></row>
1860 <row>
1861 <entry spanname="id"><constant>V4L2_CID_FM_TX_CLASS</constant>&nbsp;</entry>
1862 <entry>class</entry>
1863 </row><row><entry spanname="descr">The FM_TX class
1864descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a
1865description of this control class.</entry>
1866 </row>
1867 <row>
1868 <entry spanname="id"><constant>V4L2_CID_RDS_TX_DEVIATION</constant>&nbsp;</entry>
1869 <entry>integer</entry>
1870 </row>
1871 <row><entry spanname="descr">Configures RDS signal frequency deviation level in Hz.
1872The range and step are driver-specific.</entry>
1873 </row>
1874 <row>
1875 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PI</constant>&nbsp;</entry>
1876 <entry>integer</entry>
1877 </row>
1878 <row><entry spanname="descr">Sets the RDS Programme Identification field
1879for transmission.</entry>
1880 </row>
1881 <row>
1882 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PTY</constant>&nbsp;</entry>
1883 <entry>integer</entry>
1884 </row>
1885 <row><entry spanname="descr">Sets the RDS Programme Type field for transmission.
1886This encodes up to 31 pre-defined programme types.</entry>
1887 </row>
1888 <row>
1889 <entry spanname="id"><constant>V4L2_CID_RDS_TX_PS_NAME</constant>&nbsp;</entry>
1890 <entry>string</entry>
1891 </row>
1892 <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission.
1893It is intended for static display on a receiver. It is the primary aid to listeners in programme service
1894identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification,
1895there is a full description of the correct character encoding for Programme Service name strings.
1896Also from RDS specification, PS is usually a single eight character text. However, it is also possible
1897to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured
1898with steps of 8 characters. The result is it must always contain a string with size multiple of 8.</entry>
1899 </row>
1900 <row>
1901 <entry spanname="id"><constant>V4L2_CID_RDS_TX_RADIO_TEXT</constant>&nbsp;</entry>
1902 <entry>string</entry>
1903 </row>
1904 <row><entry spanname="descr">Sets the Radio Text info for transmission. It is a textual description of
1905what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names,
1906programme-related information or any other text. In these cases, RadioText should be used in addition to
1907<constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described
1908in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being
1909used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible
1910to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured
1911with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry>
1912 </row>
1913 <row>
1914 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_ENABLED</constant>&nbsp;</entry>
1915 <entry>boolean</entry>
1916 </row>
1917 <row><entry spanname="descr">Enables or disables the audio deviation limiter feature.
1918The limiter is useful when trying to maximize the audio volume, minimize receiver-generated
1919distortion and prevent overmodulation.
1920</entry>
1921 </row>
1922 <row>
1923 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_RELEASE_TIME</constant>&nbsp;</entry>
1924 <entry>integer</entry>
1925 </row>
1926 <row><entry spanname="descr">Sets the audio deviation limiter feature release time.
1927Unit is in useconds. Step and range are driver-specific.</entry>
1928 </row>
1929 <row>
1930 <entry spanname="id"><constant>V4L2_CID_AUDIO_LIMITER_DEVIATION</constant>&nbsp;</entry>
1931 <entry>integer</entry>
1932 </row>
1933 <row><entry spanname="descr">Configures audio frequency deviation level in Hz.
1934The range and step are driver-specific.</entry>
1935 </row>
1936 <row>
1937 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ENABLED</constant>&nbsp;</entry>
1938 <entry>boolean</entry>
1939 </row>
1940 <row><entry spanname="descr">Enables or disables the audio compression feature.
1941This feature amplifies signals below the threshold by a fixed gain and compresses audio
1942signals above the threshold by the ratio of Threshold/(Gain + Threshold).</entry>
1943 </row>
1944 <row>
1945 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_GAIN</constant>&nbsp;</entry>
1946 <entry>integer</entry>
1947 </row>
1948 <row><entry spanname="descr">Sets the gain for audio compression feature. It is
1949a dB value. The range and step are driver-specific.</entry>
1950 </row>
1951 <row>
1952 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_THRESHOLD</constant>&nbsp;</entry>
1953 <entry>integer</entry>
1954 </row>
1955 <row><entry spanname="descr">Sets the threshold level for audio compression freature.
1956It is a dB value. The range and step are driver-specific.</entry>
1957 </row>
1958 <row>
1959 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME</constant>&nbsp;</entry>
1960 <entry>integer</entry>
1961 </row>
1962 <row><entry spanname="descr">Sets the attack time for audio compression feature.
1963It is a useconds value. The range and step are driver-specific.</entry>
1964 </row>
1965 <row>
1966 <entry spanname="id"><constant>V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME</constant>&nbsp;</entry>
1967 <entry>integer</entry>
1968 </row>
1969 <row><entry spanname="descr">Sets the release time for audio compression feature.
1970It is a useconds value. The range and step are driver-specific.</entry>
1971 </row>
1972 <row>
1973 <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_ENABLED</constant>&nbsp;</entry>
1974 <entry>boolean</entry>
1975 </row>
1976 <row><entry spanname="descr">Enables or disables the pilot tone generation feature.</entry>
1977 </row>
1978 <row>
1979 <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_DEVIATION</constant>&nbsp;</entry>
1980 <entry>integer</entry>
1981 </row>
1982 <row><entry spanname="descr">Configures pilot tone frequency deviation level. Unit is
1983in Hz. The range and step are driver-specific.</entry>
1984 </row>
1985 <row>
1986 <entry spanname="id"><constant>V4L2_CID_PILOT_TONE_FREQUENCY</constant>&nbsp;</entry>
1987 <entry>integer</entry>
1988 </row>
1989 <row><entry spanname="descr">Configures pilot tone frequency value. Unit is
1990in Hz. The range and step are driver-specific.</entry>
1991 </row>
1992 <row>
1993 <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant>&nbsp;</entry>
1994 <entry>integer</entry>
1995 </row>
1996 <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting.
1997A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies.
1998Depending on the region, a time constant of either 50 or 75 useconds is used. The enum&nbsp;v4l2_preemphasis
1999defines possible values for pre-emphasis. Here they are:</entry>
2000 </row><row>
2001 <entrytbl spanname="descr" cols="2">
2002 <tbody valign="top">
2003 <row>
2004 <entry><constant>V4L2_PREEMPHASIS_DISABLED</constant>&nbsp;</entry>
2005 <entry>No pre-emphasis is applied.</entry>
2006 </row>
2007 <row>
2008 <entry><constant>V4L2_PREEMPHASIS_50_uS</constant>&nbsp;</entry>
2009 <entry>A pre-emphasis of 50 uS is used.</entry>
2010 </row>
2011 <row>
2012 <entry><constant>V4L2_PREEMPHASIS_75_uS</constant>&nbsp;</entry>
2013 <entry>A pre-emphasis of 75 uS is used.</entry>
2014 </row>
2015 </tbody>
2016 </entrytbl>
2017
2018 </row>
2019 <row>
2020 <entry spanname="id"><constant>V4L2_CID_TUNE_POWER_LEVEL</constant>&nbsp;</entry>
2021 <entry>integer</entry>
2022 </row>
2023 <row><entry spanname="descr">Sets the output power level for signal transmission.
2024Unit is in dBuV. Range and step are driver-specific.</entry>
2025 </row>
2026 <row>
2027 <entry spanname="id"><constant>V4L2_CID_TUNE_ANTENNA_CAPACITOR</constant>&nbsp;</entry>
2028 <entry>integer</entry>
2029 </row>
2030 <row><entry spanname="descr">This selects the value of antenna tuning capacitor
2031manually or automatically if set to zero. Unit, range and step are driver-specific.</entry>
2032 </row>
2033 <row><entry></entry></row>
2034 </tbody>
2035 </tgroup>
2036 </table>
2037
2038<para>For more details about RDS specification, refer to
2039<xref linkend="en50067" /> document, from CENELEC.</para>
2040 </section>
2041</section>
2042
2043 <!--
2044Local Variables:
2045mode: sgml
2046sgml-parent-document: "common.sgml"
2047indent-tabs-mode: nil
2048End:
2049 -->
diff --git a/Documentation/DocBook/v4l/crop.gif b/Documentation/DocBook/v4l/crop.gif
new file mode 100644
index 000000000000..3b9e7d836d4b
--- /dev/null
+++ b/Documentation/DocBook/v4l/crop.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/crop.pdf b/Documentation/DocBook/v4l/crop.pdf
new file mode 100644
index 000000000000..c9fb81cd32f3
--- /dev/null
+++ b/Documentation/DocBook/v4l/crop.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/dev-capture.xml b/Documentation/DocBook/v4l/dev-capture.xml
new file mode 100644
index 000000000000..32807e43f170
--- /dev/null
+++ b/Documentation/DocBook/v4l/dev-capture.xml
@@ -0,0 +1,115 @@
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> 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="overlay">video overlay</link>
25(<constant>V4L2_CAP_VIDEO_OVERLAY</constant>) and the <link
26linkend="raw-vbi">raw VBI capture</link>
27(<constant>V4L2_CAP_VBI_CAPTURE</constant>) interface. At least one of
28the read/write or streaming I/O methods must be supported. Tuners and
29audio inputs are optional.</para>
30 </section>
31
32 <section>
33 <title>Supplemental Functions</title>
34
35 <para>Video capture devices shall support <link
36linkend="audio">audio input</link>, <link
37linkend="tuner">tuner</link>, <link linkend="control">controls</link>,
38<link linkend="crop">cropping and scaling</link> and <link
39linkend="streaming-par">streaming parameter</link> ioctls as needed.
40The <link linkend="video">video input</link> and <link
41linkend="standard">video standard</link> ioctls must be supported by
42all video capture devices.</para>
43 </section>
44
45 <section>
46 <title>Image Format Negotiation</title>
47
48 <para>The result of a capture operation is determined by
49cropping and image format parameters. The former select an area of the
50video picture to capture, the latter how images are stored in memory,
51&ie; in RGB or YUV format, the number of bits per pixel or width and
52height. Together they also define how images are scaled in the
53process.</para>
54
55 <para>As usual these parameters are <emphasis>not</emphasis> reset
56at &func-open; time to permit Unix tool chains, programming a device
57and then reading from it as if it was a plain file. Well written V4L2
58applications ensure they really get what they want, including cropping
59and scaling.</para>
60
61 <para>Cropping initialization at minimum requires to reset the
62parameters to defaults. An example is given in <xref
63linkend="crop" />.</para>
64
65 <para>To query the current image format applications set the
66<structfield>type</structfield> field of a &v4l2-format; to
67<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and call the
68&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
69the &v4l2-pix-format; <structfield>pix</structfield> member of the
70<structfield>fmt</structfield> union.</para>
71
72 <para>To request different parameters applications set the
73<structfield>type</structfield> field of a &v4l2-format; as above and
74initialize all fields of the &v4l2-pix-format;
75<structfield>vbi</structfield> member of the
76<structfield>fmt</structfield> union, or better just modify the
77results of <constant>VIDIOC_G_FMT</constant>, and call the
78&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
79adjust the parameters and finally return the actual parameters as
80<constant>VIDIOC_G_FMT</constant> does.</para>
81
82 <para>Like <constant>VIDIOC_S_FMT</constant> the
83&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
84without disabling I/O or possibly time consuming hardware
85preparations.</para>
86
87 <para>The contents of &v4l2-pix-format; are discussed in <xref
88linkend="pixfmt" />. See also the specification of the
89<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
90and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
91capture devices must implement both the
92<constant>VIDIOC_G_FMT</constant> and
93<constant>VIDIOC_S_FMT</constant> ioctl, even if
94<constant>VIDIOC_S_FMT</constant> ignores all requests and always
95returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
96<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
97 </section>
98
99 <section>
100 <title>Reading Images</title>
101
102 <para>A video capture device may support the <link
103linkend="rw">read() function</link> and/or streaming (<link
104linkend="mmap">memory mapping</link> or <link
105linkend="userp">user pointer</link>) I/O. See <xref
106linkend="io" /> for details.</para>
107 </section>
108
109 <!--
110Local Variables:
111mode: sgml
112sgml-parent-document: "v4l2.sgml"
113indent-tabs-mode: nil
114End:
115 -->
diff --git a/Documentation/DocBook/v4l/dev-codec.xml b/Documentation/DocBook/v4l/dev-codec.xml
new file mode 100644
index 000000000000..6e156dc45b94
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/dev-effect.xml b/Documentation/DocBook/v4l/dev-effect.xml
new file mode 100644
index 000000000000..9c243beba0e6
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/dev-osd.xml b/Documentation/DocBook/v4l/dev-osd.xml
new file mode 100644
index 000000000000..c9a68a2ccd33
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/dev-output.xml b/Documentation/DocBook/v4l/dev-output.xml
new file mode 100644
index 000000000000..63c3c20e5a72
--- /dev/null
+++ b/Documentation/DocBook/v4l/dev-output.xml
@@ -0,0 +1,111 @@
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> flag in the
21<structfield>capabilities</structfield> field of &v4l2-capability;
22returned by the &VIDIOC-QUERYCAP; ioctl. As secondary device functions
23they may also support the <link linkend="raw-vbi">raw VBI
24output</link> (<constant>V4L2_CAP_VBI_OUTPUT</constant>) interface. At
25least one of the read/write or streaming I/O methods must be
26supported. Modulators and audio outputs are optional.</para>
27 </section>
28
29 <section>
30 <title>Supplemental Functions</title>
31
32 <para>Video output devices shall support <link
33linkend="audio">audio output</link>, <link
34linkend="tuner">modulator</link>, <link linkend="control">controls</link>,
35<link linkend="crop">cropping and scaling</link> and <link
36linkend="streaming-par">streaming parameter</link> ioctls as needed.
37The <link linkend="video">video output</link> and <link
38linkend="standard">video standard</link> ioctls must be supported by
39all video output devices.</para>
40 </section>
41
42 <section>
43 <title>Image Format Negotiation</title>
44
45 <para>The output is determined by cropping and image format
46parameters. The former select an area of the video picture where the
47image will appear, the latter how images are stored in memory, &ie; in
48RGB or YUV format, the number of bits per pixel or width and height.
49Together they also define how images are scaled in the process.</para>
50
51 <para>As usual these parameters are <emphasis>not</emphasis> reset
52at &func-open; time to permit Unix tool chains, programming a device
53and then writing to it as if it was a plain file. Well written V4L2
54applications ensure they really get what they want, including cropping
55and scaling.</para>
56
57 <para>Cropping initialization at minimum requires to reset the
58parameters to defaults. An example is given in <xref
59linkend="crop" />.</para>
60
61 <para>To query the current image format applications set the
62<structfield>type</structfield> field of a &v4l2-format; to
63<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and call the
64&VIDIOC-G-FMT; ioctl with a pointer to this structure. Drivers fill
65the &v4l2-pix-format; <structfield>pix</structfield> member of the
66<structfield>fmt</structfield> union.</para>
67
68 <para>To request different parameters applications set the
69<structfield>type</structfield> field of a &v4l2-format; as above and
70initialize all fields of the &v4l2-pix-format;
71<structfield>vbi</structfield> member of the
72<structfield>fmt</structfield> union, or better just modify the
73results of <constant>VIDIOC_G_FMT</constant>, and call the
74&VIDIOC-S-FMT; ioctl with a pointer to this structure. Drivers may
75adjust the parameters and finally return the actual parameters as
76<constant>VIDIOC_G_FMT</constant> does.</para>
77
78 <para>Like <constant>VIDIOC_S_FMT</constant> the
79&VIDIOC-TRY-FMT; ioctl can be used to learn about hardware limitations
80without disabling I/O or possibly time consuming hardware
81preparations.</para>
82
83 <para>The contents of &v4l2-pix-format; are discussed in <xref
84linkend="pixfmt" />. See also the specification of the
85<constant>VIDIOC_G_FMT</constant>, <constant>VIDIOC_S_FMT</constant>
86and <constant>VIDIOC_TRY_FMT</constant> ioctls for details. Video
87output devices must implement both the
88<constant>VIDIOC_G_FMT</constant> and
89<constant>VIDIOC_S_FMT</constant> ioctl, even if
90<constant>VIDIOC_S_FMT</constant> ignores all requests and always
91returns default parameters as <constant>VIDIOC_G_FMT</constant> does.
92<constant>VIDIOC_TRY_FMT</constant> is optional.</para>
93 </section>
94
95 <section>
96 <title>Writing Images</title>
97
98 <para>A video output device may support the <link
99linkend="rw">write() function</link> and/or streaming (<link
100linkend="mmap">memory mapping</link> or <link
101linkend="userp">user pointer</link>) I/O. See <xref
102linkend="io" /> for details.</para>
103 </section>
104
105 <!--
106Local Variables:
107mode: sgml
108sgml-parent-document: "v4l2.sgml"
109indent-tabs-mode: nil
110End:
111 -->
diff --git a/Documentation/DocBook/v4l/dev-overlay.xml b/Documentation/DocBook/v4l/dev-overlay.xml
new file mode 100644
index 000000000000..92513cf79150
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/dev-radio.xml b/Documentation/DocBook/v4l/dev-radio.xml
new file mode 100644
index 000000000000..73aa90b45b34
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/dev-raw-vbi.xml b/Documentation/DocBook/v4l/dev-raw-vbi.xml
new file mode 100644
index 000000000000..c5a70bdfaf27
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/dev-rds.xml b/Documentation/DocBook/v4l/dev-rds.xml
new file mode 100644
index 000000000000..0869d701b1e5
--- /dev/null
+++ b/Documentation/DocBook/v4l/dev-rds.xml
@@ -0,0 +1,168 @@
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 decoding 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 can also handle RBDS. Only some of the fields
14have slightly different meanings. See the RBDS standard for more information.</para>
15
16 <para>The RBDS standard also specifies support for MMBS (Modified Mobile Search).
17This is a proprietary format which seems to be discontinued. The RDS interface does not
18support this format. Should support for MMBS (or the so-called 'E blocks' in general)
19be needed, then please contact the linux-media mailing list: &v4l-ml;.</para>
20
21 <section>
22 <title>Querying Capabilities</title>
23
24 <para>Devices supporting the RDS capturing API
25set the <constant>V4L2_CAP_RDS_CAPTURE</constant> flag in
26the <structfield>capabilities</structfield> field of &v4l2-capability;
27returned by the &VIDIOC-QUERYCAP; ioctl.
28Any tuner that supports RDS will set the
29<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
30field of &v4l2-tuner;.
31Whether an RDS signal is present can be detected by looking at
32the <structfield>rxsubchans</structfield> field of &v4l2-tuner;: the
33<constant>V4L2_TUNER_SUB_RDS</constant> will be set if RDS data was detected.</para>
34
35 <para>Devices supporting the RDS output API
36set the <constant>V4L2_CAP_RDS_OUTPUT</constant> flag in
37the <structfield>capabilities</structfield> field of &v4l2-capability;
38returned by the &VIDIOC-QUERYCAP; ioctl.
39Any modulator that supports RDS will set the
40<constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield>
41field of &v4l2-modulator;.
42In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant>
43bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;.</para>
44
45 </section>
46
47 <section>
48 <title>Reading RDS data</title>
49
50 <para>RDS data can be read from the radio device
51with the &func-read; function. The data is packed in groups of three bytes,
52as follows:</para>
53 <table frame="none" pgwide="1" id="v4l2-rds-data">
54 <title>struct
55<structname>v4l2_rds_data</structname></title>
56 <tgroup cols="3">
57 <colspec colname="c1" colwidth="1*" />
58 <colspec colname="c2" colwidth="1*" />
59 <colspec colname="c3" colwidth="5*" />
60 <tbody valign="top">
61 <row>
62 <entry>__u8</entry>
63 <entry><structfield>lsb</structfield></entry>
64 <entry>Least Significant Byte of RDS Block</entry>
65 </row>
66 <row>
67 <entry>__u8</entry>
68 <entry><structfield>msb</structfield></entry>
69 <entry>Most Significant Byte of RDS Block</entry>
70 </row>
71 <row>
72 <entry>__u8</entry>
73 <entry><structfield>block</structfield></entry>
74 <entry>Block description</entry>
75 </row>
76 </tbody>
77 </tgroup>
78 </table>
79 <table frame="none" pgwide="1" id="v4l2-rds-block">
80 <title>Block description</title>
81 <tgroup cols="2">
82 <colspec colname="c1" colwidth="1*" />
83 <colspec colname="c2" colwidth="5*" />
84 <tbody valign="top">
85 <row>
86 <entry>Bits 0-2</entry>
87 <entry>Block (aka offset) of the received data.</entry>
88 </row>
89 <row>
90 <entry>Bits 3-5</entry>
91 <entry>Deprecated. Currently identical to bits 0-2. Do not use these bits.</entry>
92 </row>
93 <row>
94 <entry>Bit 6</entry>
95 <entry>Corrected bit. Indicates that an error was corrected for this data block.</entry>
96 </row>
97 <row>
98 <entry>Bit 7</entry>
99 <entry>Error bit. Indicates that an uncorrectable error occurred during reception of this block.</entry>
100 </row>
101 </tbody>
102 </tgroup>
103 </table>
104
105 <table frame="none" pgwide="1" id="v4l2-rds-block-codes">
106 <title>Block defines</title>
107 <tgroup cols="3">
108 <colspec colname="c1" colwidth="1*" />
109 <colspec colname="c2" colwidth="1*" />
110 <colspec colname="c3" colwidth="5*" />
111 <tbody valign="top">
112 <row>
113 <entry>V4L2_RDS_BLOCK_MSK</entry>
114 <entry>7</entry>
115 <entry>Mask for bits 0-2 to get the block ID.</entry>
116 </row>
117 <row>
118 <entry>V4L2_RDS_BLOCK_A</entry>
119 <entry>0</entry>
120 <entry>Block A.</entry>
121 </row>
122 <row>
123 <entry>V4L2_RDS_BLOCK_B</entry>
124 <entry>1</entry>
125 <entry>Block B.</entry>
126 </row>
127 <row>
128 <entry>V4L2_RDS_BLOCK_C</entry>
129 <entry>2</entry>
130 <entry>Block C.</entry>
131 </row>
132 <row>
133 <entry>V4L2_RDS_BLOCK_D</entry>
134 <entry>3</entry>
135 <entry>Block D.</entry>
136 </row>
137 <row>
138 <entry>V4L2_RDS_BLOCK_C_ALT</entry>
139 <entry>4</entry>
140 <entry>Block C'.</entry>
141 </row>
142 <row>
143 <entry>V4L2_RDS_BLOCK_INVALID</entry>
144 <entry>7</entry>
145 <entry>An invalid block.</entry>
146 </row>
147 <row>
148 <entry>V4L2_RDS_BLOCK_CORRECTED</entry>
149 <entry>0x40</entry>
150 <entry>A bit error was detected but corrected.</entry>
151 </row>
152 <row>
153 <entry>V4L2_RDS_BLOCK_ERROR</entry>
154 <entry>0x80</entry>
155 <entry>An incorrectable error occurred.</entry>
156 </row>
157 </tbody>
158 </tgroup>
159 </table>
160 </section>
161
162<!--
163Local Variables:
164mode: sgml
165sgml-parent-document: "v4l2.sgml"
166indent-tabs-mode: nil
167End:
168 -->
diff --git a/Documentation/DocBook/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/v4l/dev-sliced-vbi.xml
new file mode 100644
index 000000000000..69e789fa7f7b
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/dev-teletext.xml b/Documentation/DocBook/v4l/dev-teletext.xml
new file mode 100644
index 000000000000..59f9993e1489
--- /dev/null
+++ b/Documentation/DocBook/v4l/dev-teletext.xml
@@ -0,0 +1,40 @@
1 <title>Teletext Interface</title>
2
3 <para>This interface aims 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 can be found on older
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 is defined in
12the kernel header file <filename>linux/videotext.h</filename>, the
13specification is available from <ulink url="http://home.pages.de/~videotext/">
14http://home.pages.de/~videotext/</ulink>. (Videotext is the name of
15the German public television Teletext service.) Conventional character
16device file names are <filename>/dev/vtx</filename> and
17<filename>/dev/vttuner</filename>, with device number 83, 0 and 83, 16
18respectively. A similar interface exists for the Philips SAA5249
19Teletext decoder [specification?] with character device file names
20<filename>/dev/tlkN</filename>, device number 102, N.</para>
21
22 <para>Eventually the Teletext API was integrated into the V4L API
23with character device file names <filename>/dev/vtx0</filename> to
24<filename>/dev/vtx31</filename>, device major number 81, minor numbers
25192 to 223. For reference the V4L Teletext API specification is
26reproduced here in full: "Teletext interfaces talk the existing VTX
27API." Teletext devices with major number 83 and 102 will be removed in
28Linux 2.6.</para>
29
30 <para>There are no plans to replace the Teletext API or to integrate
31it into V4L2. Please write to the linux-media mailing list: &v4l-ml;
32when the need arises.</para>
33
34 <!--
35Local Variables:
36mode: sgml
37sgml-parent-document: "v4l2.sgml"
38indent-tabs-mode: nil
39End:
40 -->
diff --git a/Documentation/DocBook/v4l/driver.xml b/Documentation/DocBook/v4l/driver.xml
new file mode 100644
index 000000000000..1f7eea5c4ec3
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/fdl-appendix.xml b/Documentation/DocBook/v4l/fdl-appendix.xml
new file mode 100644
index 000000000000..b6ce50dbe492
--- /dev/null
+++ b/Documentation/DocBook/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://developer.gnome.org/projects/gdp
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/v4l/fieldseq_bt.gif b/Documentation/DocBook/v4l/fieldseq_bt.gif
new file mode 100644
index 000000000000..60e8569a76c9
--- /dev/null
+++ b/Documentation/DocBook/v4l/fieldseq_bt.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/fieldseq_bt.pdf b/Documentation/DocBook/v4l/fieldseq_bt.pdf
new file mode 100644
index 000000000000..26598b23f80d
--- /dev/null
+++ b/Documentation/DocBook/v4l/fieldseq_bt.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/fieldseq_tb.gif b/Documentation/DocBook/v4l/fieldseq_tb.gif
new file mode 100644
index 000000000000..718492f1cfc7
--- /dev/null
+++ b/Documentation/DocBook/v4l/fieldseq_tb.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/fieldseq_tb.pdf b/Documentation/DocBook/v4l/fieldseq_tb.pdf
new file mode 100644
index 000000000000..4965b22ddb3a
--- /dev/null
+++ b/Documentation/DocBook/v4l/fieldseq_tb.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/func-close.xml b/Documentation/DocBook/v4l/func-close.xml
new file mode 100644
index 000000000000..dfb41cbbbec3
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/func-ioctl.xml b/Documentation/DocBook/v4l/func-ioctl.xml
new file mode 100644
index 000000000000..00f9690e1c28
--- /dev/null
+++ b/Documentation/DocBook/v4l/func-ioctl.xml
@@ -0,0 +1,146 @@
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 <link
38linkend="videodev">videodev.h</link> header file, for example
39VIDIOC_QUERYCAP.</para>
40 </listitem>
41 </varlistentry>
42 <varlistentry>
43 <term><parameter>argp</parameter></term>
44 <listitem>
45 <para>Pointer to a function parameter, usually a structure.</para>
46 </listitem>
47 </varlistentry>
48 </variablelist>
49 </refsect1>
50
51 <refsect1>
52 <title>Description</title>
53
54 <para>The <function>ioctl()</function> function is used to program
55V4L2 devices. The argument <parameter>fd</parameter> must be an open
56file descriptor. An ioctl <parameter>request</parameter> has encoded
57in it whether the argument is an input, output or read/write
58parameter, and the size of the argument <parameter>argp</parameter> in
59bytes. Macros and defines specifying V4L2 ioctl requests are located
60in the <link linkend="videodev">videodev.h</link> header file.
61Applications should use their own copy, not include the version in the
62kernel sources on the system they compile on. All V4L2 ioctl requests,
63their respective function and parameters are specified in <xref
64 linkend="user-func" />.</para>
65 </refsect1>
66
67 <refsect1>
68 <title>Return Value</title>
69
70 <para>On success the <function>ioctl()</function> function returns
71<returnvalue>0</returnvalue> and does not reset the
72<varname>errno</varname> variable. On failure
73<returnvalue>-1</returnvalue> is returned, when the ioctl takes an
74output or read/write parameter it remains unmodified, and the
75<varname>errno</varname> variable is set appropriately. See below for
76possible error codes. Generic errors like <errorcode>EBADF</errorcode>
77or <errorcode>EFAULT</errorcode> are not listed in the sections
78discussing individual ioctl requests.</para>
79 <para>Note ioctls may return undefined error codes. Since errors
80may have side effects such as a driver reset applications should
81abort on unexpected errors.</para>
82
83 <variablelist>
84 <varlistentry>
85 <term><errorcode>EBADF</errorcode></term>
86 <listitem>
87 <para><parameter>fd</parameter> is not a valid open file
88descriptor.</para>
89 </listitem>
90 </varlistentry>
91 <varlistentry>
92 <term><errorcode>EBUSY</errorcode></term>
93 <listitem>
94 <para>The property cannot be changed right now. Typically
95this error code is returned when I/O is in progress or the driver
96supports multiple opens and another process locked the property.</para>
97 </listitem>
98 </varlistentry>
99 <varlistentry>
100 <term><errorcode>EFAULT</errorcode></term>
101 <listitem>
102 <para><parameter>argp</parameter> references an inaccessible
103memory area.</para>
104 </listitem>
105 </varlistentry>
106 <varlistentry>
107 <term><errorcode>ENOTTY</errorcode></term>
108 <listitem>
109 <para><parameter>fd</parameter> is not associated with a
110character special device.</para>
111 </listitem>
112 </varlistentry>
113 <varlistentry>
114 <term><errorcode>EINVAL</errorcode></term>
115 <listitem>
116 <para>The <parameter>request</parameter> or the data pointed
117to by <parameter>argp</parameter> is not valid. This is a very common
118error code, see the individual ioctl requests listed in <xref
119 linkend="user-func" /> for actual causes.</para>
120 </listitem>
121 </varlistentry>
122 <varlistentry>
123 <term><errorcode>ENOMEM</errorcode></term>
124 <listitem>
125 <para>Not enough physical or virtual memory was available to
126complete the request.</para>
127 </listitem>
128 </varlistentry>
129 <varlistentry>
130 <term><errorcode>ERANGE</errorcode></term>
131 <listitem>
132 <para>The application attempted to set a control with the
133&VIDIOC-S-CTRL; ioctl to a value which is out of bounds.</para>
134 </listitem>
135 </varlistentry>
136 </variablelist>
137 </refsect1>
138</refentry>
139
140<!--
141Local Variables:
142mode: sgml
143sgml-parent-document: "v4l2.sgml"
144indent-tabs-mode: nil
145End:
146-->
diff --git a/Documentation/DocBook/v4l/func-mmap.xml b/Documentation/DocBook/v4l/func-mmap.xml
new file mode 100644
index 000000000000..2e2fc3933aea
--- /dev/null
+++ b/Documentation/DocBook/v4l/func-mmap.xml
@@ -0,0 +1,185 @@
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.</para>
49 </listitem>
50 </varlistentry>
51 <varlistentry>
52 <term><parameter>prot</parameter></term>
53 <listitem>
54 <para>The <parameter>prot</parameter> argument describes the
55desired memory protection. Regardless of the device type and the
56direction of data exchange it should be set to
57<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>,
58permitting read and write access to image buffers. Drivers should
59support at least this combination of flags. Note the Linux
60<filename>video-buf</filename> kernel module, which is used by the
61bttv, saa7134, saa7146, cx88 and vivi driver supports only
62<constant>PROT_READ</constant> | <constant>PROT_WRITE</constant>. When
63the driver does not support the desired protection the
64<function>mmap()</function> function fails.</para>
65 <para>Note device memory accesses (&eg; the memory on a
66graphics card with video capturing hardware) may incur a performance
67penalty compared to main memory accesses, or reads may be
68significantly slower than writes or vice versa. Other I/O methods may
69be more efficient in this case.</para>
70 </listitem>
71 </varlistentry>
72 <varlistentry>
73 <term><parameter>flags</parameter></term>
74 <listitem>
75 <para>The <parameter>flags</parameter> parameter
76specifies the type of the mapped object, mapping options and whether
77modifications made to the mapped copy of the page are private to the
78process or are to be shared with other references.</para>
79 <para><constant>MAP_FIXED</constant> requests that the
80driver selects no other address than the one specified. If the
81specified address cannot be used, <function>mmap()</function> will fail. If
82<constant>MAP_FIXED</constant> is specified,
83<parameter>start</parameter> must be a multiple of the pagesize. Use
84of this option is discouraged.</para>
85 <para>One of the <constant>MAP_SHARED</constant> or
86<constant>MAP_PRIVATE</constant> flags must be set.
87<constant>MAP_SHARED</constant> allows applications to share the
88mapped memory with other (&eg; child-) processes. Note the Linux
89<filename>video-buf</filename> module which is used by the bttv,
90saa7134, saa7146, cx88 and vivi driver supports only
91<constant>MAP_SHARED</constant>. <constant>MAP_PRIVATE</constant>
92requests copy-on-write semantics. V4L2 applications should not set the
93<constant>MAP_PRIVATE</constant>, <constant>MAP_DENYWRITE</constant>,
94<constant>MAP_EXECUTABLE</constant> or <constant>MAP_ANON</constant>
95flag.</para>
96 </listitem>
97 </varlistentry>
98 <varlistentry>
99 <term><parameter>fd</parameter></term>
100 <listitem>
101 <para>&fd;</para>
102 </listitem>
103 </varlistentry>
104 <varlistentry>
105 <term><parameter>offset</parameter></term>
106 <listitem>
107 <para>Offset of the buffer in device memory. This must be the
108same value as returned by the driver in the &v4l2-buffer;
109<structfield>m</structfield> union <structfield>offset</structfield> field.</para>
110 </listitem>
111 </varlistentry>
112 </variablelist>
113 </refsect1>
114
115 <refsect1>
116 <title>Description</title>
117
118 <para>The <function>mmap()</function> function asks to map
119<parameter>length</parameter> bytes starting at
120<parameter>offset</parameter> in the memory of the device specified by
121<parameter>fd</parameter> into the application address space,
122preferably at address <parameter>start</parameter>. This latter
123address is a hint only, and is usually specified as 0.</para>
124
125 <para>Suitable length and offset parameters are queried with the
126&VIDIOC-QUERYBUF; ioctl. Buffers must be allocated with the
127&VIDIOC-REQBUFS; ioctl before they can be queried.</para>
128
129 <para>To unmap buffers the &func-munmap; function is used.</para>
130 </refsect1>
131
132 <refsect1>
133 <title>Return Value</title>
134
135 <para>On success <function>mmap()</function> returns a pointer to
136the mapped buffer. On error <constant>MAP_FAILED</constant> (-1) is
137returned, and the <varname>errno</varname> variable is set
138appropriately. Possible error codes are:</para>
139
140 <variablelist>
141 <varlistentry>
142 <term><errorcode>EBADF</errorcode></term>
143 <listitem>
144 <para><parameter>fd</parameter> is not a valid file
145descriptor.</para>
146 </listitem>
147 </varlistentry>
148 <varlistentry>
149 <term><errorcode>EACCES</errorcode></term>
150 <listitem>
151 <para><parameter>fd</parameter> is
152not open for reading and writing.</para>
153 </listitem>
154 </varlistentry>
155 <varlistentry>
156 <term><errorcode>EINVAL</errorcode></term>
157 <listitem>
158 <para>The <parameter>start</parameter> or
159<parameter>length</parameter> or <parameter>offset</parameter> are not
160suitable. (E.&nbsp;g. they are too large, or not aligned on a
161<constant>PAGESIZE</constant> boundary.)</para>
162 <para>The <parameter>flags</parameter> or
163<parameter>prot</parameter> value is not supported.</para>
164 <para>No buffers have been allocated with the
165&VIDIOC-REQBUFS; ioctl.</para>
166 </listitem>
167 </varlistentry>
168 <varlistentry>
169 <term><errorcode>ENOMEM</errorcode></term>
170 <listitem>
171 <para>Not enough physical or virtual memory was available to
172complete the request.</para>
173 </listitem>
174 </varlistentry>
175 </variablelist>
176 </refsect1>
177</refentry>
178
179<!--
180Local Variables:
181mode: sgml
182sgml-parent-document: "v4l2.sgml"
183indent-tabs-mode: nil
184End:
185-->
diff --git a/Documentation/DocBook/v4l/func-munmap.xml b/Documentation/DocBook/v4l/func-munmap.xml
new file mode 100644
index 000000000000..502ed49323b0
--- /dev/null
+++ b/Documentation/DocBook/v4l/func-munmap.xml
@@ -0,0 +1,83 @@
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.</para>
41 </listitem>
42 </varlistentry>
43 </variablelist>
44 </refsect1>
45
46 <refsect1>
47 <title>Description</title>
48
49 <para>Unmaps a previously with the &func-mmap; function mapped
50buffer and frees it, if possible. <!-- ? This function (not freeing)
51has no impact on I/O in progress, specifically it does not imply
52&VIDIOC-STREAMOFF; to terminate I/O. Unmapped buffers can still be
53enqueued, dequeued or queried, they are just not accessible by the
54application.--></para>
55 </refsect1>
56
57 <refsect1>
58 <title>Return Value</title>
59
60 <para>On success <function>munmap()</function> returns 0, on
61failure -1 and the <varname>errno</varname> variable is set
62appropriately:</para>
63
64 <variablelist>
65 <varlistentry>
66 <term><errorcode>EINVAL</errorcode></term>
67 <listitem>
68 <para>The <parameter>start</parameter> or
69<parameter>length</parameter> is incorrect, or no buffers have been
70mapped yet.</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/v4l/func-open.xml b/Documentation/DocBook/v4l/func-open.xml
new file mode 100644
index 000000000000..7595d07a8c72
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/func-poll.xml b/Documentation/DocBook/v4l/func-poll.xml
new file mode 100644
index 000000000000..ec3c718f5963
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/func-read.xml b/Documentation/DocBook/v4l/func-read.xml
new file mode 100644
index 000000000000..a5089bf8873d
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/func-select.xml b/Documentation/DocBook/v4l/func-select.xml
new file mode 100644
index 000000000000..b6713623181f
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/func-write.xml b/Documentation/DocBook/v4l/func-write.xml
new file mode 100644
index 000000000000..2c09c09371c3
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/io.xml b/Documentation/DocBook/v4l/io.xml
new file mode 100644
index 000000000000..f92f24323b2a
--- /dev/null
+++ b/Documentation/DocBook/v4l/io.xml
@@ -0,0 +1,1073 @@
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. The <structfield>m.offset</structfield> and
125<structfield>length</structfield> returned in a &v4l2-buffer; are
126passed as sixth and second parameter to the
127<function>mmap()</function> function. The offset and length values
128must not be modified. Remember the buffers are allocated in physical
129memory, as opposed to virtual memory which can be swapped out to disk.
130Applications should free the buffers as soon as possible with the
131&func-munmap; function.</para>
132
133 <example>
134 <title>Mapping buffers</title>
135
136 <programlisting>
137&v4l2-requestbuffers; reqbuf;
138struct {
139 void *start;
140 size_t length;
141} *buffers;
142unsigned int i;
143
144memset (&amp;reqbuf, 0, sizeof (reqbuf));
145reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
146reqbuf.memory = V4L2_MEMORY_MMAP;
147reqbuf.count = 20;
148
149if (-1 == ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf)) {
150 if (errno == EINVAL)
151 printf ("Video capturing or mmap-streaming is not supported\n");
152 else
153 perror ("VIDIOC_REQBUFS");
154
155 exit (EXIT_FAILURE);
156}
157
158/* We want at least five buffers. */
159
160if (reqbuf.count &lt; 5) {
161 /* You may need to free the buffers here. */
162 printf ("Not enough buffer memory\n");
163 exit (EXIT_FAILURE);
164}
165
166buffers = calloc (reqbuf.count, sizeof (*buffers));
167assert (buffers != NULL);
168
169for (i = 0; i &lt; reqbuf.count; i++) {
170 &v4l2-buffer; buffer;
171
172 memset (&amp;buffer, 0, sizeof (buffer));
173 buffer.type = reqbuf.type;
174 buffer.memory = V4L2_MEMORY_MMAP;
175 buffer.index = i;
176
177 if (-1 == ioctl (fd, &VIDIOC-QUERYBUF;, &amp;buffer)) {
178 perror ("VIDIOC_QUERYBUF");
179 exit (EXIT_FAILURE);
180 }
181
182 buffers[i].length = buffer.length; /* remember for munmap() */
183
184 buffers[i].start = mmap (NULL, buffer.length,
185 PROT_READ | PROT_WRITE, /* recommended */
186 MAP_SHARED, /* recommended */
187 fd, buffer.m.offset);
188
189 if (MAP_FAILED == buffers[i].start) {
190 /* If you do not exit here you should unmap() and free()
191 the buffers mapped so far. */
192 perror ("mmap");
193 exit (EXIT_FAILURE);
194 }
195}
196
197/* Cleanup. */
198
199for (i = 0; i &lt; reqbuf.count; i++)
200 munmap (buffers[i].start, buffers[i].length);
201 </programlisting>
202 </example>
203
204 <para>Conceptually streaming drivers maintain two buffer queues, an incoming
205and an outgoing queue. They separate the synchronous capture or output
206operation locked to a video clock from the application which is
207subject to random disk or network delays and preemption by
208other processes, thereby reducing the probability of data loss.
209The queues are organized as FIFOs, buffers will be
210output in the order enqueued in the incoming FIFO, and were
211captured in the order dequeued from the outgoing FIFO.</para>
212
213 <para>The driver may require a minimum number of buffers enqueued
214at all times to function, apart of this no limit exists on the number
215of buffers applications can enqueue in advance, or dequeue and
216process. They can also enqueue in a different order than buffers have
217been dequeued, and the driver can <emphasis>fill</emphasis> enqueued
218<emphasis>empty</emphasis> buffers in any order. <footnote>
219 <para>Random enqueue order permits applications processing
220images out of order (such as video codecs) to return buffers earlier,
221reducing the probability of data loss. Random fill order allows
222drivers to reuse buffers on a LIFO-basis, taking advantage of caches
223holding scatter-gather lists and the like.</para>
224 </footnote> The index number of a buffer (&v4l2-buffer;
225<structfield>index</structfield>) plays no role here, it only
226identifies the buffer.</para>
227
228 <para>Initially all mapped buffers are in dequeued state,
229inaccessible by the driver. For capturing applications it is customary
230to first enqueue all mapped buffers, then to start capturing and enter
231the read loop. Here the application waits until a filled buffer can be
232dequeued, and re-enqueues the buffer when the data is no longer
233needed. Output applications fill and enqueue buffers, when enough
234buffers are stacked up the output is started with
235<constant>VIDIOC_STREAMON</constant>. In the write loop, when
236the application runs out of free buffers, it must wait until an empty
237buffer can be dequeued and reused.</para>
238
239 <para>To enqueue and dequeue a buffer applications use the
240&VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. The status of a buffer being
241mapped, enqueued, full or empty can be determined at any time using the
242&VIDIOC-QUERYBUF; ioctl. Two methods exist to suspend execution of the
243application until one or more buffers can be dequeued. By default
244<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
245outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
246given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
247returns immediately with an &EAGAIN; when no buffer is available. The
248&func-select; or &func-poll; function are always available.</para>
249
250 <para>To start and stop capturing or output applications call the
251&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
252<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
253queues as a side effect. Since there is no notion of doing anything
254"now" on a multitasking system, if an application needs to synchronize
255with another event it should examine the &v4l2-buffer;
256<structfield>timestamp</structfield> of captured buffers, or set the
257field before enqueuing buffers for output.</para>
258
259 <para>Drivers implementing memory mapping I/O must
260support the <constant>VIDIOC_REQBUFS</constant>,
261<constant>VIDIOC_QUERYBUF</constant>,
262<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
263<constant>VIDIOC_STREAMON</constant> and
264<constant>VIDIOC_STREAMOFF</constant> ioctl, the
265<function>mmap()</function>, <function>munmap()</function>,
266<function>select()</function> and <function>poll()</function>
267function.<footnote>
268 <para>At the driver level <function>select()</function> and
269<function>poll()</function> are the same, and
270<function>select()</function> is too important to be optional. The
271rest should be evident.</para>
272 </footnote></para>
273
274 <para>[capture example]</para>
275
276 </section>
277
278 <section id="userp">
279 <title>Streaming I/O (User Pointers)</title>
280
281 <para>Input and output devices support this I/O method when the
282<constant>V4L2_CAP_STREAMING</constant> flag in the
283<structfield>capabilities</structfield> field of &v4l2-capability;
284returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
285pointer method (not only memory mapping) is supported must be
286determined by calling the &VIDIOC-REQBUFS; ioctl.</para>
287
288 <para>This I/O method combines advantages of the read/write and
289memory mapping methods. Buffers are allocated by the application
290itself, and can reside for example in virtual or shared memory. Only
291pointers to data are exchanged, these pointers and meta-information
292are passed in &v4l2-buffer;. The driver must be switched
293into user pointer I/O mode by calling the &VIDIOC-REQBUFS; with the
294desired buffer type. No buffers are allocated beforehands,
295consequently they are not indexed and cannot be queried like mapped
296buffers with the <constant>VIDIOC_QUERYBUF</constant> ioctl.</para>
297
298 <example>
299 <title>Initiating streaming I/O with user pointers</title>
300
301 <programlisting>
302&v4l2-requestbuffers; reqbuf;
303
304memset (&amp;reqbuf, 0, sizeof (reqbuf));
305reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
306reqbuf.memory = V4L2_MEMORY_USERPTR;
307
308if (ioctl (fd, &VIDIOC-REQBUFS;, &amp;reqbuf) == -1) {
309 if (errno == EINVAL)
310 printf ("Video capturing or user pointer streaming is not supported\n");
311 else
312 perror ("VIDIOC_REQBUFS");
313
314 exit (EXIT_FAILURE);
315}
316 </programlisting>
317 </example>
318
319 <para>Buffer addresses and sizes are passed on the fly with the
320&VIDIOC-QBUF; ioctl. Although buffers are commonly cycled,
321applications can pass different addresses and sizes at each
322<constant>VIDIOC_QBUF</constant> call. If required by the hardware the
323driver swaps memory pages within physical memory to create a
324continuous area of memory. This happens transparently to the
325application in the virtual memory subsystem of the kernel. When buffer
326pages have been swapped out to disk they are brought back and finally
327locked in physical memory for DMA.<footnote>
328 <para>We expect that frequently used buffers are typically not
329swapped out. Anyway, the process of swapping, locking or generating
330scatter-gather lists may be time consuming. The delay can be masked by
331the depth of the incoming buffer queue, and perhaps by maintaining
332caches assuming a buffer will be soon enqueued again. On the other
333hand, to optimize memory usage drivers can limit the number of buffers
334locked in advance and recycle the most recently used buffers first. Of
335course, the pages of empty buffers in the incoming queue need not be
336saved to disk. Output buffers must be saved on the incoming and
337outgoing queue because an application may share them with other
338processes.</para>
339 </footnote></para>
340
341 <para>Filled or displayed buffers are dequeued with the
342&VIDIOC-DQBUF; ioctl. The driver can unlock the memory pages at any
343time between the completion of the DMA and this ioctl. The memory is
344also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or
345when the device is closed. Applications must take care not to free
346buffers without dequeuing. For once, the buffers remain locked until
347further, wasting physical memory. Second the driver will not be
348notified when the memory is returned to the application's free list
349and subsequently reused for other purposes, possibly completing the
350requested DMA and overwriting valuable data.</para>
351
352 <para>For capturing applications it is customary to enqueue a
353number of empty buffers, to start capturing and enter the read loop.
354Here the application waits until a filled buffer can be dequeued, and
355re-enqueues the buffer when the data is no longer needed. Output
356applications fill and enqueue buffers, when enough buffers are stacked
357up output is started. In the write loop, when the application
358runs out of free buffers it must wait until an empty buffer can be
359dequeued and reused. Two methods exist to suspend execution of the
360application until one or more buffers can be dequeued. By default
361<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the
362outgoing queue. When the <constant>O_NONBLOCK</constant> flag was
363given to the &func-open; function, <constant>VIDIOC_DQBUF</constant>
364returns immediately with an &EAGAIN; when no buffer is available. The
365&func-select; or &func-poll; function are always available.</para>
366
367 <para>To start and stop capturing or output applications call the
368&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note
369<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both
370queues and unlocks all buffers as a side effect. Since there is no
371notion of doing anything "now" on a multitasking system, if an
372application needs to synchronize with another event it should examine
373the &v4l2-buffer; <structfield>timestamp</structfield> of captured
374buffers, or set the field before enqueuing buffers for output.</para>
375
376 <para>Drivers implementing user pointer I/O must
377support the <constant>VIDIOC_REQBUFS</constant>,
378<constant>VIDIOC_QBUF</constant>, <constant>VIDIOC_DQBUF</constant>,
379<constant>VIDIOC_STREAMON</constant> and
380<constant>VIDIOC_STREAMOFF</constant> ioctl, the
381<function>select()</function> and <function>poll()</function> function.<footnote>
382 <para>At the driver level <function>select()</function> and
383<function>poll()</function> are the same, and
384<function>select()</function> is too important to be optional. The
385rest should be evident.</para>
386 </footnote></para>
387 </section>
388
389 <section id="async">
390 <title>Asynchronous I/O</title>
391
392 <para>This method is not defined yet.</para>
393 </section>
394
395 <section id="buffer">
396 <title>Buffers</title>
397
398 <para>A buffer contains data exchanged by application and
399driver using one of the Streaming I/O methods. Only pointers to
400buffers are exchanged, the data itself is not copied. These pointers,
401together with meta-information like timestamps or field parity, are
402stored in a struct <structname>v4l2_buffer</structname>, argument to
403the &VIDIOC-QUERYBUF;, &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl.</para>
404
405 <para>Nominally timestamps refer to the first data byte transmitted.
406In practice however the wide range of hardware covered by the V4L2 API
407limits timestamp accuracy. Often an interrupt routine will
408sample the system clock shortly after the field or frame was stored
409completely in memory. So applications must expect a constant
410difference up to one field or frame period plus a small (few scan
411lines) random error. The delay and error can be much
412larger due to compression or transmission over an external bus when
413the frames are not properly stamped by the sender. This is frequently
414the case with USB cameras. Here timestamps refer to the instant the
415field or frame was received by the driver, not the capture time. These
416devices identify by not enumerating any video standards, see <xref
417linkend="standard" />.</para>
418
419 <para>Similar limitations apply to output timestamps. Typically
420the video hardware locks to a clock controlling the video timing, the
421horizontal and vertical synchronization pulses. At some point in the
422line sequence, possibly the vertical blanking, an interrupt routine
423samples the system clock, compares against the timestamp and programs
424the hardware to repeat the previous field or frame, or to display the
425buffer contents.</para>
426
427 <para>Apart of limitations of the video device and natural
428inaccuracies of all clocks, it should be noted system time itself is
429not perfectly stable. It can be affected by power saving cycles,
430warped to insert leap seconds, or even turned back or forth by the
431system administrator affecting long term measurements. <footnote>
432 <para>Since no other Linux multimedia
433API supports unadjusted time it would be foolish to introduce here. We
434must use a universally supported clock to synchronize different media,
435hence time of day.</para>
436 </footnote></para>
437
438 <table frame="none" pgwide="1" id="v4l2-buffer">
439 <title>struct <structname>v4l2_buffer</structname></title>
440 <tgroup cols="4">
441 &cs-ustr;
442 <tbody valign="top">
443 <row>
444 <entry>__u32</entry>
445 <entry><structfield>index</structfield></entry>
446 <entry></entry>
447 <entry>Number of the buffer, set by the application. This
448field is only used for <link linkend="mmap">memory mapping</link> I/O
449and can range from zero to the number of buffers allocated
450with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry>
451 </row>
452 <row>
453 <entry>&v4l2-buf-type;</entry>
454 <entry><structfield>type</structfield></entry>
455 <entry></entry>
456 <entry>Type of the buffer, same as &v4l2-format;
457<structfield>type</structfield> or &v4l2-requestbuffers;
458<structfield>type</structfield>, set by the application.</entry>
459 </row>
460 <row>
461 <entry>__u32</entry>
462 <entry><structfield>bytesused</structfield></entry>
463 <entry></entry>
464 <entry>The number of bytes occupied by the data in the
465buffer. It depends on the negotiated data format and may change with
466each buffer for compressed variable size data like JPEG images.
467Drivers must set this field when <structfield>type</structfield>
468refers to an input stream, applications when an output stream.</entry>
469 </row>
470 <row>
471 <entry>__u32</entry>
472 <entry><structfield>flags</structfield></entry>
473 <entry></entry>
474 <entry>Flags set by the application or driver, see <xref
475linkend="buffer-flags" />.</entry>
476 </row>
477 <row>
478 <entry>&v4l2-field;</entry>
479 <entry><structfield>field</structfield></entry>
480 <entry></entry>
481 <entry>Indicates the field order of the image in the
482buffer, see <xref linkend="v4l2-field" />. This field is not used when
483the buffer contains VBI data. Drivers must set it when
484<structfield>type</structfield> refers to an input stream,
485applications when an output stream.</entry>
486 </row>
487 <row>
488 <entry>struct timeval</entry>
489 <entry><structfield>timestamp</structfield></entry>
490 <entry></entry>
491 <entry><para>For input streams this is the
492system time (as returned by the <function>gettimeofday()</function>
493function) when the first data byte was captured. For output streams
494the data will not be displayed before this time, secondary to the
495nominal frame rate determined by the current video standard in
496enqueued order. Applications can for example zero this field to
497display frames as soon as possible. The driver stores the time at
498which the first data byte was actually sent out in the
499<structfield>timestamp</structfield> field. This permits
500applications to monitor the drift between the video and system
501clock.</para></entry>
502 </row>
503 <row>
504 <entry>&v4l2-timecode;</entry>
505 <entry><structfield>timecode</structfield></entry>
506 <entry></entry>
507 <entry>When <structfield>type</structfield> is
508<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant> and the
509<constant>V4L2_BUF_FLAG_TIMECODE</constant> flag is set in
510<structfield>flags</structfield>, this structure contains a frame
511timecode. In <link linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link>
512mode the top and bottom field contain the same timecode.
513Timecodes are intended to help video editing and are typically recorded on
514video tapes, but also embedded in compressed formats like MPEG. This
515field is independent of the <structfield>timestamp</structfield> and
516<structfield>sequence</structfield> fields.</entry>
517 </row>
518 <row>
519 <entry>__u32</entry>
520 <entry><structfield>sequence</structfield></entry>
521 <entry></entry>
522 <entry>Set by the driver, counting the frames in the
523sequence.</entry>
524 </row>
525 <row>
526 <entry spanname="hspan"><para>In <link
527linkend="v4l2-field">V4L2_FIELD_ALTERNATE</link> mode the top and
528bottom field have the same sequence number. The count starts at zero
529and includes dropped or repeated frames. A dropped frame was received
530by an input device but could not be stored due to lack of free buffer
531space. A repeated frame was displayed again by an output device
532because the application did not pass new data in
533time.</para><para>Note this may count the frames received
534e.g. over USB, without taking into account the frames dropped by the
535remote hardware due to limited compression throughput or bus
536bandwidth. These devices identify by not enumerating any video
537standards, see <xref linkend="standard" />.</para></entry>
538 </row>
539 <row>
540 <entry>&v4l2-memory;</entry>
541 <entry><structfield>memory</structfield></entry>
542 <entry></entry>
543 <entry>This field must be set by applications and/or drivers
544in accordance with the selected I/O method.</entry>
545 </row>
546 <row>
547 <entry>union</entry>
548 <entry><structfield>m</structfield></entry>
549 </row>
550 <row>
551 <entry></entry>
552 <entry>__u32</entry>
553 <entry><structfield>offset</structfield></entry>
554 <entry>When <structfield>memory</structfield> is
555<constant>V4L2_MEMORY_MMAP</constant> this is the offset of the buffer
556from the start of the device memory. The value is returned by the
557driver and apart of serving as parameter to the &func-mmap; function
558not useful for applications. See <xref linkend="mmap" /> for details.</entry>
559 </row>
560 <row>
561 <entry></entry>
562 <entry>unsigned long</entry>
563 <entry><structfield>userptr</structfield></entry>
564 <entry>When <structfield>memory</structfield> is
565<constant>V4L2_MEMORY_USERPTR</constant> this is a pointer to the
566buffer (casted to unsigned long type) in virtual memory, set by the
567application. See <xref linkend="userp" /> for details.</entry>
568 </row>
569 <row>
570 <entry>__u32</entry>
571 <entry><structfield>length</structfield></entry>
572 <entry></entry>
573 <entry>Size of the buffer (not the payload) in bytes.</entry>
574 </row>
575 <row>
576 <entry>__u32</entry>
577 <entry><structfield>input</structfield></entry>
578 <entry></entry>
579 <entry>Some video capture drivers support rapid and
580synchronous video input changes, a function useful for example in
581video surveillance applications. For this purpose applications set the
582<constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the
583number of a video input as in &v4l2-input; field
584<structfield>index</structfield>.</entry>
585 </row>
586 <row>
587 <entry>__u32</entry>
588 <entry><structfield>reserved</structfield></entry>
589 <entry></entry>
590 <entry>A place holder for future extensions and custom
591(driver defined) buffer types
592<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry>
593 </row>
594 </tbody>
595 </tgroup>
596 </table>
597
598 <table frame="none" pgwide="1" id="v4l2-buf-type">
599 <title>enum v4l2_buf_type</title>
600 <tgroup cols="3">
601 &cs-def;
602 <tbody valign="top">
603 <row>
604 <entry><constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant></entry>
605 <entry>1</entry>
606 <entry>Buffer of a video capture stream, see <xref
607 linkend="capture" />.</entry>
608 </row>
609 <row>
610 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant></entry>
611 <entry>2</entry>
612 <entry>Buffer of a video output stream, see <xref
613 linkend="output" />.</entry>
614 </row>
615 <row>
616 <entry><constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant></entry>
617 <entry>3</entry>
618 <entry>Buffer for video overlay, see <xref linkend="overlay" />.</entry>
619 </row>
620 <row>
621 <entry><constant>V4L2_BUF_TYPE_VBI_CAPTURE</constant></entry>
622 <entry>4</entry>
623 <entry>Buffer of a raw VBI capture stream, see <xref
624 linkend="raw-vbi" />.</entry>
625 </row>
626 <row>
627 <entry><constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant></entry>
628 <entry>5</entry>
629 <entry>Buffer of a raw VBI output stream, see <xref
630 linkend="raw-vbi" />.</entry>
631 </row>
632 <row>
633 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant></entry>
634 <entry>6</entry>
635 <entry>Buffer of a sliced VBI capture stream, see <xref
636 linkend="sliced" />.</entry>
637 </row>
638 <row>
639 <entry><constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant></entry>
640 <entry>7</entry>
641 <entry>Buffer of a sliced VBI output stream, see <xref
642 linkend="sliced" />.</entry>
643 </row>
644 <row>
645 <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry>
646 <entry>8</entry>
647 <entry>Buffer for video output overlay (OSD), see <xref
648 linkend="osd" />. Status: <link
649linkend="experimental">Experimental</link>.</entry>
650 </row>
651 <row>
652 <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry>
653 <entry>0x80</entry>
654 <entry>This and higher values are reserved for custom
655(driver defined) buffer types.</entry>
656 </row>
657 </tbody>
658 </tgroup>
659 </table>
660
661 <table frame="none" pgwide="1" id="buffer-flags">
662 <title>Buffer Flags</title>
663 <tgroup cols="3">
664 &cs-def;
665 <tbody valign="top">
666 <row>
667 <entry><constant>V4L2_BUF_FLAG_MAPPED</constant></entry>
668 <entry>0x0001</entry>
669 <entry>The buffer resides in device memory and has been mapped
670into the application's address space, see <xref linkend="mmap" /> for details.
671Drivers set or clear this flag when the
672<link linkend="vidioc-querybuf">VIDIOC_QUERYBUF</link>, <link
673 linkend="vidioc-qbuf">VIDIOC_QBUF</link> or <link
674 linkend="vidioc-qbuf">VIDIOC_DQBUF</link> ioctl is called. Set by the driver.</entry>
675 </row>
676 <row>
677 <entry><constant>V4L2_BUF_FLAG_QUEUED</constant></entry>
678 <entry>0x0002</entry>
679 <entry>Internally drivers maintain two buffer queues, an
680incoming and outgoing queue. When this flag is set, the buffer is
681currently on the incoming queue. It automatically moves to the
682outgoing queue after the buffer has been filled (capture devices) or
683displayed (output devices). Drivers set or clear this flag when the
684<constant>VIDIOC_QUERYBUF</constant> ioctl is called. After
685(successful) calling the <constant>VIDIOC_QBUF </constant>ioctl it is
686always set and after <constant>VIDIOC_DQBUF</constant> always
687cleared.</entry>
688 </row>
689 <row>
690 <entry><constant>V4L2_BUF_FLAG_DONE</constant></entry>
691 <entry>0x0004</entry>
692 <entry>When this flag is set, the buffer is currently on
693the outgoing queue, ready to be dequeued from the driver. Drivers set
694or clear this flag when the <constant>VIDIOC_QUERYBUF</constant> ioctl
695is called. After calling the <constant>VIDIOC_QBUF</constant> or
696<constant>VIDIOC_DQBUF</constant> it is always cleared. Of course a
697buffer cannot be on both queues at the same time, the
698<constant>V4L2_BUF_FLAG_QUEUED</constant> and
699<constant>V4L2_BUF_FLAG_DONE</constant> flag are mutually exclusive.
700They can be both cleared however, then the buffer is in "dequeued"
701state, in the application domain to say so.</entry>
702 </row>
703 <row>
704 <entry><constant>V4L2_BUF_FLAG_KEYFRAME</constant></entry>
705 <entry>0x0008</entry>
706 <entry>Drivers set or clear this flag when calling the
707<constant>VIDIOC_DQBUF</constant> ioctl. It may be set by video
708capture devices when the buffer contains a compressed image which is a
709key frame (or field), &ie; can be decompressed on its own.</entry>
710 </row>
711 <row>
712 <entry><constant>V4L2_BUF_FLAG_PFRAME</constant></entry>
713 <entry>0x0010</entry>
714 <entry>Similar to <constant>V4L2_BUF_FLAG_KEYFRAME</constant>
715this flags predicted frames or fields which contain only differences to a
716previous key frame.</entry>
717 </row>
718 <row>
719 <entry><constant>V4L2_BUF_FLAG_BFRAME</constant></entry>
720 <entry>0x0020</entry>
721 <entry>Similar to <constant>V4L2_BUF_FLAG_PFRAME</constant>
722 this is a bidirectional predicted frame or field. [ooc tbd]</entry>
723 </row>
724 <row>
725 <entry><constant>V4L2_BUF_FLAG_TIMECODE</constant></entry>
726 <entry>0x0100</entry>
727 <entry>The <structfield>timecode</structfield> field is valid.
728Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant>
729ioctl is called.</entry>
730 </row>
731 <row>
732 <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry>
733 <entry>0x0200</entry>
734 <entry>The <structfield>input</structfield> field is valid.
735Applications set or clear this flag before calling the
736<constant>VIDIOC_QBUF</constant> ioctl.</entry>
737 </row>
738 </tbody>
739 </tgroup>
740 </table>
741
742 <table pgwide="1" frame="none" id="v4l2-memory">
743 <title>enum v4l2_memory</title>
744 <tgroup cols="3">
745 &cs-def;
746 <tbody valign="top">
747 <row>
748 <entry><constant>V4L2_MEMORY_MMAP</constant></entry>
749 <entry>1</entry>
750 <entry>The buffer is used for <link linkend="mmap">memory
751mapping</link> I/O.</entry>
752 </row>
753 <row>
754 <entry><constant>V4L2_MEMORY_USERPTR</constant></entry>
755 <entry>2</entry>
756 <entry>The buffer is used for <link linkend="userp">user
757pointer</link> I/O.</entry>
758 </row>
759 <row>
760 <entry><constant>V4L2_MEMORY_OVERLAY</constant></entry>
761 <entry>3</entry>
762 <entry>[to do]</entry>
763 </row>
764 </tbody>
765 </tgroup>
766 </table>
767
768 <section>
769 <title>Timecodes</title>
770
771 <para>The <structname>v4l2_timecode</structname> structure is
772designed to hold a <xref linkend="smpte12m" /> or similar timecode.
773(struct <structname>timeval</structname> timestamps are stored in
774&v4l2-buffer; field <structfield>timestamp</structfield>.)</para>
775
776 <table frame="none" pgwide="1" id="v4l2-timecode">
777 <title>struct <structname>v4l2_timecode</structname></title>
778 <tgroup cols="3">
779 &cs-str;
780 <tbody valign="top">
781 <row>
782 <entry>__u32</entry>
783 <entry><structfield>type</structfield></entry>
784 <entry>Frame rate the timecodes are based on, see <xref
785 linkend="timecode-type" />.</entry>
786 </row>
787 <row>
788 <entry>__u32</entry>
789 <entry><structfield>flags</structfield></entry>
790 <entry>Timecode flags, see <xref linkend="timecode-flags" />.</entry>
791 </row>
792 <row>
793 <entry>__u8</entry>
794 <entry><structfield>frames</structfield></entry>
795 <entry>Frame count, 0 ... 23/24/29/49/59, depending on the
796 type of timecode.</entry>
797 </row>
798 <row>
799 <entry>__u8</entry>
800 <entry><structfield>seconds</structfield></entry>
801 <entry>Seconds count, 0 ... 59. This is a binary, not BCD number.</entry>
802 </row>
803 <row>
804 <entry>__u8</entry>
805 <entry><structfield>minutes</structfield></entry>
806 <entry>Minutes count, 0 ... 59. This is a binary, not BCD number.</entry>
807 </row>
808 <row>
809 <entry>__u8</entry>
810 <entry><structfield>hours</structfield></entry>
811 <entry>Hours count, 0 ... 29. This is a binary, not BCD number.</entry>
812 </row>
813 <row>
814 <entry>__u8</entry>
815 <entry><structfield>userbits</structfield>[4]</entry>
816 <entry>The "user group" bits from the timecode.</entry>
817 </row>
818 </tbody>
819 </tgroup>
820 </table>
821
822 <table frame="none" pgwide="1" id="timecode-type">
823 <title>Timecode Types</title>
824 <tgroup cols="3">
825 &cs-def;
826 <tbody valign="top">
827 <row>
828 <entry><constant>V4L2_TC_TYPE_24FPS</constant></entry>
829 <entry>1</entry>
830 <entry>24 frames per second, i.&nbsp;e. film.</entry>
831 </row>
832 <row>
833 <entry><constant>V4L2_TC_TYPE_25FPS</constant></entry>
834 <entry>2</entry>
835 <entry>25 frames per second, &ie; PAL or SECAM video.</entry>
836 </row>
837 <row>
838 <entry><constant>V4L2_TC_TYPE_30FPS</constant></entry>
839 <entry>3</entry>
840 <entry>30 frames per second, &ie; NTSC video.</entry>
841 </row>
842 <row>
843 <entry><constant>V4L2_TC_TYPE_50FPS</constant></entry>
844 <entry>4</entry>
845 <entry></entry>
846 </row>
847 <row>
848 <entry><constant>V4L2_TC_TYPE_60FPS</constant></entry>
849 <entry>5</entry>
850 <entry></entry>
851 </row>
852 </tbody>
853 </tgroup>
854 </table>
855
856 <table frame="none" pgwide="1" id="timecode-flags">
857 <title>Timecode Flags</title>
858 <tgroup cols="3">
859 &cs-def;
860 <tbody valign="top">
861 <row>
862 <entry><constant>V4L2_TC_FLAG_DROPFRAME</constant></entry>
863 <entry>0x0001</entry>
864 <entry>Indicates "drop frame" semantics for counting frames
865in 29.97 fps material. When set, frame numbers 0 and 1 at the start of
866each minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the
867count.</entry>
868 </row>
869 <row>
870 <entry><constant>V4L2_TC_FLAG_COLORFRAME</constant></entry>
871 <entry>0x0002</entry>
872 <entry>The "color frame" flag.</entry>
873 </row>
874 <row>
875 <entry><constant>V4L2_TC_USERBITS_field</constant></entry>
876 <entry>0x000C</entry>
877 <entry>Field mask for the "binary group flags".</entry>
878 </row>
879 <row>
880 <entry><constant>V4L2_TC_USERBITS_USERDEFINED</constant></entry>
881 <entry>0x0000</entry>
882 <entry>Unspecified format.</entry>
883 </row>
884 <row>
885 <entry><constant>V4L2_TC_USERBITS_8BITCHARS</constant></entry>
886 <entry>0x0008</entry>
887 <entry>8-bit ISO characters.</entry>
888 </row>
889 </tbody>
890 </tgroup>
891 </table>
892 </section>
893 </section>
894
895 <section id="field-order">
896 <title>Field Order</title>
897
898 <para>We have to distinguish between progressive and interlaced
899video. Progressive video transmits all lines of a video image
900sequentially. Interlaced video divides an image into two fields,
901containing only the odd and even lines of the image, respectively.
902Alternating the so called odd and even field are transmitted, and due
903to a small delay between fields a cathode ray TV displays the lines
904interleaved, yielding the original frame. This curious technique was
905invented because at refresh rates similar to film the image would
906fade out too quickly. Transmitting fields reduces the flicker without
907the necessity of doubling the frame rate and with it the bandwidth
908required for each channel.</para>
909
910 <para>It is important to understand a video camera does not expose
911one frame at a time, merely transmitting the frames separated into
912fields. The fields are in fact captured at two different instances in
913time. An object on screen may well move between one field and the
914next. For applications analysing motion it is of paramount importance
915to recognize which field of a frame is older, the <emphasis>temporal
916order</emphasis>.</para>
917
918 <para>When the driver provides or accepts images field by field
919rather than interleaved, it is also important applications understand
920how the fields combine to frames. We distinguish between top and
921bottom fields, the <emphasis>spatial order</emphasis>: The first line
922of the top field is the first line of an interlaced frame, the first
923line of the bottom field is the second line of that frame.</para>
924
925 <para>However because fields were captured one after the other,
926arguing whether a frame commences with the top or bottom field is
927pointless. Any two successive top and bottom, or bottom and top fields
928yield a valid frame. Only when the source was progressive to begin
929with, &eg; when transferring film to video, two fields may come from
930the same frame, creating a natural order.</para>
931
932 <para>Counter to intuition the top field is not necessarily the
933older field. Whether the older field contains the top or bottom lines
934is a convention determined by the video standard. Hence the
935distinction between temporal and spatial order of fields. The diagrams
936below should make this clearer.</para>
937
938 <para>All video capture and output devices must report the current
939field order. Some drivers may permit the selection of a different
940order, to this end applications initialize the
941<structfield>field</structfield> field of &v4l2-pix-format; before
942calling the &VIDIOC-S-FMT; ioctl. If this is not desired it should
943have the value <constant>V4L2_FIELD_ANY</constant> (0).</para>
944
945 <table frame="none" pgwide="1" id="v4l2-field">
946 <title>enum v4l2_field</title>
947 <tgroup cols="3">
948 &cs-def;
949 <tbody valign="top">
950 <row>
951 <entry><constant>V4L2_FIELD_ANY</constant></entry>
952 <entry>0</entry>
953 <entry>Applications request this field order when any
954one of the <constant>V4L2_FIELD_NONE</constant>,
955<constant>V4L2_FIELD_TOP</constant>,
956<constant>V4L2_FIELD_BOTTOM</constant>, or
957<constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable.
958Drivers choose depending on hardware capabilities or e.&nbsp;g. the
959requested image size, and return the actual field order. &v4l2-buffer;
960<structfield>field</structfield> can never be
961<constant>V4L2_FIELD_ANY</constant>.</entry>
962 </row>
963 <row>
964 <entry><constant>V4L2_FIELD_NONE</constant></entry>
965 <entry>1</entry>
966 <entry>Images are in progressive format, not interlaced.
967The driver may also indicate this order when it cannot distinguish
968between <constant>V4L2_FIELD_TOP</constant> and
969<constant>V4L2_FIELD_BOTTOM</constant>.</entry>
970 </row>
971 <row>
972 <entry><constant>V4L2_FIELD_TOP</constant></entry>
973 <entry>2</entry>
974 <entry>Images consist of the top field only.</entry>
975 </row>
976 <row>
977 <entry><constant>V4L2_FIELD_BOTTOM</constant></entry>
978 <entry>3</entry>
979 <entry>Images consist of the bottom field only.
980Applications may wish to prevent a device from capturing interlaced
981images because they will have "comb" or "feathering" artefacts around
982moving objects.</entry>
983 </row>
984 <row>
985 <entry><constant>V4L2_FIELD_INTERLACED</constant></entry>
986 <entry>4</entry>
987 <entry>Images contain both fields, interleaved line by
988line. The temporal order of the fields (whether the top or bottom
989field is first transmitted) depends on the current video standard.
990M/NTSC transmits the bottom field first, all other standards the top
991field first.</entry>
992 </row>
993 <row>
994 <entry><constant>V4L2_FIELD_SEQ_TB</constant></entry>
995 <entry>5</entry>
996 <entry>Images contain both fields, the top field lines
997are stored first in memory, immediately followed by the bottom field
998lines. Fields are always stored in temporal order, the older one first
999in memory. Image sizes refer to the frame, not fields.</entry>
1000 </row>
1001 <row>
1002 <entry><constant>V4L2_FIELD_SEQ_BT</constant></entry>
1003 <entry>6</entry>
1004 <entry>Images contain both fields, the bottom field
1005lines are stored first in memory, immediately followed by the top
1006field lines. Fields are always stored in temporal order, the older one
1007first in memory. Image sizes refer to the frame, not fields.</entry>
1008 </row>
1009 <row>
1010 <entry><constant>V4L2_FIELD_ALTERNATE</constant></entry>
1011 <entry>7</entry>
1012 <entry>The two fields of a frame are passed in separate
1013buffers, in temporal order, &ie; the older one first. To indicate the field
1014parity (whether the current field is a top or bottom field) the driver
1015or application, depending on data direction, must set &v4l2-buffer;
1016<structfield>field</structfield> to
1017<constant>V4L2_FIELD_TOP</constant> or
1018<constant>V4L2_FIELD_BOTTOM</constant>. Any two successive fields pair
1019to build a frame. If fields are successive, without any dropped fields
1020between them (fields can drop individually), can be determined from
1021the &v4l2-buffer; <structfield>sequence</structfield> field. Image
1022sizes refer to the frame, not fields. This format cannot be selected
1023when using the read/write I/O method.<!-- Where it's indistinguishable
1024from V4L2_FIELD_SEQ_*. --></entry>
1025 </row>
1026 <row>
1027 <entry><constant>V4L2_FIELD_INTERLACED_TB</constant></entry>
1028 <entry>8</entry>
1029 <entry>Images contain both fields, interleaved line by
1030line, top field first. The top field is transmitted first.</entry>
1031 </row>
1032 <row>
1033 <entry><constant>V4L2_FIELD_INTERLACED_BT</constant></entry>
1034 <entry>9</entry>
1035 <entry>Images contain both fields, interleaved line by
1036line, top field first. The bottom field is transmitted first.</entry>
1037 </row>
1038 </tbody>
1039 </tgroup>
1040 </table>
1041
1042 <figure id="fieldseq-tb">
1043 <title>Field Order, Top Field First Transmitted</title>
1044 <mediaobject>
1045 <imageobject>
1046 <imagedata fileref="fieldseq_tb.pdf" format="PS" />
1047 </imageobject>
1048 <imageobject>
1049 <imagedata fileref="fieldseq_tb.gif" format="GIF" />
1050 </imageobject>
1051 </mediaobject>
1052 </figure>
1053
1054 <figure id="fieldseq-bt">
1055 <title>Field Order, Bottom Field First Transmitted</title>
1056 <mediaobject>
1057 <imageobject>
1058 <imagedata fileref="fieldseq_bt.pdf" format="PS" />
1059 </imageobject>
1060 <imageobject>
1061 <imagedata fileref="fieldseq_bt.gif" format="GIF" />
1062 </imageobject>
1063 </mediaobject>
1064 </figure>
1065 </section>
1066
1067 <!--
1068Local Variables:
1069mode: sgml
1070sgml-parent-document: "v4l2.sgml"
1071indent-tabs-mode: nil
1072End:
1073 -->
diff --git a/Documentation/DocBook/v4l/keytable.c.xml b/Documentation/DocBook/v4l/keytable.c.xml
new file mode 100644
index 000000000000..d53254a3be15
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/libv4l.xml b/Documentation/DocBook/v4l/libv4l.xml
new file mode 100644
index 000000000000..c14fc3db2a81
--- /dev/null
+++ b/Documentation/DocBook/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 occured 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/v4l/pixfmt-grey.xml b/Documentation/DocBook/v4l/pixfmt-grey.xml
new file mode 100644
index 000000000000..3b72bc6b2de7
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-nv12.xml b/Documentation/DocBook/v4l/pixfmt-nv12.xml
new file mode 100644
index 000000000000..873f67035181
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-nv16.xml b/Documentation/DocBook/v4l/pixfmt-nv16.xml
new file mode 100644
index 000000000000..26094035fc04
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml
new file mode 100644
index 000000000000..d2dd697a81d8
--- /dev/null
+++ b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml
@@ -0,0 +1,862 @@
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-BGR24">
244 <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
245 <entry>'BGR3'</entry>
246 <entry></entry>
247 <entry>b<subscript>7</subscript></entry>
248 <entry>b<subscript>6</subscript></entry>
249 <entry>b<subscript>5</subscript></entry>
250 <entry>b<subscript>4</subscript></entry>
251 <entry>b<subscript>3</subscript></entry>
252 <entry>b<subscript>2</subscript></entry>
253 <entry>b<subscript>1</subscript></entry>
254 <entry>b<subscript>0</subscript></entry>
255 <entry></entry>
256 <entry>g<subscript>7</subscript></entry>
257 <entry>g<subscript>6</subscript></entry>
258 <entry>g<subscript>5</subscript></entry>
259 <entry>g<subscript>4</subscript></entry>
260 <entry>g<subscript>3</subscript></entry>
261 <entry>g<subscript>2</subscript></entry>
262 <entry>g<subscript>1</subscript></entry>
263 <entry>g<subscript>0</subscript></entry>
264 <entry></entry>
265 <entry>r<subscript>7</subscript></entry>
266 <entry>r<subscript>6</subscript></entry>
267 <entry>r<subscript>5</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 id="V4L2-PIX-FMT-RGB24">
275 <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
276 <entry>'RGB3'</entry>
277 <entry></entry>
278 <entry>r<subscript>7</subscript></entry>
279 <entry>r<subscript>6</subscript></entry>
280 <entry>r<subscript>5</subscript></entry>
281 <entry>r<subscript>4</subscript></entry>
282 <entry>r<subscript>3</subscript></entry>
283 <entry>r<subscript>2</subscript></entry>
284 <entry>r<subscript>1</subscript></entry>
285 <entry>r<subscript>0</subscript></entry>
286 <entry></entry>
287 <entry>g<subscript>7</subscript></entry>
288 <entry>g<subscript>6</subscript></entry>
289 <entry>g<subscript>5</subscript></entry>
290 <entry>g<subscript>4</subscript></entry>
291 <entry>g<subscript>3</subscript></entry>
292 <entry>g<subscript>2</subscript></entry>
293 <entry>g<subscript>1</subscript></entry>
294 <entry>g<subscript>0</subscript></entry>
295 <entry></entry>
296 <entry>b<subscript>7</subscript></entry>
297 <entry>b<subscript>6</subscript></entry>
298 <entry>b<subscript>5</subscript></entry>
299 <entry>b<subscript>4</subscript></entry>
300 <entry>b<subscript>3</subscript></entry>
301 <entry>b<subscript>2</subscript></entry>
302 <entry>b<subscript>1</subscript></entry>
303 <entry>b<subscript>0</subscript></entry>
304 </row>
305 <row id="V4L2-PIX-FMT-BGR32">
306 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
307 <entry>'BGR4'</entry>
308 <entry></entry>
309 <entry>b<subscript>7</subscript></entry>
310 <entry>b<subscript>6</subscript></entry>
311 <entry>b<subscript>5</subscript></entry>
312 <entry>b<subscript>4</subscript></entry>
313 <entry>b<subscript>3</subscript></entry>
314 <entry>b<subscript>2</subscript></entry>
315 <entry>b<subscript>1</subscript></entry>
316 <entry>b<subscript>0</subscript></entry>
317 <entry></entry>
318 <entry>g<subscript>7</subscript></entry>
319 <entry>g<subscript>6</subscript></entry>
320 <entry>g<subscript>5</subscript></entry>
321 <entry>g<subscript>4</subscript></entry>
322 <entry>g<subscript>3</subscript></entry>
323 <entry>g<subscript>2</subscript></entry>
324 <entry>g<subscript>1</subscript></entry>
325 <entry>g<subscript>0</subscript></entry>
326 <entry></entry>
327 <entry>r<subscript>7</subscript></entry>
328 <entry>r<subscript>6</subscript></entry>
329 <entry>r<subscript>5</subscript></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></entry>
336 <entry>a<subscript>7</subscript></entry>
337 <entry>a<subscript>6</subscript></entry>
338 <entry>a<subscript>5</subscript></entry>
339 <entry>a<subscript>4</subscript></entry>
340 <entry>a<subscript>3</subscript></entry>
341 <entry>a<subscript>2</subscript></entry>
342 <entry>a<subscript>1</subscript></entry>
343 <entry>a<subscript>0</subscript></entry>
344 </row>
345 <row id="V4L2-PIX-FMT-RGB32">
346 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
347 <entry>'RGB4'</entry>
348 <entry></entry>
349 <entry>r<subscript>7</subscript></entry>
350 <entry>r<subscript>6</subscript></entry>
351 <entry>r<subscript>5</subscript></entry>
352 <entry>r<subscript>4</subscript></entry>
353 <entry>r<subscript>3</subscript></entry>
354 <entry>r<subscript>2</subscript></entry>
355 <entry>r<subscript>1</subscript></entry>
356 <entry>r<subscript>0</subscript></entry>
357 <entry></entry>
358 <entry>g<subscript>7</subscript></entry>
359 <entry>g<subscript>6</subscript></entry>
360 <entry>g<subscript>5</subscript></entry>
361 <entry>g<subscript>4</subscript></entry>
362 <entry>g<subscript>3</subscript></entry>
363 <entry>g<subscript>2</subscript></entry>
364 <entry>g<subscript>1</subscript></entry>
365 <entry>g<subscript>0</subscript></entry>
366 <entry></entry>
367 <entry>b<subscript>7</subscript></entry>
368 <entry>b<subscript>6</subscript></entry>
369 <entry>b<subscript>5</subscript></entry>
370 <entry>b<subscript>4</subscript></entry>
371 <entry>b<subscript>3</subscript></entry>
372 <entry>b<subscript>2</subscript></entry>
373 <entry>b<subscript>1</subscript></entry>
374 <entry>b<subscript>0</subscript></entry>
375 <entry></entry>
376 <entry>a<subscript>7</subscript></entry>
377 <entry>a<subscript>6</subscript></entry>
378 <entry>a<subscript>5</subscript></entry>
379 <entry>a<subscript>4</subscript></entry>
380 <entry>a<subscript>3</subscript></entry>
381 <entry>a<subscript>2</subscript></entry>
382 <entry>a<subscript>1</subscript></entry>
383 <entry>a<subscript>0</subscript></entry>
384 </row>
385 </tbody>
386 </tgroup>
387 </table>
388
389 <para>Bit 7 is the most significant bit. The value of a = alpha
390bits is undefined when reading from the driver, ignored when writing
391to the driver, except when alpha blending has been negotiated for a
392<link linkend="overlay">Video Overlay</link> or <link
393linkend="osd">Video Output Overlay</link>.</para>
394
395 <example>
396 <title><constant>V4L2_PIX_FMT_BGR24</constant> 4 &times; 4 pixel
397image</title>
398
399 <formalpara>
400 <title>Byte Order.</title>
401 <para>Each cell is one byte.
402 <informaltable frame="none">
403 <tgroup cols="13" align="center">
404 <colspec align="left" colwidth="2*" />
405 <tbody valign="top">
406 <row>
407 <entry>start&nbsp;+&nbsp;0:</entry>
408 <entry>B<subscript>00</subscript></entry>
409 <entry>G<subscript>00</subscript></entry>
410 <entry>R<subscript>00</subscript></entry>
411 <entry>B<subscript>01</subscript></entry>
412 <entry>G<subscript>01</subscript></entry>
413 <entry>R<subscript>01</subscript></entry>
414 <entry>B<subscript>02</subscript></entry>
415 <entry>G<subscript>02</subscript></entry>
416 <entry>R<subscript>02</subscript></entry>
417 <entry>B<subscript>03</subscript></entry>
418 <entry>G<subscript>03</subscript></entry>
419 <entry>R<subscript>03</subscript></entry>
420 </row>
421 <row>
422 <entry>start&nbsp;+&nbsp;12:</entry>
423 <entry>B<subscript>10</subscript></entry>
424 <entry>G<subscript>10</subscript></entry>
425 <entry>R<subscript>10</subscript></entry>
426 <entry>B<subscript>11</subscript></entry>
427 <entry>G<subscript>11</subscript></entry>
428 <entry>R<subscript>11</subscript></entry>
429 <entry>B<subscript>12</subscript></entry>
430 <entry>G<subscript>12</subscript></entry>
431 <entry>R<subscript>12</subscript></entry>
432 <entry>B<subscript>13</subscript></entry>
433 <entry>G<subscript>13</subscript></entry>
434 <entry>R<subscript>13</subscript></entry>
435 </row>
436 <row>
437 <entry>start&nbsp;+&nbsp;24:</entry>
438 <entry>B<subscript>20</subscript></entry>
439 <entry>G<subscript>20</subscript></entry>
440 <entry>R<subscript>20</subscript></entry>
441 <entry>B<subscript>21</subscript></entry>
442 <entry>G<subscript>21</subscript></entry>
443 <entry>R<subscript>21</subscript></entry>
444 <entry>B<subscript>22</subscript></entry>
445 <entry>G<subscript>22</subscript></entry>
446 <entry>R<subscript>22</subscript></entry>
447 <entry>B<subscript>23</subscript></entry>
448 <entry>G<subscript>23</subscript></entry>
449 <entry>R<subscript>23</subscript></entry>
450 </row>
451 <row>
452 <entry>start&nbsp;+&nbsp;36:</entry>
453 <entry>B<subscript>30</subscript></entry>
454 <entry>G<subscript>30</subscript></entry>
455 <entry>R<subscript>30</subscript></entry>
456 <entry>B<subscript>31</subscript></entry>
457 <entry>G<subscript>31</subscript></entry>
458 <entry>R<subscript>31</subscript></entry>
459 <entry>B<subscript>32</subscript></entry>
460 <entry>G<subscript>32</subscript></entry>
461 <entry>R<subscript>32</subscript></entry>
462 <entry>B<subscript>33</subscript></entry>
463 <entry>G<subscript>33</subscript></entry>
464 <entry>R<subscript>33</subscript></entry>
465 </row>
466 </tbody>
467 </tgroup>
468 </informaltable>
469 </para>
470 </formalpara>
471 </example>
472
473 <important>
474 <para>Drivers may interpret these formats differently.</para>
475 </important>
476
477 <para>Some RGB formats above are uncommon and were probably
478defined in error. Drivers may interpret them as in <xref
479 linkend="rgb-formats-corrected" />.</para>
480
481 <table pgwide="1" frame="none" id="rgb-formats-corrected">
482 <title>Packed RGB Image Formats (corrected)</title>
483 <tgroup cols="37" align="center">
484 <colspec colname="id" align="left" />
485 <colspec colname="fourcc" />
486 <colspec colname="bit" />
487
488 <colspec colnum="4" colname="b07" align="center" />
489 <colspec colnum="5" colname="b06" align="center" />
490 <colspec colnum="6" colname="b05" align="center" />
491 <colspec colnum="7" colname="b04" align="center" />
492 <colspec colnum="8" colname="b03" align="center" />
493 <colspec colnum="9" colname="b02" align="center" />
494 <colspec colnum="10" colname="b01" align="center" />
495 <colspec colnum="11" colname="b00" align="center" />
496
497 <colspec colnum="13" colname="b17" align="center" />
498 <colspec colnum="14" colname="b16" align="center" />
499 <colspec colnum="15" colname="b15" align="center" />
500 <colspec colnum="16" colname="b14" align="center" />
501 <colspec colnum="17" colname="b13" align="center" />
502 <colspec colnum="18" colname="b12" align="center" />
503 <colspec colnum="19" colname="b11" align="center" />
504 <colspec colnum="20" colname="b10" align="center" />
505
506 <colspec colnum="22" colname="b27" align="center" />
507 <colspec colnum="23" colname="b26" align="center" />
508 <colspec colnum="24" colname="b25" align="center" />
509 <colspec colnum="25" colname="b24" align="center" />
510 <colspec colnum="26" colname="b23" align="center" />
511 <colspec colnum="27" colname="b22" align="center" />
512 <colspec colnum="28" colname="b21" align="center" />
513 <colspec colnum="29" colname="b20" align="center" />
514
515 <colspec colnum="31" colname="b37" align="center" />
516 <colspec colnum="32" colname="b36" align="center" />
517 <colspec colnum="33" colname="b35" align="center" />
518 <colspec colnum="34" colname="b34" align="center" />
519 <colspec colnum="35" colname="b33" align="center" />
520 <colspec colnum="36" colname="b32" align="center" />
521 <colspec colnum="37" colname="b31" align="center" />
522 <colspec colnum="38" colname="b30" align="center" />
523
524 <spanspec namest="b07" nameend="b00" spanname="b0" />
525 <spanspec namest="b17" nameend="b10" spanname="b1" />
526 <spanspec namest="b27" nameend="b20" spanname="b2" />
527 <spanspec namest="b37" nameend="b30" spanname="b3" />
528 <thead>
529 <row>
530 <entry>Identifier</entry>
531 <entry>Code</entry>
532 <entry>&nbsp;</entry>
533 <entry spanname="b0">Byte&nbsp;0 in memory</entry>
534 <entry spanname="b1">Byte&nbsp;1</entry>
535 <entry spanname="b2">Byte&nbsp;2</entry>
536 <entry spanname="b3">Byte&nbsp;3</entry>
537 </row>
538 <row>
539 <entry>&nbsp;</entry>
540 <entry>&nbsp;</entry>
541 <entry>Bit</entry>
542 <entry>7</entry>
543 <entry>6</entry>
544 <entry>5</entry>
545 <entry>4</entry>
546 <entry>3</entry>
547 <entry>2</entry>
548 <entry>1</entry>
549 <entry>0</entry>
550 <entry>&nbsp;</entry>
551 <entry>7</entry>
552 <entry>6</entry>
553 <entry>5</entry>
554 <entry>4</entry>
555 <entry>3</entry>
556 <entry>2</entry>
557 <entry>1</entry>
558 <entry>0</entry>
559 <entry>&nbsp;</entry>
560 <entry>7</entry>
561 <entry>6</entry>
562 <entry>5</entry>
563 <entry>4</entry>
564 <entry>3</entry>
565 <entry>2</entry>
566 <entry>1</entry>
567 <entry>0</entry>
568 <entry>&nbsp;</entry>
569 <entry>7</entry>
570 <entry>6</entry>
571 <entry>5</entry>
572 <entry>4</entry>
573 <entry>3</entry>
574 <entry>2</entry>
575 <entry>1</entry>
576 <entry>0</entry>
577 </row>
578 </thead>
579 <tbody valign="top">
580 <row><!-- id="V4L2-PIX-FMT-RGB332" -->
581 <entry><constant>V4L2_PIX_FMT_RGB332</constant></entry>
582 <entry>'RGB1'</entry>
583 <entry></entry>
584 <entry>r<subscript>2</subscript></entry>
585 <entry>r<subscript>1</subscript></entry>
586 <entry>r<subscript>0</subscript></entry>
587 <entry>g<subscript>2</subscript></entry>
588 <entry>g<subscript>1</subscript></entry>
589 <entry>g<subscript>0</subscript></entry>
590 <entry>b<subscript>1</subscript></entry>
591 <entry>b<subscript>0</subscript></entry>
592 </row>
593 <row><!-- id="V4L2-PIX-FMT-RGB444" -->
594 <entry><constant>V4L2_PIX_FMT_RGB444</constant></entry>
595 <entry>'R444'</entry>
596 <entry></entry>
597 <entry>g<subscript>3</subscript></entry>
598 <entry>g<subscript>2</subscript></entry>
599 <entry>g<subscript>1</subscript></entry>
600 <entry>g<subscript>0</subscript></entry>
601 <entry>b<subscript>3</subscript></entry>
602 <entry>b<subscript>2</subscript></entry>
603 <entry>b<subscript>1</subscript></entry>
604 <entry>b<subscript>0</subscript></entry>
605 <entry></entry>
606 <entry>a<subscript>3</subscript></entry>
607 <entry>a<subscript>2</subscript></entry>
608 <entry>a<subscript>1</subscript></entry>
609 <entry>a<subscript>0</subscript></entry>
610 <entry>r<subscript>3</subscript></entry>
611 <entry>r<subscript>2</subscript></entry>
612 <entry>r<subscript>1</subscript></entry>
613 <entry>r<subscript>0</subscript></entry>
614 </row>
615 <row><!-- id="V4L2-PIX-FMT-RGB555" -->
616 <entry><constant>V4L2_PIX_FMT_RGB555</constant></entry>
617 <entry>'RGBO'</entry>
618 <entry></entry>
619 <entry>g<subscript>2</subscript></entry>
620 <entry>g<subscript>1</subscript></entry>
621 <entry>g<subscript>0</subscript></entry>
622 <entry>b<subscript>4</subscript></entry>
623 <entry>b<subscript>3</subscript></entry>
624 <entry>b<subscript>2</subscript></entry>
625 <entry>b<subscript>1</subscript></entry>
626 <entry>b<subscript>0</subscript></entry>
627 <entry></entry>
628 <entry>a</entry>
629 <entry>r<subscript>4</subscript></entry>
630 <entry>r<subscript>3</subscript></entry>
631 <entry>r<subscript>2</subscript></entry>
632 <entry>r<subscript>1</subscript></entry>
633 <entry>r<subscript>0</subscript></entry>
634 <entry>g<subscript>4</subscript></entry>
635 <entry>g<subscript>3</subscript></entry>
636 </row>
637 <row><!-- id="V4L2-PIX-FMT-RGB565" -->
638 <entry><constant>V4L2_PIX_FMT_RGB565</constant></entry>
639 <entry>'RGBP'</entry>
640 <entry></entry>
641 <entry>g<subscript>2</subscript></entry>
642 <entry>g<subscript>1</subscript></entry>
643 <entry>g<subscript>0</subscript></entry>
644 <entry>b<subscript>4</subscript></entry>
645 <entry>b<subscript>3</subscript></entry>
646 <entry>b<subscript>2</subscript></entry>
647 <entry>b<subscript>1</subscript></entry>
648 <entry>b<subscript>0</subscript></entry>
649 <entry></entry>
650 <entry>r<subscript>4</subscript></entry>
651 <entry>r<subscript>3</subscript></entry>
652 <entry>r<subscript>2</subscript></entry>
653 <entry>r<subscript>1</subscript></entry>
654 <entry>r<subscript>0</subscript></entry>
655 <entry>g<subscript>5</subscript></entry>
656 <entry>g<subscript>4</subscript></entry>
657 <entry>g<subscript>3</subscript></entry>
658 </row>
659 <row><!-- id="V4L2-PIX-FMT-RGB555X" -->
660 <entry><constant>V4L2_PIX_FMT_RGB555X</constant></entry>
661 <entry>'RGBQ'</entry>
662 <entry></entry>
663 <entry>a</entry>
664 <entry>r<subscript>4</subscript></entry>
665 <entry>r<subscript>3</subscript></entry>
666 <entry>r<subscript>2</subscript></entry>
667 <entry>r<subscript>1</subscript></entry>
668 <entry>r<subscript>0</subscript></entry>
669 <entry>g<subscript>4</subscript></entry>
670 <entry>g<subscript>3</subscript></entry>
671 <entry></entry>
672 <entry>g<subscript>2</subscript></entry>
673 <entry>g<subscript>1</subscript></entry>
674 <entry>g<subscript>0</subscript></entry>
675 <entry>b<subscript>4</subscript></entry>
676 <entry>b<subscript>3</subscript></entry>
677 <entry>b<subscript>2</subscript></entry>
678 <entry>b<subscript>1</subscript></entry>
679 <entry>b<subscript>0</subscript></entry>
680 </row>
681 <row><!-- id="V4L2-PIX-FMT-RGB565X" -->
682 <entry><constant>V4L2_PIX_FMT_RGB565X</constant></entry>
683 <entry>'RGBR'</entry>
684 <entry></entry>
685 <entry>r<subscript>4</subscript></entry>
686 <entry>r<subscript>3</subscript></entry>
687 <entry>r<subscript>2</subscript></entry>
688 <entry>r<subscript>1</subscript></entry>
689 <entry>r<subscript>0</subscript></entry>
690 <entry>g<subscript>5</subscript></entry>
691 <entry>g<subscript>4</subscript></entry>
692 <entry>g<subscript>3</subscript></entry>
693 <entry></entry>
694 <entry>g<subscript>2</subscript></entry>
695 <entry>g<subscript>1</subscript></entry>
696 <entry>g<subscript>0</subscript></entry>
697 <entry>b<subscript>4</subscript></entry>
698 <entry>b<subscript>3</subscript></entry>
699 <entry>b<subscript>2</subscript></entry>
700 <entry>b<subscript>1</subscript></entry>
701 <entry>b<subscript>0</subscript></entry>
702 </row>
703 <row><!-- id="V4L2-PIX-FMT-BGR24" -->
704 <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry>
705 <entry>'BGR3'</entry>
706 <entry></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 <entry>b<subscript>1</subscript></entry>
714 <entry>b<subscript>0</subscript></entry>
715 <entry></entry>
716 <entry>g<subscript>7</subscript></entry>
717 <entry>g<subscript>6</subscript></entry>
718 <entry>g<subscript>5</subscript></entry>
719 <entry>g<subscript>4</subscript></entry>
720 <entry>g<subscript>3</subscript></entry>
721 <entry>g<subscript>2</subscript></entry>
722 <entry>g<subscript>1</subscript></entry>
723 <entry>g<subscript>0</subscript></entry>
724 <entry></entry>
725 <entry>r<subscript>7</subscript></entry>
726 <entry>r<subscript>6</subscript></entry>
727 <entry>r<subscript>5</subscript></entry>
728 <entry>r<subscript>4</subscript></entry>
729 <entry>r<subscript>3</subscript></entry>
730 <entry>r<subscript>2</subscript></entry>
731 <entry>r<subscript>1</subscript></entry>
732 <entry>r<subscript>0</subscript></entry>
733 </row>
734 <row><!-- id="V4L2-PIX-FMT-RGB24" -->
735 <entry><constant>V4L2_PIX_FMT_RGB24</constant></entry>
736 <entry>'RGB3'</entry>
737 <entry></entry>
738 <entry>r<subscript>7</subscript></entry>
739 <entry>r<subscript>6</subscript></entry>
740 <entry>r<subscript>5</subscript></entry>
741 <entry>r<subscript>4</subscript></entry>
742 <entry>r<subscript>3</subscript></entry>
743 <entry>r<subscript>2</subscript></entry>
744 <entry>r<subscript>1</subscript></entry>
745 <entry>r<subscript>0</subscript></entry>
746 <entry></entry>
747 <entry>g<subscript>7</subscript></entry>
748 <entry>g<subscript>6</subscript></entry>
749 <entry>g<subscript>5</subscript></entry>
750 <entry>g<subscript>4</subscript></entry>
751 <entry>g<subscript>3</subscript></entry>
752 <entry>g<subscript>2</subscript></entry>
753 <entry>g<subscript>1</subscript></entry>
754 <entry>g<subscript>0</subscript></entry>
755 <entry></entry>
756 <entry>b<subscript>7</subscript></entry>
757 <entry>b<subscript>6</subscript></entry>
758 <entry>b<subscript>5</subscript></entry>
759 <entry>b<subscript>4</subscript></entry>
760 <entry>b<subscript>3</subscript></entry>
761 <entry>b<subscript>2</subscript></entry>
762 <entry>b<subscript>1</subscript></entry>
763 <entry>b<subscript>0</subscript></entry>
764 </row>
765 <row><!-- id="V4L2-PIX-FMT-BGR32" -->
766 <entry><constant>V4L2_PIX_FMT_BGR32</constant></entry>
767 <entry>'BGR4'</entry>
768 <entry></entry>
769 <entry>b<subscript>7</subscript></entry>
770 <entry>b<subscript>6</subscript></entry>
771 <entry>b<subscript>5</subscript></entry>
772 <entry>b<subscript>4</subscript></entry>
773 <entry>b<subscript>3</subscript></entry>
774 <entry>b<subscript>2</subscript></entry>
775 <entry>b<subscript>1</subscript></entry>
776 <entry>b<subscript>0</subscript></entry>
777 <entry></entry>
778 <entry>g<subscript>7</subscript></entry>
779 <entry>g<subscript>6</subscript></entry>
780 <entry>g<subscript>5</subscript></entry>
781 <entry>g<subscript>4</subscript></entry>
782 <entry>g<subscript>3</subscript></entry>
783 <entry>g<subscript>2</subscript></entry>
784 <entry>g<subscript>1</subscript></entry>
785 <entry>g<subscript>0</subscript></entry>
786 <entry></entry>
787 <entry>r<subscript>7</subscript></entry>
788 <entry>r<subscript>6</subscript></entry>
789 <entry>r<subscript>5</subscript></entry>
790 <entry>r<subscript>4</subscript></entry>
791 <entry>r<subscript>3</subscript></entry>
792 <entry>r<subscript>2</subscript></entry>
793 <entry>r<subscript>1</subscript></entry>
794 <entry>r<subscript>0</subscript></entry>
795 <entry></entry>
796 <entry>a<subscript>7</subscript></entry>
797 <entry>a<subscript>6</subscript></entry>
798 <entry>a<subscript>5</subscript></entry>
799 <entry>a<subscript>4</subscript></entry>
800 <entry>a<subscript>3</subscript></entry>
801 <entry>a<subscript>2</subscript></entry>
802 <entry>a<subscript>1</subscript></entry>
803 <entry>a<subscript>0</subscript></entry>
804 </row>
805 <row><!-- id="V4L2-PIX-FMT-RGB32" -->
806 <entry><constant>V4L2_PIX_FMT_RGB32</constant></entry>
807 <entry>'RGB4'</entry>
808 <entry></entry>
809 <entry>a<subscript>7</subscript></entry>
810 <entry>a<subscript>6</subscript></entry>
811 <entry>a<subscript>5</subscript></entry>
812 <entry>a<subscript>4</subscript></entry>
813 <entry>a<subscript>3</subscript></entry>
814 <entry>a<subscript>2</subscript></entry>
815 <entry>a<subscript>1</subscript></entry>
816 <entry>a<subscript>0</subscript></entry>
817 <entry></entry>
818 <entry>r<subscript>7</subscript></entry>
819 <entry>r<subscript>6</subscript></entry>
820 <entry>r<subscript>5</subscript></entry>
821 <entry>r<subscript>4</subscript></entry>
822 <entry>r<subscript>3</subscript></entry>
823 <entry>r<subscript>2</subscript></entry>
824 <entry>r<subscript>1</subscript></entry>
825 <entry>r<subscript>0</subscript></entry>
826 <entry></entry>
827 <entry>g<subscript>7</subscript></entry>
828 <entry>g<subscript>6</subscript></entry>
829 <entry>g<subscript>5</subscript></entry>
830 <entry>g<subscript>4</subscript></entry>
831 <entry>g<subscript>3</subscript></entry>
832 <entry>g<subscript>2</subscript></entry>
833 <entry>g<subscript>1</subscript></entry>
834 <entry>g<subscript>0</subscript></entry>
835 <entry></entry>
836 <entry>b<subscript>7</subscript></entry>
837 <entry>b<subscript>6</subscript></entry>
838 <entry>b<subscript>5</subscript></entry>
839 <entry>b<subscript>4</subscript></entry>
840 <entry>b<subscript>3</subscript></entry>
841 <entry>b<subscript>2</subscript></entry>
842 <entry>b<subscript>1</subscript></entry>
843 <entry>b<subscript>0</subscript></entry>
844 </row>
845 </tbody>
846 </tgroup>
847 </table>
848
849 <para>A test utility to determine which RGB formats a driver
850actually supports is available from the LinuxTV v4l-dvb repository.
851See &v4l-dvb; for access instructions.</para>
852
853 </refsect1>
854 </refentry>
855
856 <!--
857Local Variables:
858mode: sgml
859sgml-parent-document: "pixfmt.sgml"
860indent-tabs-mode: nil
861End:
862 -->
diff --git a/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml b/Documentation/DocBook/v4l/pixfmt-packed-yuv.xml
new file mode 100644
index 000000000000..3cab5d0ca75d
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-sbggr16.xml b/Documentation/DocBook/v4l/pixfmt-sbggr16.xml
new file mode 100644
index 000000000000..519a9efbac10
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-sbggr8.xml b/Documentation/DocBook/v4l/pixfmt-sbggr8.xml
new file mode 100644
index 000000000000..5fe84ecc2ebe
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-sgbrg8.xml b/Documentation/DocBook/v4l/pixfmt-sgbrg8.xml
new file mode 100644
index 000000000000..d67a472b0880
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-sgrbg8.xml b/Documentation/DocBook/v4l/pixfmt-sgrbg8.xml
new file mode 100644
index 000000000000..0cdf13b8ac1c
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-uyvy.xml b/Documentation/DocBook/v4l/pixfmt-uyvy.xml
new file mode 100644
index 000000000000..816c8d467c16
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-vyuy.xml b/Documentation/DocBook/v4l/pixfmt-vyuy.xml
new file mode 100644
index 000000000000..61f12a5e68d9
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-y16.xml b/Documentation/DocBook/v4l/pixfmt-y16.xml
new file mode 100644
index 000000000000..d58404015078
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-y41p.xml b/Documentation/DocBook/v4l/pixfmt-y41p.xml
new file mode 100644
index 000000000000..73c8536efb05
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-yuv410.xml b/Documentation/DocBook/v4l/pixfmt-yuv410.xml
new file mode 100644
index 000000000000..8eb4a193d770
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-yuv411p.xml b/Documentation/DocBook/v4l/pixfmt-yuv411p.xml
new file mode 100644
index 000000000000..00e0960a9869
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-yuv420.xml b/Documentation/DocBook/v4l/pixfmt-yuv420.xml
new file mode 100644
index 000000000000..42d7de5e456d
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-yuv422p.xml b/Documentation/DocBook/v4l/pixfmt-yuv422p.xml
new file mode 100644
index 000000000000..4348bd9f0d01
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-yuyv.xml b/Documentation/DocBook/v4l/pixfmt-yuyv.xml
new file mode 100644
index 000000000000..bdb2ffacbbcc
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt-yvyu.xml b/Documentation/DocBook/v4l/pixfmt-yvyu.xml
new file mode 100644
index 000000000000..40d17ae39dde
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/pixfmt.xml b/Documentation/DocBook/v4l/pixfmt.xml
new file mode 100644
index 000000000000..aaea55d44592
--- /dev/null
+++ b/Documentation/DocBook/v4l/pixfmt.xml
@@ -0,0 +1,796 @@
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> structure defines the format
6and layout of an image in memory. Image formats are negotiated with
7the &VIDIOC-S-FMT; ioctl. (The explanations here focus on video
8capturing and output, for overlay frame buffer formats see also
9&VIDIOC-G-FBUF;.)</para>
10
11 <table pgwide="1" frame="none" id="v4l2-pix-format">
12 <title>struct <structname>v4l2_pix_format</structname></title>
13 <tgroup cols="3">
14 &cs-str;
15 <tbody valign="top">
16 <row>
17 <entry>__u32</entry>
18 <entry><structfield>width</structfield></entry>
19 <entry>Image width in pixels.</entry>
20 </row>
21 <row>
22 <entry>__u32</entry>
23 <entry><structfield>height</structfield></entry>
24 <entry>Image height in pixels.</entry>
25 </row>
26 <row>
27 <entry spanname="hspan">Applications set these fields to
28request an image size, drivers return the closest possible values. In
29case of planar formats the <structfield>width</structfield> and
30<structfield>height</structfield> applies to the largest plane. To
31avoid ambiguities drivers must return values rounded up to a multiple
32of the scale factor of any smaller planes. For example when the image
33format is YUV 4:2:0, <structfield>width</structfield> and
34<structfield>height</structfield> must be multiples of two.</entry>
35 </row>
36 <row>
37 <entry>__u32</entry>
38 <entry><structfield>pixelformat</structfield></entry>
39 <entry>The pixel format or type of compression, set by the
40application. This is a little endian <link
41linkend="v4l2-fourcc">four character code</link>. V4L2 defines
42standard RGB formats in <xref linkend="rgb-formats" />, YUV formats in <xref
43linkend="yuv-formats" />, and reserved codes in <xref
44linkend="reserved-formats" /></entry>
45 </row>
46 <row>
47 <entry>&v4l2-field;</entry>
48 <entry><structfield>field</structfield></entry>
49 <entry>Video images are typically interlaced. Applications
50can request to capture or output only the top or bottom field, or both
51fields interlaced or sequentially stored in one buffer or alternating
52in separate buffers. Drivers return the actual field order selected.
53For details see <xref linkend="field-order" />.</entry>
54 </row>
55 <row>
56 <entry>__u32</entry>
57 <entry><structfield>bytesperline</structfield></entry>
58 <entry>Distance in bytes between the leftmost pixels in two
59adjacent lines.</entry>
60 </row>
61 <row>
62 <entry spanname="hspan"><para>Both applications and drivers
63can set this field to request padding bytes at the end of each line.
64Drivers however may ignore the value requested by the application,
65returning <structfield>width</structfield> times bytes per pixel or a
66larger value required by the hardware. That implies applications can
67just set this field to zero to get a reasonable
68default.</para><para>Video hardware may access padding bytes,
69therefore they must reside in accessible memory. Consider cases where
70padding bytes after the last line of an image cross a system page
71boundary. Input devices may write padding bytes, the value is
72undefined. Output devices ignore the contents of padding
73bytes.</para><para>When the image format is planar the
74<structfield>bytesperline</structfield> value applies to the largest
75plane and is divided by the same factor as the
76<structfield>width</structfield> field for any smaller planes. For
77example the Cb and Cr planes of a YUV 4:2:0 image have half as many
78padding bytes following each line as the Y plane. To avoid ambiguities
79drivers must return a <structfield>bytesperline</structfield> value
80rounded up to a multiple of the scale factor.</para></entry>
81 </row>
82 <row>
83 <entry>__u32</entry>
84 <entry><structfield>sizeimage</structfield></entry>
85 <entry>Size in bytes of the buffer to hold a complete image,
86set by the driver. Usually this is
87<structfield>bytesperline</structfield> times
88<structfield>height</structfield>. When the image consists of variable
89length compressed data this is the maximum number of bytes required to
90hold an image.</entry>
91 </row>
92 <row>
93 <entry>&v4l2-colorspace;</entry>
94 <entry><structfield>colorspace</structfield></entry>
95 <entry>This information supplements the
96<structfield>pixelformat</structfield> and must be set by the driver,
97see <xref linkend="colorspaces" />.</entry>
98 </row>
99 <row>
100 <entry>__u32</entry>
101 <entry><structfield>priv</structfield></entry>
102 <entry>Reserved for custom (driver defined) additional
103information about formats. When not used drivers and applications must
104set this field to zero.</entry>
105 </row>
106 </tbody>
107 </tgroup>
108 </table>
109
110 <section>
111 <title>Standard Image Formats</title>
112
113 <para>In order to exchange images between drivers and
114applications, it is necessary to have standard image data formats
115which both sides will interpret the same way. V4L2 includes several
116such formats, and this section is intended to be an unambiguous
117specification of the standard image data formats in V4L2.</para>
118
119 <para>V4L2 drivers are not limited to these formats, however.
120Driver-specific formats are possible. In that case the application may
121depend on a codec to convert images to one of the standard formats
122when needed. But the data can still be stored and retrieved in the
123proprietary format. For example, a device may support a proprietary
124compressed format. Applications can still capture and save the data in
125the compressed format, saving much disk space, and later use a codec
126to convert the images to the X Windows screen format when the video is
127to be displayed.</para>
128
129 <para>Even so, ultimately, some standard formats are needed, so
130the V4L2 specification would not be complete without well-defined
131standard formats.</para>
132
133 <para>The V4L2 standard formats are mainly uncompressed formats. The
134pixels are always arranged in memory from left to right, and from top
135to bottom. The first byte of data in the image buffer is always for
136the leftmost pixel of the topmost row. Following that is the pixel
137immediately to its right, and so on until the end of the top row of
138pixels. Following the rightmost pixel of the row there may be zero or
139more bytes of padding to guarantee that each row of pixel data has a
140certain alignment. Following the pad bytes, if any, is data for the
141leftmost pixel of the second row from the top, and so on. The last row
142has just as many pad bytes after it as the other rows.</para>
143
144 <para>In V4L2 each format has an identifier which looks like
145<constant>PIX_FMT_XXX</constant>, defined in the <link
146linkend="videodev">videodev.h</link> header file. These identifiers
147represent <link linkend="v4l2-fourcc">four character codes</link>
148which are also listed below, however they are not the same as those
149used in the Windows world.</para>
150 </section>
151
152 <section id="colorspaces">
153 <title>Colorspaces</title>
154
155 <para>[intro]</para>
156
157 <!-- See proposal by Billy Biggs, video4linux-list@redhat.com
158on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and
159http://vektor.theorem.ca/graphics/ycbcr/ and
160http://www.inforamp.net/~poynton/notes/colour_and_gamma/index.html -->
161
162 <para>
163 <variablelist>
164 <varlistentry>
165 <term>Gamma Correction</term>
166 <listitem>
167 <para>[to do]</para>
168 <para>E'<subscript>R</subscript> = f(R)</para>
169 <para>E'<subscript>G</subscript> = f(G)</para>
170 <para>E'<subscript>B</subscript> = f(B)</para>
171 </listitem>
172 </varlistentry>
173 <varlistentry>
174 <term>Construction of luminance and color-difference
175signals</term>
176 <listitem>
177 <para>[to do]</para>
178 <para>E'<subscript>Y</subscript> =
179Coeff<subscript>R</subscript> E'<subscript>R</subscript>
180+ Coeff<subscript>G</subscript> E'<subscript>G</subscript>
181+ Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
182 <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript>
183- Coeff<subscript>R</subscript> E'<subscript>R</subscript>
184- Coeff<subscript>G</subscript> E'<subscript>G</subscript>
185- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
186 <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript>
187- Coeff<subscript>R</subscript> E'<subscript>R</subscript>
188- Coeff<subscript>G</subscript> E'<subscript>G</subscript>
189- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para>
190 </listitem>
191 </varlistentry>
192 <varlistentry>
193 <term>Re-normalized color-difference signals</term>
194 <listitem>
195 <para>The color-difference signals are scaled back to unity
196range [-0.5;+0.5]:</para>
197 <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para>
198 <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para>
199 <para>P<subscript>B</subscript> =
200K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) =
201 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript>
202+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript>
203+ 0.5 E'<subscript>B</subscript></para>
204 <para>P<subscript>R</subscript> =
205K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) =
206 0.5 E'<subscript>R</subscript>
207+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript>
208+ 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para>
209 </listitem>
210 </varlistentry>
211 <varlistentry>
212 <term>Quantization</term>
213 <listitem>
214 <para>[to do]</para>
215 <para>Y' = (Lum. Levels - 1) &middot; E'<subscript>Y</subscript> + Lum. Offset</para>
216 <para>C<subscript>B</subscript> = (Chrom. Levels - 1)
217&middot; P<subscript>B</subscript> + Chrom. Offset</para>
218 <para>C<subscript>R</subscript> = (Chrom. Levels - 1)
219&middot; P<subscript>R</subscript> + Chrom. Offset</para>
220 <para>Rounding to the nearest integer and clamping to the range
221[0;255] finally yields the digital color components Y'CbCr
222stored in YUV images.</para>
223 </listitem>
224 </varlistentry>
225 </variablelist>
226 </para>
227
228 <example>
229 <title>ITU-R Rec. BT.601 color conversion</title>
230
231 <para>Forward Transformation</para>
232
233 <programlisting>
234int ER, EG, EB; /* gamma corrected RGB input [0;255] */
235int Y1, Cb, Cr; /* output [0;255] */
236
237double r, g, b; /* temporaries */
238double y1, pb, pr;
239
240int
241clamp (double x)
242{
243 int r = x; /* round to nearest */
244
245 if (r &lt; 0) return 0;
246 else if (r &gt; 255) return 255;
247 else return r;
248}
249
250r = ER / 255.0;
251g = EG / 255.0;
252b = EB / 255.0;
253
254y1 = 0.299 * r + 0.587 * g + 0.114 * b;
255pb = -0.169 * r - 0.331 * g + 0.5 * b;
256pr = 0.5 * r - 0.419 * g - 0.081 * b;
257
258Y1 = clamp (219 * y1 + 16);
259Cb = clamp (224 * pb + 128);
260Cr = clamp (224 * pr + 128);
261
262/* or shorter */
263
264y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB;
265
266Y1 = clamp ( (219 / 255.0) * y1 + 16);
267Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128);
268Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128);
269 </programlisting>
270
271 <para>Inverse Transformation</para>
272
273 <programlisting>
274int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */
275int ER, EG, EB; /* output [0;255] */
276
277double r, g, b; /* temporaries */
278double y1, pb, pr;
279
280int
281clamp (double x)
282{
283 int r = x; /* round to nearest */
284
285 if (r &lt; 0) return 0;
286 else if (r &gt; 255) return 255;
287 else return r;
288}
289
290y1 = (255 / 219.0) * (Y1 - 16);
291pb = (255 / 224.0) * (Cb - 128);
292pr = (255 / 224.0) * (Cr - 128);
293
294r = 1.0 * y1 + 0 * pb + 1.402 * pr;
295g = 1.0 * y1 - 0.344 * pb - 0.714 * pr;
296b = 1.0 * y1 + 1.772 * pb + 0 * pr;
297
298ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */
299EG = clamp (g * 255);
300EB = clamp (b * 255);
301 </programlisting>
302 </example>
303
304 <table pgwide="1" id="v4l2-colorspace" orient="land">
305 <title>enum v4l2_colorspace</title>
306 <tgroup cols="11" align="center">
307 <colspec align="left" />
308 <colspec align="center" />
309 <colspec align="left" />
310 <colspec colname="cr" />
311 <colspec colname="cg" />
312 <colspec colname="cb" />
313 <colspec colname="wp" />
314 <colspec colname="gc" />
315 <colspec colname="lum" />
316 <colspec colname="qy" />
317 <colspec colname="qc" />
318 <spanspec namest="cr" nameend="cb" spanname="chrom" />
319 <spanspec namest="qy" nameend="qc" spanname="quant" />
320 <spanspec namest="lum" nameend="qc" spanname="spam" />
321 <thead>
322 <row>
323 <entry morerows="1">Identifier</entry>
324 <entry morerows="1">Value</entry>
325 <entry morerows="1">Description</entry>
326 <entry spanname="chrom">Chromaticities<footnote>
327 <para>The coordinates of the color primaries are
328given in the CIE system (1931)</para>
329 </footnote></entry>
330 <entry morerows="1">White Point</entry>
331 <entry morerows="1">Gamma Correction</entry>
332 <entry morerows="1">Luminance E'<subscript>Y</subscript></entry>
333 <entry spanname="quant">Quantization</entry>
334 </row>
335 <row>
336 <entry>Red</entry>
337 <entry>Green</entry>
338 <entry>Blue</entry>
339 <entry>Y'</entry>
340 <entry>Cb, Cr</entry>
341 </row>
342 </thead>
343 <tbody valign="top">
344 <row>
345 <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry>
346 <entry>1</entry>
347 <entry>NTSC/PAL according to <xref linkend="smpte170m" />,
348<xref linkend="itu601" /></entry>
349 <entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
350 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
351 <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
352 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
353 Illuminant D<subscript>65</subscript></entry>
354 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
3551.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
356 <entry>0.299&nbsp;E'<subscript>R</subscript>
357+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
358+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
359 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
360 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
361 </row>
362 <row>
363 <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry>
364 <entry>2</entry>
365 <entry>1125-Line (US) HDTV, see <xref
366linkend="smpte240m" /></entry>
367 <entry>x&nbsp;=&nbsp;0.630, y&nbsp;=&nbsp;0.340</entry>
368 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.595</entry>
369 <entry>x&nbsp;=&nbsp;0.155, y&nbsp;=&nbsp;0.070</entry>
370 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
371 Illuminant D<subscript>65</subscript></entry>
372 <entry>E' = 4&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.0228,
3731.1115&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.1115&nbsp;for&nbsp;0.0228&nbsp;&lt;&nbsp;I</entry>
374 <entry>0.212&nbsp;E'<subscript>R</subscript>
375+&nbsp;0.701&nbsp;E'<subscript>G</subscript>
376+&nbsp;0.087&nbsp;E'<subscript>B</subscript></entry>
377 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
378 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
379 </row>
380 <row>
381 <entry><constant>V4L2_COLORSPACE_REC709</constant></entry>
382 <entry>3</entry>
383 <entry>HDTV and modern devices, see <xref
384linkend="itu709" /></entry>
385 <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
386 <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
387 <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
388 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
389 Illuminant D<subscript>65</subscript></entry>
390 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
3911.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
392 <entry>0.2125&nbsp;E'<subscript>R</subscript>
393+&nbsp;0.7154&nbsp;E'<subscript>G</subscript>
394+&nbsp;0.0721&nbsp;E'<subscript>B</subscript></entry>
395 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
396 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
397 </row>
398 <row>
399 <entry><constant>V4L2_COLORSPACE_BT878</constant></entry>
400 <entry>4</entry>
401 <entry>Broken Bt878 extents<footnote>
402 <para>The ubiquitous Bt878 video capture chip
403quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range
404of Y' = 16 &hellip; 253, unlike Rec. 601 Y' = 16 &hellip;
405235. This is not a typo in the Bt878 documentation, it has been
406implemented in silicon. The chroma extents are unclear.</para>
407 </footnote>, <xref linkend="itu601" /></entry>
408 <entry>?</entry>
409 <entry>?</entry>
410 <entry>?</entry>
411 <entry>?</entry>
412 <entry>?</entry>
413 <entry>0.299&nbsp;E'<subscript>R</subscript>
414+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
415+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
416 <entry><emphasis>237</emphasis>&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
417 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128 (probably)</entry>
418 </row>
419 <row>
420 <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry>
421 <entry>5</entry>
422 <entry>M/NTSC<footnote>
423 <para>No identifier exists for M/PAL which uses
424the chromaticities of M/NTSC, the remaining parameters are equal to B and
425G/PAL.</para>
426 </footnote> according to <xref linkend="itu470" />, <xref
427 linkend="itu601" /></entry>
428 <entry>x&nbsp;=&nbsp;0.67, y&nbsp;=&nbsp;0.33</entry>
429 <entry>x&nbsp;=&nbsp;0.21, y&nbsp;=&nbsp;0.71</entry>
430 <entry>x&nbsp;=&nbsp;0.14, y&nbsp;=&nbsp;0.08</entry>
431 <entry>x&nbsp;=&nbsp;0.310, y&nbsp;=&nbsp;0.316, Illuminant C</entry>
432 <entry>?</entry>
433 <entry>0.299&nbsp;E'<subscript>R</subscript>
434+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
435+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
436 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
437 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
438 </row>
439 <row>
440 <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry>
441 <entry>6</entry>
442 <entry>625-line PAL and SECAM systems according to <xref
443linkend="itu470" />, <xref linkend="itu601" /></entry>
444 <entry>x&nbsp;=&nbsp;0.64, y&nbsp;=&nbsp;0.33</entry>
445 <entry>x&nbsp;=&nbsp;0.29, y&nbsp;=&nbsp;0.60</entry>
446 <entry>x&nbsp;=&nbsp;0.15, y&nbsp;=&nbsp;0.06</entry>
447 <entry>x&nbsp;=&nbsp;0.313, y&nbsp;=&nbsp;0.329,
448Illuminant D<subscript>65</subscript></entry>
449 <entry>?</entry>
450 <entry>0.299&nbsp;E'<subscript>R</subscript>
451+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
452+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
453 <entry>219&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16</entry>
454 <entry>224&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
455 </row>
456 <row>
457 <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry>
458 <entry>7</entry>
459 <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry>
460 <entry>?</entry>
461 <entry>?</entry>
462 <entry>?</entry>
463 <entry>?</entry>
464 <entry>?</entry>
465 <entry>0.299&nbsp;E'<subscript>R</subscript>
466+&nbsp;0.587&nbsp;E'<subscript>G</subscript>
467+&nbsp;0.114&nbsp;E'<subscript>B</subscript></entry>
468 <entry>256&nbsp;E'<subscript>Y</subscript>&nbsp;+&nbsp;16<footnote>
469 <para>Note JFIF quantizes
470Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and
471[-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals
472are still clamped to [0;255].</para>
473 </footnote></entry>
474 <entry>256&nbsp;P<subscript>B,R</subscript>&nbsp;+&nbsp;128</entry>
475 </row>
476 <row>
477 <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry>
478 <entry>8</entry>
479 <entry>[?]</entry>
480 <entry>x&nbsp;=&nbsp;0.640, y&nbsp;=&nbsp;0.330</entry>
481 <entry>x&nbsp;=&nbsp;0.300, y&nbsp;=&nbsp;0.600</entry>
482 <entry>x&nbsp;=&nbsp;0.150, y&nbsp;=&nbsp;0.060</entry>
483 <entry>x&nbsp;=&nbsp;0.3127, y&nbsp;=&nbsp;0.3290,
484 Illuminant D<subscript>65</subscript></entry>
485 <entry>E' = 4.5&nbsp;I&nbsp;for&nbsp;I&nbsp;&le;0.018,
4861.099&nbsp;I<superscript>0.45</superscript>&nbsp;-&nbsp;0.099&nbsp;for&nbsp;0.018&nbsp;&lt;&nbsp;I</entry>
487 <entry spanname="spam">n/a</entry>
488 </row>
489 </tbody>
490 </tgroup>
491 </table>
492 </section>
493
494 <section id="pixfmt-indexed">
495 <title>Indexed Format</title>
496
497 <para>In this format each pixel is represented by an 8 bit index
498into a 256 entry ARGB palette. It is intended for <link
499linkend="osd">Video Output Overlays</link> only. There are no ioctls to
500access the palette, this must be done with ioctls of the Linux framebuffer API.</para>
501
502 <table pgwide="0" frame="none">
503 <title>Indexed Image Format</title>
504 <tgroup cols="37" align="center">
505 <colspec colname="id" align="left" />
506 <colspec colname="fourcc" />
507 <colspec colname="bit" />
508
509 <colspec colnum="4" colname="b07" align="center" />
510 <colspec colnum="5" colname="b06" align="center" />
511 <colspec colnum="6" colname="b05" align="center" />
512 <colspec colnum="7" colname="b04" align="center" />
513 <colspec colnum="8" colname="b03" align="center" />
514 <colspec colnum="9" colname="b02" align="center" />
515 <colspec colnum="10" colname="b01" align="center" />
516 <colspec colnum="11" colname="b00" align="center" />
517
518 <spanspec namest="b07" nameend="b00" spanname="b0" />
519 <spanspec namest="b17" nameend="b10" spanname="b1" />
520 <spanspec namest="b27" nameend="b20" spanname="b2" />
521 <spanspec namest="b37" nameend="b30" spanname="b3" />
522 <thead>
523 <row>
524 <entry>Identifier</entry>
525 <entry>Code</entry>
526 <entry>&nbsp;</entry>
527 <entry spanname="b0">Byte&nbsp;0</entry>
528 </row>
529 <row>
530 <entry>&nbsp;</entry>
531 <entry>&nbsp;</entry>
532 <entry>Bit</entry>
533 <entry>7</entry>
534 <entry>6</entry>
535 <entry>5</entry>
536 <entry>4</entry>
537 <entry>3</entry>
538 <entry>2</entry>
539 <entry>1</entry>
540 <entry>0</entry>
541 </row>
542 </thead>
543 <tbody valign="top">
544 <row id="V4L2-PIX-FMT-PAL8">
545 <entry><constant>V4L2_PIX_FMT_PAL8</constant></entry>
546 <entry>'PAL8'</entry>
547 <entry></entry>
548 <entry>i<subscript>7</subscript></entry>
549 <entry>i<subscript>6</subscript></entry>
550 <entry>i<subscript>5</subscript></entry>
551 <entry>i<subscript>4</subscript></entry>
552 <entry>i<subscript>3</subscript></entry>
553 <entry>i<subscript>2</subscript></entry>
554 <entry>i<subscript>1</subscript></entry>
555 <entry>i<subscript>0</subscript></entry>
556 </row>
557 </tbody>
558 </tgroup>
559 </table>
560 </section>
561
562 <section id="pixfmt-rgb">
563 <title>RGB Formats</title>
564
565 &sub-packed-rgb;
566 &sub-sbggr8;
567 &sub-sgbrg8;
568 &sub-sgrbg8;
569 &sub-sbggr16;
570 </section>
571
572 <section id="yuv-formats">
573 <title>YUV Formats</title>
574
575 <para>YUV is the format native to TV broadcast and composite video
576signals. It separates the brightness information (Y) from the color
577information (U and V or Cb and Cr). The color information consists of
578red and blue <emphasis>color difference</emphasis> signals, this way
579the green component can be reconstructed by subtracting from the
580brightness component. See <xref linkend="colorspaces" /> for conversion
581examples. YUV was chosen because early television would only transmit
582brightness information. To add color in a way compatible with existing
583receivers a new signal carrier was added to transmit the color
584difference signals. Secondary in the YUV format the U and V components
585usually have lower resolution than the Y component. This is an analog
586video compression technique taking advantage of a property of the
587human visual system, being more sensitive to brightness
588information.</para>
589
590 &sub-packed-yuv;
591 &sub-grey;
592 &sub-y16;
593 &sub-yuyv;
594 &sub-uyvy;
595 &sub-yvyu;
596 &sub-vyuy;
597 &sub-y41p;
598 &sub-yuv420;
599 &sub-yuv410;
600 &sub-yuv422p;
601 &sub-yuv411p;
602 &sub-nv12;
603 &sub-nv16;
604 </section>
605
606 <section>
607 <title>Compressed Formats</title>
608
609 <table pgwide="1" frame="none" id="compressed-formats">
610 <title>Compressed Image Formats</title>
611 <tgroup cols="3" align="left">
612 &cs-def;
613 <thead>
614 <row>
615 <entry>Identifier</entry>
616 <entry>Code</entry>
617 <entry>Details</entry>
618 </row>
619 </thead>
620 <tbody valign="top">
621 <row id="V4L2-PIX-FMT-JPEG">
622 <entry><constant>V4L2_PIX_FMT_JPEG</constant></entry>
623 <entry>'JPEG'</entry>
624 <entry>TBD. See also &VIDIOC-G-JPEGCOMP;,
625 &VIDIOC-S-JPEGCOMP;.</entry>
626 </row>
627 <row id="V4L2-PIX-FMT-MPEG">
628 <entry><constant>V4L2_PIX_FMT_MPEG</constant></entry>
629 <entry>'MPEG'</entry>
630 <entry>MPEG stream. The actual format is determined by
631extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
632<xref linkend="mpeg-control-id" />.</entry>
633 </row>
634 </tbody>
635 </tgroup>
636 </table>
637 </section>
638
639 <section id="pixfmt-reserved">
640 <title>Reserved Format Identifiers</title>
641
642 <para>These formats are not defined by this specification, they
643are just listed for reference and to avoid naming conflicts. If you
644want to register your own format, send an e-mail to the linux-media mailing
645list &v4l-ml; for inclusion in the <filename>videodev2.h</filename>
646file. If you want to share your format with other developers add a
647link to your documentation and send a copy to the linux-media mailing list
648for inclusion in this section. If you think your format should be listed
649in a standard format section please make a proposal on the linux-media mailing
650list.</para>
651
652 <table pgwide="1" frame="none" id="reserved-formats">
653 <title>Reserved Image Formats</title>
654 <tgroup cols="3" align="left">
655 &cs-def;
656 <thead>
657 <row>
658 <entry>Identifier</entry>
659 <entry>Code</entry>
660 <entry>Details</entry>
661 </row>
662 </thead>
663 <tbody valign="top">
664 <row id="V4L2-PIX-FMT-DV">
665 <entry><constant>V4L2_PIX_FMT_DV</constant></entry>
666 <entry>'dvsd'</entry>
667 <entry>unknown</entry>
668 </row>
669 <row id="V4L2-PIX-FMT-ET61X251">
670 <entry><constant>V4L2_PIX_FMT_ET61X251</constant></entry>
671 <entry>'E625'</entry>
672 <entry>Compressed format of the ET61X251 driver.</entry>
673 </row>
674 <row id="V4L2-PIX-FMT-HI240">
675 <entry><constant>V4L2_PIX_FMT_HI240</constant></entry>
676 <entry>'HI24'</entry>
677 <entry><para>8 bit RGB format used by the BTTV driver.</para></entry>
678 </row>
679 <row id="V4L2-PIX-FMT-HM12">
680 <entry><constant>V4L2_PIX_FMT_HM12</constant></entry>
681 <entry>'HM12'</entry>
682 <entry><para>YUV 4:2:0 format used by the
683IVTV driver, <ulink url="http://www.ivtvdriver.org/">
684http://www.ivtvdriver.org/</ulink></para><para>The format is documented in the
685kernel sources in the file <filename>Documentation/video4linux/cx2341x/README.hm12</filename>
686</para></entry>
687 </row>
688 <row id="V4L2-PIX-FMT-SPCA501">
689 <entry><constant>V4L2_PIX_FMT_SPCA501</constant></entry>
690 <entry>'S501'</entry>
691 <entry>YUYV per line used by the gspca driver.</entry>
692 </row>
693 <row id="V4L2-PIX-FMT-SPCA505">
694 <entry><constant>V4L2_PIX_FMT_SPCA505</constant></entry>
695 <entry>'S505'</entry>
696 <entry>YYUV per line used by the gspca driver.</entry>
697 </row>
698 <row id="V4L2-PIX-FMT-SPCA508">
699 <entry><constant>V4L2_PIX_FMT_SPCA508</constant></entry>
700 <entry>'S508'</entry>
701 <entry>YUVY per line used by the gspca driver.</entry>
702 </row>
703 <row id="V4L2-PIX-FMT-SPCA561">
704 <entry><constant>V4L2_PIX_FMT_SPCA561</constant></entry>
705 <entry>'S561'</entry>
706 <entry>Compressed GBRG Bayer format used by the gspca driver.</entry>
707 </row>
708 <row id="V4L2-PIX-FMT-SGRBG10">
709 <entry><constant>V4L2_PIX_FMT_SGRBG10</constant></entry>
710 <entry>'DA10'</entry>
711 <entry>10 bit raw Bayer, expanded to 16 bits.</entry>
712 </row>
713 <row id="V4L2-PIX-FMT-SGRBG10DPCM8">
714 <entry><constant>V4L2_PIX_FMT_SGRBG10DPCM8</constant></entry>
715 <entry>'DB10'</entry>
716 <entry>10 bit raw Bayer DPCM compressed to 8 bits.</entry>
717 </row>
718 <row id="V4L2-PIX-FMT-PAC207">
719 <entry><constant>V4L2_PIX_FMT_PAC207</constant></entry>
720 <entry>'P207'</entry>
721 <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
722 </row>
723 <row id="V4L2-PIX-FMT-MR97310A">
724 <entry><constant>V4L2_PIX_FMT_MR97310A</constant></entry>
725 <entry>'M310'</entry>
726 <entry>Compressed BGGR Bayer format used by the gspca driver.</entry>
727 </row>
728 <row id="V4L2-PIX-FMT-OV511">
729 <entry><constant>V4L2_PIX_FMT_OV511</constant></entry>
730 <entry>'O511'</entry>
731 <entry>OV511 JPEG format used by the gspca driver.</entry>
732 </row>
733 <row id="V4L2-PIX-FMT-OV518">
734 <entry><constant>V4L2_PIX_FMT_OV518</constant></entry>
735 <entry>'O518'</entry>
736 <entry>OV518 JPEG format used by the gspca driver.</entry>
737 </row>
738 <row id="V4L2-PIX-FMT-PJPG">
739 <entry><constant>V4L2_PIX_FMT_PJPG</constant></entry>
740 <entry>'PJPG'</entry>
741 <entry>Pixart 73xx JPEG format used by the gspca driver.</entry>
742 </row>
743 <row id="V4L2-PIX-FMT-SQ905C">
744 <entry><constant>V4L2_PIX_FMT_SQ905C</constant></entry>
745 <entry>'905C'</entry>
746 <entry>Compressed RGGB bayer format used by the gspca driver.</entry>
747 </row>
748 <row id="V4L2-PIX-FMT-MJPEG">
749 <entry><constant>V4L2_PIX_FMT_MJPEG</constant></entry>
750 <entry>'MJPG'</entry>
751 <entry>Compressed format used by the Zoran driver</entry>
752 </row>
753 <row id="V4L2-PIX-FMT-PWC1">
754 <entry><constant>V4L2_PIX_FMT_PWC1</constant></entry>
755 <entry>'PWC1'</entry>
756 <entry>Compressed format of the PWC driver.</entry>
757 </row>
758 <row id="V4L2-PIX-FMT-PWC2">
759 <entry><constant>V4L2_PIX_FMT_PWC2</constant></entry>
760 <entry>'PWC2'</entry>
761 <entry>Compressed format of the PWC driver.</entry>
762 </row>
763 <row id="V4L2-PIX-FMT-SN9C10X">
764 <entry><constant>V4L2_PIX_FMT_SN9C10X</constant></entry>
765 <entry>'S910'</entry>
766 <entry>Compressed format of the SN9C102 driver.</entry>
767 </row>
768 <row id="V4L2-PIX-FMT-SN9C20X-I420">
769 <entry><constant>V4L2_PIX_FMT_SN9C20X_I420</constant></entry>
770 <entry>'S920'</entry>
771 <entry>YUV 4:2:0 format of the gspca sn9c20x driver.</entry>
772 </row>
773 <row id="V4L2-PIX-FMT-WNVA">
774 <entry><constant>V4L2_PIX_FMT_WNVA</constant></entry>
775 <entry>'WNVA'</entry>
776 <entry><para>Used by the Winnov Videum driver, <ulink
777url="http://www.thedirks.org/winnov/">
778http://www.thedirks.org/winnov/</ulink></para></entry>
779 </row>
780 <row id="V4L2-PIX-FMT-YYUV">
781 <entry><constant>V4L2_PIX_FMT_YYUV</constant></entry>
782 <entry>'YYUV'</entry>
783 <entry>unknown</entry>
784 </row>
785 </tbody>
786 </tgroup>
787 </table>
788 </section>
789
790 <!--
791Local Variables:
792mode: sgml
793sgml-parent-document: "v4l2.sgml"
794indent-tabs-mode: nil
795End:
796 -->
diff --git a/Documentation/DocBook/v4l/remote_controllers.xml b/Documentation/DocBook/v4l/remote_controllers.xml
new file mode 100644
index 000000000000..eb669537a641
--- /dev/null
+++ b/Documentation/DocBook/v4l/remote_controllers.xml
@@ -0,0 +1,170 @@
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 manufacturer has their own type of control. It is not rare that the same manufacturer to ship different types of controls, depending on the device.</para>
6<para>Unfortunately, during several years, there weren't any effort to uniform the IR keycodes under different boards. This resulted that the same IR keyname to be mapped completely different on different IR's. Due to that, V4L2 API now specifies a standard for mapping Media keys on IR.</para>
7<para>This standard should be used by both V4L/DVB drivers and userspace applications</para>
8<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>
9
10<table pgwide="1" frame="none" id="rc_standard_keymap">
11<title>IR default keymapping</title>
12<tgroup cols="3">
13&cs-str;
14<tbody valign="top">
15<row>
16<entry>Key code</entry>
17<entry>Meaning</entry>
18<entry>Key examples on IR</entry>
19</row>
20
21<row><entry><emphasis role="bold">Numeric keys</emphasis></entry></row>
22
23<row><entry><constant>KEY_0</constant></entry><entry>Keyboard digit 0</entry><entry>0</entry></row>
24<row><entry><constant>KEY_1</constant></entry><entry>Keyboard digit 1</entry><entry>1</entry></row>
25<row><entry><constant>KEY_2</constant></entry><entry>Keyboard digit 2</entry><entry>2</entry></row>
26<row><entry><constant>KEY_3</constant></entry><entry>Keyboard digit 3</entry><entry>3</entry></row>
27<row><entry><constant>KEY_4</constant></entry><entry>Keyboard digit 4</entry><entry>4</entry></row>
28<row><entry><constant>KEY_5</constant></entry><entry>Keyboard digit 5</entry><entry>5</entry></row>
29<row><entry><constant>KEY_6</constant></entry><entry>Keyboard digit 6</entry><entry>6</entry></row>
30<row><entry><constant>KEY_7</constant></entry><entry>Keyboard digit 7</entry><entry>7</entry></row>
31<row><entry><constant>KEY_8</constant></entry><entry>Keyboard digit 8</entry><entry>8</entry></row>
32<row><entry><constant>KEY_9</constant></entry><entry>Keyboard digit 9</entry><entry>9</entry></row>
33
34<row><entry><emphasis role="bold">Movie play control</emphasis></entry></row>
35
36<row><entry><constant>KEY_FORWARD</constant></entry><entry>Instantly advance in time</entry><entry>&gt;&gt; / FORWARD</entry></row>
37<row><entry><constant>KEY_BACK</constant></entry><entry>Instantly go back in time</entry><entry>&lt;&lt;&lt; / BACK</entry></row>
38<row><entry><constant>KEY_FASTFORWARD</constant></entry><entry>Play movie faster</entry><entry>&gt;&gt;&gt; / FORWARD</entry></row>
39<row><entry><constant>KEY_REWIND</constant></entry><entry>Play movie back</entry><entry>REWIND / BACKWARD</entry></row>
40<row><entry><constant>KEY_NEXT</constant></entry><entry>Select next chapter / sub-chapter / interval</entry><entry>NEXT / SKIP</entry></row>
41<row><entry><constant>KEY_PREVIOUS</constant></entry><entry>Select previous chapter / sub-chapter / interval</entry><entry>&lt;&lt; / PREV / PREVIOUS</entry></row>
42<row><entry><constant>KEY_AGAIN</constant></entry><entry>Repeat the video or a video interval</entry><entry>REPEAT / LOOP / RECALL</entry></row>
43<row><entry><constant>KEY_PAUSE</constant></entry><entry>Pause sroweam</entry><entry>PAUSE / FREEZE</entry></row>
44<row><entry><constant>KEY_PLAY</constant></entry><entry>Play movie at the normal timeshift</entry><entry>NORMAL TIMESHIFT / LIVE / &gt;</entry></row>
45<row><entry><constant>KEY_PLAYPAUSE</constant></entry><entry>Alternate between play and pause</entry><entry>PLAY / PAUSE</entry></row>
46<row><entry><constant>KEY_STOP</constant></entry><entry>Stop sroweam</entry><entry>STOP</entry></row>
47<row><entry><constant>KEY_RECORD</constant></entry><entry>Start/stop recording sroweam</entry><entry>CAPTURE / REC / RECORD/PAUSE</entry></row>
48<row><entry><constant>KEY_CAMERA</constant></entry><entry>Take a picture of the image</entry><entry>CAMERA ICON / CAPTURE / SNAPSHOT</entry></row>
49<row><entry><constant>KEY_SHUFFLE</constant></entry><entry>Enable shuffle mode</entry><entry>SHUFFLE</entry></row>
50<row><entry><constant>KEY_TIME</constant></entry><entry>Activate time shift mode</entry><entry>TIME SHIFT</entry></row>
51<row><entry><constant>KEY_TITLE</constant></entry><entry>Allow changing the chapter</entry><entry>CHAPTER</entry></row>
52<row><entry><constant>KEY_SUBTITLE</constant></entry><entry>Allow changing the subtitle</entry><entry>SUBTITLE</entry></row>
53
54<row><entry><emphasis role="bold">Image control</emphasis></entry></row>
55
56<row><entry><constant>KEY_BRIGHTNESSDOWN</constant></entry><entry>Decrease Brightness</entry><entry>BRIGHTNESS DECREASE</entry></row>
57<row><entry><constant>KEY_BRIGHTNESSUP</constant></entry><entry>Increase Brightness</entry><entry>BRIGHTNESS INCREASE</entry></row>
58
59<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>
60<row><entry><constant>KEY_EPG</constant></entry><entry>Open the Elecrowonic Play Guide (EPG)</entry><entry>EPG / GUIDE</entry></row>
61<row><entry><constant>KEY_TEXT</constant></entry><entry>Activate/change closed caption mode</entry><entry>CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX</entry></row>
62
63<row><entry><emphasis role="bold">Audio control</emphasis></entry></row>
64
65<row><entry><constant>KEY_AUDIO</constant></entry><entry>Change audio source</entry><entry>AUDIO SOURCE / AUDIO / MUSIC</entry></row>
66<row><entry><constant>KEY_MUTE</constant></entry><entry>Mute/unmute audio</entry><entry>MUTE / DEMUTE / UNMUTE</entry></row>
67<row><entry><constant>KEY_VOLUMEDOWN</constant></entry><entry>Decrease volume</entry><entry>VOLUME- / VOLUME DOWN</entry></row>
68<row><entry><constant>KEY_VOLUMEUP</constant></entry><entry>Increase volume</entry><entry>VOLUME+ / VOLUME UP</entry></row>
69<row><entry><constant>KEY_MODE</constant></entry><entry>Change sound mode</entry><entry>MONO/STEREO</entry></row>
70<row><entry><constant>KEY_LANGUAGE</constant></entry><entry>Select Language</entry><entry>1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL</entry></row>
71
72<row><entry><emphasis role="bold">Channel control</emphasis></entry></row>
73
74<row><entry><constant>KEY_CHANNEL</constant></entry><entry>Go to the next favorite channel</entry><entry>ALT / CHANNEL / CH SURFING / SURF / FAV</entry></row>
75<row><entry><constant>KEY_CHANNELDOWN</constant></entry><entry>Decrease channel sequencially</entry><entry>CHANNEL - / CHANNEL DOWN / DOWN</entry></row>
76<row><entry><constant>KEY_CHANNELUP</constant></entry><entry>Increase channel sequencially</entry><entry>CHANNEL + / CHANNEL UP / UP</entry></row>
77<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>
78<row><entry><constant>KEY_SEARCH</constant></entry><entry>Start channel autoscan</entry><entry>SCAN / AUTOSCAN</entry></row>
79
80<row><entry><emphasis role="bold">Colored keys</emphasis></entry></row>
81
82<row><entry><constant>KEY_BLUE</constant></entry><entry>IR Blue key</entry><entry>BLUE</entry></row>
83<row><entry><constant>KEY_GREEN</constant></entry><entry>IR Green Key</entry><entry>GREEN</entry></row>
84<row><entry><constant>KEY_RED</constant></entry><entry>IR Red key</entry><entry>RED</entry></row>
85<row><entry><constant>KEY_YELLOW</constant></entry><entry>IR Yellow key</entry><entry> YELLOW</entry></row>
86
87<row><entry><emphasis role="bold">Media selection</emphasis></entry></row>
88
89<row><entry><constant>KEY_CD</constant></entry><entry>Change input source to Compact Disc</entry><entry>CD</entry></row>
90<row><entry><constant>KEY_DVD</constant></entry><entry>Change input to DVD</entry><entry>DVD / DVD MENU</entry></row>
91<row><entry><constant>KEY_EJECTCLOSECD</constant></entry><entry>Open/close the CD/DVD player</entry><entry>-&gt; ) / CLOSE / OPEN</entry></row>
92
93<row><entry><constant>KEY_MEDIA</constant></entry><entry>Turn on/off Media application</entry><entry>PC/TV / TURN ON/OFF APP</entry></row>
94<row><entry><constant>KEY_PC</constant></entry><entry>Selects from TV to PC</entry><entry>PC</entry></row>
95<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>
96<row><entry><constant>KEY_TV</constant></entry><entry>Select tv mode</entry><entry>TV / LIVE TV</entry></row>
97<row><entry><constant>KEY_TV2</constant></entry><entry>Select Cable mode</entry><entry>AIR/CBL</entry></row>
98<row><entry><constant>KEY_VCR</constant></entry><entry>Select VCR mode</entry><entry>VCR MODE / DTR</entry></row>
99<row><entry><constant>KEY_VIDEO</constant></entry><entry>Alternate between input modes</entry><entry>SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO</entry></row>
100
101<row><entry><emphasis role="bold">Power control</emphasis></entry></row>
102
103<row><entry><constant>KEY_POWER</constant></entry><entry>Turn on/off computer</entry><entry>SYSTEM POWER / COMPUTER POWER</entry></row>
104<row><entry><constant>KEY_POWER2</constant></entry><entry>Turn on/off application</entry><entry>TV ON/OFF / POWER</entry></row>
105<row><entry><constant>KEY_SLEEP</constant></entry><entry>Activate sleep timer</entry><entry>SLEEP / SLEEP TIMER</entry></row>
106<row><entry><constant>KEY_SUSPEND</constant></entry><entry>Put computer into suspend mode</entry><entry>STANDBY / SUSPEND</entry></row>
107
108<row><entry><emphasis role="bold">Window control</emphasis></entry></row>
109
110<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>
111<row><entry><constant>KEY_CYCLEWINDOWS</constant></entry><entry>Minimize windows and move to the next one</entry><entry>ALT-TAB / MINIMIZE / DESKTOP</entry></row>
112<row><entry><constant>KEY_FAVORITES</constant></entry><entry>Open the favorites sroweam window</entry><entry>TV WALL / Favorites</entry></row>
113<row><entry><constant>KEY_MENU</constant></entry><entry>Call application menu</entry><entry>2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL</entry></row>
114<row><entry><constant>KEY_NEW</constant></entry><entry>Open/Close Picture in Picture</entry><entry>PIP</entry></row>
115<row><entry><constant>KEY_OK</constant></entry><entry>Send a confirmation code to application</entry><entry>OK / ENTER / RETURN</entry></row>
116<row><entry><constant>KEY_SCREEN</constant></entry><entry>Select screen aspect ratio</entry><entry>4:3 16:9 SELECT</entry></row>
117<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>
118
119<row><entry><emphasis role="bold">Navigation keys</emphasis></entry></row>
120
121<row><entry><constant>KEY_ESC</constant></entry><entry>Cancel current operation</entry><entry>CANCEL / BACK</entry></row>
122<row><entry><constant>KEY_HELP</constant></entry><entry>Open a Help window</entry><entry>HELP</entry></row>
123<row><entry><constant>KEY_HOMEPAGE</constant></entry><entry>Navigate to Homepage</entry><entry>HOME</entry></row>
124<row><entry><constant>KEY_INFO</constant></entry><entry>Open On Screen Display</entry><entry>DISPLAY INFORMATION / OSD</entry></row>
125<row><entry><constant>KEY_WWW</constant></entry><entry>Open the default browser</entry><entry>WEB</entry></row>
126<row><entry><constant>KEY_UP</constant></entry><entry>Up key</entry><entry>UP</entry></row>
127<row><entry><constant>KEY_DOWN</constant></entry><entry>Down key</entry><entry>DOWN</entry></row>
128<row><entry><constant>KEY_LEFT</constant></entry><entry>Left key</entry><entry>LEFT</entry></row>
129<row><entry><constant>KEY_RIGHT</constant></entry><entry>Right key</entry><entry>RIGHT</entry></row>
130
131<row><entry><emphasis role="bold">Miscelaneous keys</emphasis></entry></row>
132
133<row><entry><constant>KEY_DOT</constant></entry><entry>Return a dot</entry><entry>.</entry></row>
134<row><entry><constant>KEY_FN</constant></entry><entry>Select a function</entry><entry>FUNCTION</entry></row>
135
136</tbody>
137</tgroup>
138</table>
139
140<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>
141
142<table pgwide="1" frame="none" id="rc_keymap_notes">
143<title>Notes</title>
144<tgroup cols="1">
145&cs-str;
146<tbody valign="top">
147<row>
148<entry>On simpler IR's, without separate channel keys, you need to map UP as <constant>KEY_CHANNELUP</constant></entry>
149</row><row>
150<entry>On simpler IR's, without separate channel keys, you need to map DOWN as <constant>KEY_CHANNELDOWN</constant></entry>
151</row><row>
152<entry>On simpler IR's, without separate volume keys, you need to map LEFT as <constant>KEY_VOLUMEDOWN</constant></entry>
153</row><row>
154<entry>On simpler IR's, without separate volume keys, you need to map RIGHT as <constant>KEY_VOLUMEUP</constant></entry>
155</row>
156</tbody>
157</tgroup>
158</table>
159
160</section>
161
162<section id="Remote_controllers_table_change">
163<title>Changing default Remote Controller mappings</title>
164<para>The event interface provides two ioctls to be used against
165the /dev/input/event device, to allow changing the default
166keymapping.</para>
167
168<para>This program demonstrates how to replace the keymap tables.</para>
169&sub-keytable-c;
170</section>
diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml
new file mode 100644
index 000000000000..97801725b976
--- /dev/null
+++ b/Documentation/DocBook/v4l/v4l2.xml
@@ -0,0 +1,481 @@
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@radix.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 </authorgroup>
78
79 <copyright>
80 <year>1999</year>
81 <year>2000</year>
82 <year>2001</year>
83 <year>2002</year>
84 <year>2003</year>
85 <year>2004</year>
86 <year>2005</year>
87 <year>2006</year>
88 <year>2007</year>
89 <year>2008</year>
90 <year>2009</year>
91 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
92Rubli, Andy Walls, Mauro Carvalho Chehab</holder>
93 </copyright>
94 <legalnotice>
95 <para>Except when explicitly stated as GPL, programming examples within
96 this part can be used and distributed without restrictions.</para>
97 </legalnotice>
98 <revhistory>
99 <!-- Put document revisions here, newest first. -->
100 <!-- API revisions (changes and additions of defines, enums,
101structs, ioctls) must be noted in more detail in the history chapter
102(compat.sgml), along with the possible impact on existing drivers and
103applications. -->
104
105 <revision>
106 <revnumber>2.6.32</revnumber>
107 <date>2009-08-31</date>
108 <authorinitials>mcc</authorinitials>
109 <revremark>Now, revisions will match the kernel version where
110the V4L2 API changes will be used by the Linux Kernel.
111Also added Remote Controller chapter.</revremark>
112 </revision>
113
114 <revision>
115 <revnumber>0.29</revnumber>
116 <date>2009-08-26</date>
117 <authorinitials>ev</authorinitials>
118 <revremark>Added documentation for string controls and for FM Transmitter controls.</revremark>
119 </revision>
120
121 <revision>
122 <revnumber>0.28</revnumber>
123 <date>2009-08-26</date>
124 <authorinitials>gl</authorinitials>
125 <revremark>Added V4L2_CID_BAND_STOP_FILTER documentation.</revremark>
126 </revision>
127
128 <revision>
129 <revnumber>0.27</revnumber>
130 <date>2009-08-15</date>
131 <authorinitials>mcc</authorinitials>
132 <revremark>Added libv4l and Remote Controller documentation;
133added v4l2grab and keytable application examples.</revremark>
134 </revision>
135
136 <revision>
137 <revnumber>0.26</revnumber>
138 <date>2009-07-23</date>
139 <authorinitials>hv</authorinitials>
140 <revremark>Finalized the RDS capture API. Added modulator and RDS encoder
141capabilities. Added support for string controls.</revremark>
142 </revision>
143
144 <revision>
145 <revnumber>0.25</revnumber>
146 <date>2009-01-18</date>
147 <authorinitials>hv</authorinitials>
148 <revremark>Added pixel formats VYUY, NV16 and NV61, and changed
149the debug ioctls VIDIOC_DBG_G/S_REGISTER and VIDIOC_DBG_G_CHIP_IDENT.
150Added camera controls V4L2_CID_ZOOM_ABSOLUTE, V4L2_CID_ZOOM_RELATIVE,
151V4L2_CID_ZOOM_CONTINUOUS and V4L2_CID_PRIVACY.</revremark>
152 </revision>
153
154 <revision>
155 <revnumber>0.24</revnumber>
156 <date>2008-03-04</date>
157 <authorinitials>mhs</authorinitials>
158 <revremark>Added pixel formats Y16 and SBGGR16, new controls
159and a camera controls class. Removed VIDIOC_G/S_MPEGCOMP.</revremark>
160 </revision>
161
162 <revision>
163 <revnumber>0.23</revnumber>
164 <date>2007-08-30</date>
165 <authorinitials>mhs</authorinitials>
166 <revremark>Fixed a typo in VIDIOC_DBG_G/S_REGISTER.
167Clarified the byte order of packed pixel formats.</revremark>
168 </revision>
169
170 <revision>
171 <revnumber>0.22</revnumber>
172 <date>2007-08-29</date>
173 <authorinitials>mhs</authorinitials>
174 <revremark>Added the Video Output Overlay interface, new MPEG
175controls, V4L2_FIELD_INTERLACED_TB and V4L2_FIELD_INTERLACED_BT,
176VIDIOC_DBG_G/S_REGISTER, VIDIOC_(TRY_)ENCODER_CMD,
177VIDIOC_G_CHIP_IDENT, VIDIOC_G_ENC_INDEX, new pixel formats.
178Clarifications in the cropping chapter, about RGB pixel formats, the
179mmap(), poll(), select(), read() and write() functions. Typographical
180fixes.</revremark>
181 </revision>
182
183 <revision>
184 <revnumber>0.21</revnumber>
185 <date>2006-12-19</date>
186 <authorinitials>mhs</authorinitials>
187 <revremark>Fixed a link in the VIDIOC_G_EXT_CTRLS section.</revremark>
188 </revision>
189
190 <revision>
191 <revnumber>0.20</revnumber>
192 <date>2006-11-24</date>
193 <authorinitials>mhs</authorinitials>
194 <revremark>Clarified the purpose of the audioset field in
195struct v4l2_input and v4l2_output.</revremark>
196 </revision>
197
198 <revision>
199 <revnumber>0.19</revnumber>
200 <date>2006-10-19</date>
201 <authorinitials>mhs</authorinitials>
202 <revremark>Documented V4L2_PIX_FMT_RGB444.</revremark>
203 </revision>
204
205 <revision>
206 <revnumber>0.18</revnumber>
207 <date>2006-10-18</date>
208 <authorinitials>mhs</authorinitials>
209 <revremark>Added the description of extended controls by Hans
210Verkuil. Linked V4L2_PIX_FMT_MPEG to V4L2_CID_MPEG_STREAM_TYPE.</revremark>
211 </revision>
212
213 <revision>
214 <revnumber>0.17</revnumber>
215 <date>2006-10-12</date>
216 <authorinitials>mhs</authorinitials>
217 <revremark>Corrected V4L2_PIX_FMT_HM12 description.</revremark>
218 </revision>
219
220 <revision>
221 <revnumber>0.16</revnumber>
222 <date>2006-10-08</date>
223 <authorinitials>mhs</authorinitials>
224 <revremark>VIDIOC_ENUM_FRAMESIZES and
225VIDIOC_ENUM_FRAMEINTERVALS are now part of the API.</revremark>
226 </revision>
227
228 <revision>
229 <revnumber>0.15</revnumber>
230 <date>2006-09-23</date>
231 <authorinitials>mhs</authorinitials>
232 <revremark>Cleaned up the bibliography, added BT.653 and
233BT.1119. capture.c/start_capturing() for user pointer I/O did not
234initialize the buffer index. Documented the V4L MPEG and MJPEG
235VID_TYPEs and V4L2_PIX_FMT_SBGGR8. Updated the list of reserved pixel
236formats. See the history chapter for API changes.</revremark>
237 </revision>
238
239 <revision>
240 <revnumber>0.14</revnumber>
241 <date>2006-09-14</date>
242 <authorinitials>mr</authorinitials>
243 <revremark>Added VIDIOC_ENUM_FRAMESIZES and
244VIDIOC_ENUM_FRAMEINTERVALS proposal for frame format enumeration of
245digital devices.</revremark>
246 </revision>
247
248 <revision>
249 <revnumber>0.13</revnumber>
250 <date>2006-04-07</date>
251 <authorinitials>mhs</authorinitials>
252 <revremark>Corrected the description of struct v4l2_window
253clips. New V4L2_STD_ and V4L2_TUNER_MODE_LANG1_LANG2
254defines.</revremark>
255 </revision>
256
257 <revision>
258 <revnumber>0.12</revnumber>
259 <date>2006-02-03</date>
260 <authorinitials>mhs</authorinitials>
261 <revremark>Corrected the description of struct
262v4l2_captureparm and v4l2_outputparm.</revremark>
263 </revision>
264
265 <revision>
266 <revnumber>0.11</revnumber>
267 <date>2006-01-27</date>
268 <authorinitials>mhs</authorinitials>
269 <revremark>Improved the description of struct
270v4l2_tuner.</revremark>
271 </revision>
272
273 <revision>
274 <revnumber>0.10</revnumber>
275 <date>2006-01-10</date>
276 <authorinitials>mhs</authorinitials>
277 <revremark>VIDIOC_G_INPUT and VIDIOC_S_PARM
278clarifications.</revremark>
279 </revision>
280
281 <revision>
282 <revnumber>0.9</revnumber>
283 <date>2005-11-27</date>
284 <authorinitials>mhs</authorinitials>
285 <revremark>Improved the 525 line numbering diagram. Hans
286Verkuil and I rewrote the sliced VBI section. He also contributed a
287VIDIOC_LOG_STATUS page. Fixed VIDIOC_S_STD call in the video standard
288selection example. Various updates.</revremark>
289 </revision>
290
291 <revision>
292 <revnumber>0.8</revnumber>
293 <date>2004-10-04</date>
294 <authorinitials>mhs</authorinitials>
295 <revremark>Somehow a piece of junk slipped into the capture
296example, removed.</revremark>
297 </revision>
298
299 <revision>
300 <revnumber>0.7</revnumber>
301 <date>2004-09-19</date>
302 <authorinitials>mhs</authorinitials>
303 <revremark>Fixed video standard selection, control
304enumeration, downscaling and aspect example. Added read and user
305pointer i/o to video capture example.</revremark>
306 </revision>
307
308 <revision>
309 <revnumber>0.6</revnumber>
310 <date>2004-08-01</date>
311 <authorinitials>mhs</authorinitials>
312 <revremark>v4l2_buffer changes, added video capture example,
313various corrections.</revremark>
314 </revision>
315
316 <revision>
317 <revnumber>0.5</revnumber>
318 <date>2003-11-05</date>
319 <authorinitials>mhs</authorinitials>
320 <revremark>Pixel format erratum.</revremark>
321 </revision>
322
323 <revision>
324 <revnumber>0.4</revnumber>
325 <date>2003-09-17</date>
326 <authorinitials>mhs</authorinitials>
327 <revremark>Corrected source and Makefile to generate a PDF.
328SGML fixes. Added latest API changes. Closed gaps in the history
329chapter.</revremark>
330 </revision>
331
332 <revision>
333 <revnumber>0.3</revnumber>
334 <date>2003-02-05</date>
335 <authorinitials>mhs</authorinitials>
336 <revremark>Another draft, more corrections.</revremark>
337 </revision>
338
339 <revision>
340 <revnumber>0.2</revnumber>
341 <date>2003-01-15</date>
342 <authorinitials>mhs</authorinitials>
343 <revremark>Second draft, with corrections pointed out by Gerd
344Knorr.</revremark>
345 </revision>
346
347 <revision>
348 <revnumber>0.1</revnumber>
349 <date>2002-12-01</date>
350 <authorinitials>mhs</authorinitials>
351 <revremark>First draft, based on documentation by Bill Dirks
352and discussions on the V4L mailing list.</revremark>
353 </revision>
354 </revhistory>
355</partinfo>
356
357<title>Video for Linux Two API Specification</title>
358 <subtitle>Revision 2.6.32</subtitle>
359
360 <chapter id="common">
361 &sub-common;
362 </chapter>
363
364 <chapter id="pixfmt">
365 &sub-pixfmt;
366 </chapter>
367
368 <chapter id="io">
369 &sub-io;
370 </chapter>
371
372 <chapter id="devices">
373 <title>Interfaces</title>
374
375 <section id="capture"> &sub-dev-capture; </section>
376 <section id="overlay"> &sub-dev-overlay; </section>
377 <section id="output"> &sub-dev-output; </section>
378 <section id="osd"> &sub-dev-osd; </section>
379 <section id="codec"> &sub-dev-codec; </section>
380 <section id="effect"> &sub-dev-effect; </section>
381 <section id="raw-vbi"> &sub-dev-raw-vbi; </section>
382 <section id="sliced"> &sub-dev-sliced-vbi; </section>
383 <section id="ttx"> &sub-dev-teletext; </section>
384 <section id="radio"> &sub-dev-radio; </section>
385 <section id="rds"> &sub-dev-rds; </section>
386 </chapter>
387
388 <chapter id="driver">
389 &sub-driver;
390 </chapter>
391
392 <chapter id="libv4l">
393 &sub-libv4l;
394 </chapter>
395
396 <chapter id="compat">
397 &sub-compat;
398 </chapter>
399
400 <appendix id="function_ref">
401 <title>Function Reference</title>
402 <reference id="user-func">
403
404 <!-- Keep this alphabetically sorted. -->
405
406 &sub-close;
407 &sub-ioctl;
408 <!-- All ioctls go here. -->
409 &sub-cropcap;
410 &sub-dbg-g-chip-ident;
411 &sub-dbg-g-register;
412 &sub-encoder-cmd;
413 &sub-enumaudio;
414 &sub-enumaudioout;
415 &sub-enum-fmt;
416 &sub-enum-framesizes;
417 &sub-enum-frameintervals;
418 &sub-enuminput;
419 &sub-enumoutput;
420 &sub-enumstd;
421 &sub-g-audio;
422 &sub-g-audioout;
423 &sub-g-crop;
424 &sub-g-ctrl;
425 &sub-g-enc-index;
426 &sub-g-ext-ctrls;
427 &sub-g-fbuf;
428 &sub-g-fmt;
429 &sub-g-frequency;
430 &sub-g-input;
431 &sub-g-jpegcomp;
432 &sub-g-modulator;
433 &sub-g-output;
434 &sub-g-parm;
435 &sub-g-priority;
436 &sub-g-sliced-vbi-cap;
437 &sub-g-std;
438 &sub-g-tuner;
439 &sub-log-status;
440 &sub-overlay;
441 &sub-qbuf;
442 &sub-querybuf;
443 &sub-querycap;
444 &sub-queryctrl;
445 &sub-querystd;
446 &sub-reqbufs;
447 &sub-s-hw-freq-seek;
448 &sub-streamon;
449 <!-- End of ioctls. -->
450 &sub-mmap;
451 &sub-munmap;
452 &sub-open;
453 &sub-poll;
454 &sub-read;
455 &sub-select;
456 &sub-write;
457 </reference>
458 </appendix>
459
460 <appendix id="videodev">
461 <title>Video For Linux Two Header File</title>
462 &sub-videodev2-h;
463 </appendix>
464
465 <appendix id="capture-example">
466 <title>Video Capture Example</title>
467 &sub-capture-c;
468 </appendix>
469
470 <appendix id="v4l2grab-example">
471 <title>Video Grabber example using libv4l</title>
472 <para>This program demonstrates how to grab V4L2 images in ppm format by
473using libv4l handlers. The advantage is that this grabber can potentially work
474with any V4L2 driver.</para>
475 &sub-v4l2grab-c;
476 </appendix>
477
478 &sub-media-indices;
479
480 &sub-biblio;
481
diff --git a/Documentation/DocBook/v4l/v4l2grab.c.xml b/Documentation/DocBook/v4l/v4l2grab.c.xml
new file mode 100644
index 000000000000..bed12e40be27
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vbi_525.gif b/Documentation/DocBook/v4l/vbi_525.gif
new file mode 100644
index 000000000000..5580b690d504
--- /dev/null
+++ b/Documentation/DocBook/v4l/vbi_525.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/vbi_525.pdf b/Documentation/DocBook/v4l/vbi_525.pdf
new file mode 100644
index 000000000000..9e72c25b208d
--- /dev/null
+++ b/Documentation/DocBook/v4l/vbi_525.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/vbi_625.gif b/Documentation/DocBook/v4l/vbi_625.gif
new file mode 100644
index 000000000000..34e3251983c4
--- /dev/null
+++ b/Documentation/DocBook/v4l/vbi_625.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/vbi_625.pdf b/Documentation/DocBook/v4l/vbi_625.pdf
new file mode 100644
index 000000000000..765235e33a4d
--- /dev/null
+++ b/Documentation/DocBook/v4l/vbi_625.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/vbi_hsync.gif b/Documentation/DocBook/v4l/vbi_hsync.gif
new file mode 100644
index 000000000000..b02434d3b356
--- /dev/null
+++ b/Documentation/DocBook/v4l/vbi_hsync.gif
Binary files differ
diff --git a/Documentation/DocBook/v4l/vbi_hsync.pdf b/Documentation/DocBook/v4l/vbi_hsync.pdf
new file mode 100644
index 000000000000..200b668189bf
--- /dev/null
+++ b/Documentation/DocBook/v4l/vbi_hsync.pdf
Binary files differ
diff --git a/Documentation/DocBook/v4l/videodev2.h.xml b/Documentation/DocBook/v4l/videodev2.h.xml
new file mode 100644
index 000000000000..6a8e13940699
--- /dev/null
+++ b/Documentation/DocBook/v4l/videodev2.h.xml
@@ -0,0 +1,1639 @@
1<programlisting>
2/*
3 * Video for Linux Two header file
4 *
5 * Copyright (C) 1999-2007 the contributors
6 *
7 * This program is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 2 of the License, or
10 * (at your option) any later version.
11 *
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * Alternatively you can redistribute this file under the terms of the
18 * BSD license as stated below:
19 *
20 * Redistribution and use in source and binary forms, with or without
21 * modification, are permitted provided that the following conditions
22 * are met:
23 * 1. Redistributions of source code must retain the above copyright
24 * notice, this list of conditions and the following disclaimer.
25 * 2. Redistributions in binary form must reproduce the above copyright
26 * notice, this list of conditions and the following disclaimer in
27 * the documentation and/or other materials provided with the
28 * distribution.
29 * 3. The names of its contributors may not be used to endorse or promote
30 * products derived from this software without specific prior written
31 * permission.
32 *
33 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
34 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
35 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
36 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
37 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
38 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
39 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
40 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
41 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
42 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
43 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44 *
45 * Header file for v4l or V4L2 drivers and applications
46 * with public API.
47 * All kernel-specific stuff were moved to media/v4l2-dev.h, so
48 * no #if __KERNEL tests are allowed here
49 *
50 * See http://linuxtv.org for more info
51 *
52 * Author: Bill Dirks &lt;bill@thedirks.org&gt;
53 * Justin Schoeman
54 * Hans Verkuil &lt;hverkuil@xs4all.nl&gt;
55 * et al.
56 */
57#ifndef __LINUX_VIDEODEV2_H
58#define __LINUX_VIDEODEV2_H
59
60#ifdef __KERNEL__
61#include &lt;linux/time.h&gt; /* need struct timeval */
62#else
63#include &lt;sys/time.h&gt;
64#endif
65#include &lt;linux/compiler.h&gt;
66#include &lt;linux/ioctl.h&gt;
67#include &lt;linux/types.h&gt;
68
69/*
70 * Common stuff for both V4L1 and V4L2
71 * Moved from videodev.h
72 */
73#define VIDEO_MAX_FRAME 32
74
75#ifndef __KERNEL__
76
77/* These defines are V4L1 specific and should not be used with the V4L2 API!
78 They will be removed from this header in the future. */
79
80#define VID_TYPE_CAPTURE 1 /* Can capture */
81#define VID_TYPE_TUNER 2 /* Can tune */
82#define VID_TYPE_TELETEXT 4 /* Does teletext */
83#define VID_TYPE_OVERLAY 8 /* Overlay onto frame buffer */
84#define VID_TYPE_CHROMAKEY 16 /* Overlay by chromakey */
85#define VID_TYPE_CLIPPING 32 /* Can clip */
86#define VID_TYPE_FRAMERAM 64 /* Uses the frame buffer memory */
87#define VID_TYPE_SCALES 128 /* Scalable */
88#define VID_TYPE_MONOCHROME 256 /* Monochrome only */
89#define VID_TYPE_SUBCAPTURE 512 /* Can capture subareas of the image */
90#define VID_TYPE_MPEG_DECODER 1024 /* Can decode MPEG streams */
91#define VID_TYPE_MPEG_ENCODER 2048 /* Can encode MPEG streams */
92#define VID_TYPE_MJPEG_DECODER 4096 /* Can decode MJPEG streams */
93#define VID_TYPE_MJPEG_ENCODER 8192 /* Can encode MJPEG streams */
94#endif
95
96/*
97 * M I S C E L L A N E O U S
98 */
99
100/* Four-character-code (FOURCC) */
101#define v4l2_fourcc(a, b, c, d)\
102 ((__u32)(a) | ((__u32)(b) &lt;&lt; 8) | ((__u32)(c) &lt;&lt; 16) | ((__u32)(d) &lt;&lt; 24))
103
104/*
105 * E N U M S
106 */
107enum <link linkend="v4l2-field">v4l2_field</link> {
108 V4L2_FIELD_ANY = 0, /* driver can choose from none,
109 top, bottom, interlaced
110 depending on whatever it thinks
111 is approximate ... */
112 V4L2_FIELD_NONE = 1, /* this device has no fields ... */
113 V4L2_FIELD_TOP = 2, /* top field only */
114 V4L2_FIELD_BOTTOM = 3, /* bottom field only */
115 V4L2_FIELD_INTERLACED = 4, /* both fields interlaced */
116 V4L2_FIELD_SEQ_TB = 5, /* both fields sequential into one
117 buffer, top-bottom order */
118 V4L2_FIELD_SEQ_BT = 6, /* same as above + bottom-top order */
119 V4L2_FIELD_ALTERNATE = 7, /* both fields alternating into
120 separate buffers */
121 V4L2_FIELD_INTERLACED_TB = 8, /* both fields interlaced, top field
122 first and the top field is
123 transmitted first */
124 V4L2_FIELD_INTERLACED_BT = 9, /* both fields interlaced, top field
125 first and the bottom field is
126 transmitted first */
127};
128#define V4L2_FIELD_HAS_TOP(field) \
129 ((field) == V4L2_FIELD_TOP ||\
130 (field) == V4L2_FIELD_INTERLACED ||\
131 (field) == V4L2_FIELD_INTERLACED_TB ||\
132 (field) == V4L2_FIELD_INTERLACED_BT ||\
133 (field) == V4L2_FIELD_SEQ_TB ||\
134 (field) == V4L2_FIELD_SEQ_BT)
135#define V4L2_FIELD_HAS_BOTTOM(field) \
136 ((field) == V4L2_FIELD_BOTTOM ||\
137 (field) == V4L2_FIELD_INTERLACED ||\
138 (field) == V4L2_FIELD_INTERLACED_TB ||\
139 (field) == V4L2_FIELD_INTERLACED_BT ||\
140 (field) == V4L2_FIELD_SEQ_TB ||\
141 (field) == V4L2_FIELD_SEQ_BT)
142#define V4L2_FIELD_HAS_BOTH(field) \
143 ((field) == V4L2_FIELD_INTERLACED ||\
144 (field) == V4L2_FIELD_INTERLACED_TB ||\
145 (field) == V4L2_FIELD_INTERLACED_BT ||\
146 (field) == V4L2_FIELD_SEQ_TB ||\
147 (field) == V4L2_FIELD_SEQ_BT)
148
149enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> {
150 V4L2_BUF_TYPE_VIDEO_CAPTURE = 1,
151 V4L2_BUF_TYPE_VIDEO_OUTPUT = 2,
152 V4L2_BUF_TYPE_VIDEO_OVERLAY = 3,
153 V4L2_BUF_TYPE_VBI_CAPTURE = 4,
154 V4L2_BUF_TYPE_VBI_OUTPUT = 5,
155 V4L2_BUF_TYPE_SLICED_VBI_CAPTURE = 6,
156 V4L2_BUF_TYPE_SLICED_VBI_OUTPUT = 7,
157#if 1 /*KEEP*/
158 /* Experimental */
159 V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY = 8,
160#endif
161 V4L2_BUF_TYPE_PRIVATE = 0x80,
162};
163
164enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> {
165 V4L2_CTRL_TYPE_INTEGER = 1,
166 V4L2_CTRL_TYPE_BOOLEAN = 2,
167 V4L2_CTRL_TYPE_MENU = 3,
168 V4L2_CTRL_TYPE_BUTTON = 4,
169 V4L2_CTRL_TYPE_INTEGER64 = 5,
170 V4L2_CTRL_TYPE_CTRL_CLASS = 6,
171 V4L2_CTRL_TYPE_STRING = 7,
172};
173
174enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> {
175 V4L2_TUNER_RADIO = 1,
176 V4L2_TUNER_ANALOG_TV = 2,
177 V4L2_TUNER_DIGITAL_TV = 3,
178};
179
180enum <link linkend="v4l2-memory">v4l2_memory</link> {
181 V4L2_MEMORY_MMAP = 1,
182 V4L2_MEMORY_USERPTR = 2,
183 V4L2_MEMORY_OVERLAY = 3,
184};
185
186/* see also http://vektor.theorem.ca/graphics/ycbcr/ */
187enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> {
188 /* ITU-R 601 -- broadcast NTSC/PAL */
189 V4L2_COLORSPACE_SMPTE170M = 1,
190
191 /* 1125-Line (US) HDTV */
192 V4L2_COLORSPACE_SMPTE240M = 2,
193
194 /* HD and modern captures. */
195 V4L2_COLORSPACE_REC709 = 3,
196
197 /* broken BT878 extents (601, luma range 16-253 instead of 16-235) */
198 V4L2_COLORSPACE_BT878 = 4,
199
200 /* These should be useful. Assume 601 extents. */
201 V4L2_COLORSPACE_470_SYSTEM_M = 5,
202 V4L2_COLORSPACE_470_SYSTEM_BG = 6,
203
204 /* I know there will be cameras that send this. So, this is
205 * unspecified chromaticities and full 0-255 on each of the
206 * Y'CbCr components
207 */
208 V4L2_COLORSPACE_JPEG = 7,
209
210 /* For RGB colourspaces, this is probably a good start. */
211 V4L2_COLORSPACE_SRGB = 8,
212};
213
214enum <link linkend="v4l2-priority">v4l2_priority</link> {
215 V4L2_PRIORITY_UNSET = 0, /* not initialized */
216 V4L2_PRIORITY_BACKGROUND = 1,
217 V4L2_PRIORITY_INTERACTIVE = 2,
218 V4L2_PRIORITY_RECORD = 3,
219 V4L2_PRIORITY_DEFAULT = V4L2_PRIORITY_INTERACTIVE,
220};
221
222struct <link linkend="v4l2-rect">v4l2_rect</link> {
223 __s32 left;
224 __s32 top;
225 __s32 width;
226 __s32 height;
227};
228
229struct <link linkend="v4l2-fract">v4l2_fract</link> {
230 __u32 numerator;
231 __u32 denominator;
232};
233
234/*
235 * D R I V E R C A P A B I L I T I E S
236 */
237struct <link linkend="v4l2-capability">v4l2_capability</link> {
238 __u8 driver[16]; /* i.e.ie; "bttv" */
239 __u8 card[32]; /* i.e.ie; "Hauppauge WinTV" */
240 __u8 bus_info[32]; /* "PCI:" + pci_name(pci_dev) */
241 __u32 version; /* should use KERNEL_VERSION() */
242 __u32 capabilities; /* Device capabilities */
243 __u32 reserved[4];
244};
245
246/* Values for 'capabilities' field */
247#define V4L2_CAP_VIDEO_CAPTURE 0x00000001 /* Is a video capture device */
248#define V4L2_CAP_VIDEO_OUTPUT 0x00000002 /* Is a video output device */
249#define V4L2_CAP_VIDEO_OVERLAY 0x00000004 /* Can do video overlay */
250#define V4L2_CAP_VBI_CAPTURE 0x00000010 /* Is a raw VBI capture device */
251#define V4L2_CAP_VBI_OUTPUT 0x00000020 /* Is a raw VBI output device */
252#define V4L2_CAP_SLICED_VBI_CAPTURE 0x00000040 /* Is a sliced VBI capture device */
253#define V4L2_CAP_SLICED_VBI_OUTPUT 0x00000080 /* Is a sliced VBI output device */
254#define V4L2_CAP_RDS_CAPTURE 0x00000100 /* RDS data capture */
255#define V4L2_CAP_VIDEO_OUTPUT_OVERLAY 0x00000200 /* Can do video output overlay */
256#define V4L2_CAP_HW_FREQ_SEEK 0x00000400 /* Can do hardware frequency seek */
257#define V4L2_CAP_RDS_OUTPUT 0x00000800 /* Is an RDS encoder */
258
259#define V4L2_CAP_TUNER 0x00010000 /* has a tuner */
260#define V4L2_CAP_AUDIO 0x00020000 /* has audio support */
261#define V4L2_CAP_RADIO 0x00040000 /* is a radio device */
262#define V4L2_CAP_MODULATOR 0x00080000 /* has a modulator */
263
264#define V4L2_CAP_READWRITE 0x01000000 /* read/write systemcalls */
265#define V4L2_CAP_ASYNCIO 0x02000000 /* async I/O */
266#define V4L2_CAP_STREAMING 0x04000000 /* streaming I/O ioctls */
267
268/*
269 * V I D E O I M A G E F O R M A T
270 */
271struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> {
272 __u32 width;
273 __u32 height;
274 __u32 pixelformat;
275 enum <link linkend="v4l2-field">v4l2_field</link> field;
276 __u32 bytesperline; /* for padding, zero if unused */
277 __u32 sizeimage;
278 enum <link linkend="v4l2-colorspace">v4l2_colorspace</link> colorspace;
279 __u32 priv; /* private data, depends on pixelformat */
280};
281
282/* Pixel format FOURCC depth Description */
283
284/* RGB formats */
285#define <link linkend="V4L2-PIX-FMT-RGB332">V4L2_PIX_FMT_RGB332</link> v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */
286#define <link linkend="V4L2-PIX-FMT-RGB444">V4L2_PIX_FMT_RGB444</link> v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */
287#define <link linkend="V4L2-PIX-FMT-RGB555">V4L2_PIX_FMT_RGB555</link> v4l2_fourcc('R', 'G', 'B', 'O') /* 16 RGB-5-5-5 */
288#define <link linkend="V4L2-PIX-FMT-RGB565">V4L2_PIX_FMT_RGB565</link> v4l2_fourcc('R', 'G', 'B', 'P') /* 16 RGB-5-6-5 */
289#define <link linkend="V4L2-PIX-FMT-RGB555X">V4L2_PIX_FMT_RGB555X</link> v4l2_fourcc('R', 'G', 'B', 'Q') /* 16 RGB-5-5-5 BE */
290#define <link linkend="V4L2-PIX-FMT-RGB565X">V4L2_PIX_FMT_RGB565X</link> v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */
291#define <link linkend="V4L2-PIX-FMT-BGR24">V4L2_PIX_FMT_BGR24</link> v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */
292#define <link linkend="V4L2-PIX-FMT-RGB24">V4L2_PIX_FMT_RGB24</link> v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */
293#define <link linkend="V4L2-PIX-FMT-BGR32">V4L2_PIX_FMT_BGR32</link> v4l2_fourcc('B', 'G', 'R', '4') /* 32 BGR-8-8-8-8 */
294#define <link linkend="V4L2-PIX-FMT-RGB32">V4L2_PIX_FMT_RGB32</link> v4l2_fourcc('R', 'G', 'B', '4') /* 32 RGB-8-8-8-8 */
295
296/* Grey formats */
297#define <link linkend="V4L2-PIX-FMT-GREY">V4L2_PIX_FMT_GREY</link> v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */
298#define <link linkend="V4L2-PIX-FMT-Y16">V4L2_PIX_FMT_Y16</link> v4l2_fourcc('Y', '1', '6', ' ') /* 16 Greyscale */
299
300/* Palette formats */
301#define <link linkend="V4L2-PIX-FMT-PAL8">V4L2_PIX_FMT_PAL8</link> v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */
302
303/* Luminance+Chrominance formats */
304#define <link linkend="V4L2-PIX-FMT-YVU410">V4L2_PIX_FMT_YVU410</link> v4l2_fourcc('Y', 'V', 'U', '9') /* 9 YVU 4:1:0 */
305#define <link linkend="V4L2-PIX-FMT-YVU420">V4L2_PIX_FMT_YVU420</link> v4l2_fourcc('Y', 'V', '1', '2') /* 12 YVU 4:2:0 */
306#define <link linkend="V4L2-PIX-FMT-YUYV">V4L2_PIX_FMT_YUYV</link> v4l2_fourcc('Y', 'U', 'Y', 'V') /* 16 YUV 4:2:2 */
307#define <link linkend="V4L2-PIX-FMT-YYUV">V4L2_PIX_FMT_YYUV</link> v4l2_fourcc('Y', 'Y', 'U', 'V') /* 16 YUV 4:2:2 */
308#define <link linkend="V4L2-PIX-FMT-YVYU">V4L2_PIX_FMT_YVYU</link> v4l2_fourcc('Y', 'V', 'Y', 'U') /* 16 YVU 4:2:2 */
309#define <link linkend="V4L2-PIX-FMT-UYVY">V4L2_PIX_FMT_UYVY</link> v4l2_fourcc('U', 'Y', 'V', 'Y') /* 16 YUV 4:2:2 */
310#define <link linkend="V4L2-PIX-FMT-VYUY">V4L2_PIX_FMT_VYUY</link> v4l2_fourcc('V', 'Y', 'U', 'Y') /* 16 YUV 4:2:2 */
311#define <link linkend="V4L2-PIX-FMT-YUV422P">V4L2_PIX_FMT_YUV422P</link> v4l2_fourcc('4', '2', '2', 'P') /* 16 YVU422 planar */
312#define <link linkend="V4L2-PIX-FMT-YUV411P">V4L2_PIX_FMT_YUV411P</link> v4l2_fourcc('4', '1', '1', 'P') /* 16 YVU411 planar */
313#define <link linkend="V4L2-PIX-FMT-Y41P">V4L2_PIX_FMT_Y41P</link> v4l2_fourcc('Y', '4', '1', 'P') /* 12 YUV 4:1:1 */
314#define <link linkend="V4L2-PIX-FMT-YUV444">V4L2_PIX_FMT_YUV444</link> v4l2_fourcc('Y', '4', '4', '4') /* 16 xxxxyyyy uuuuvvvv */
315#define <link linkend="V4L2-PIX-FMT-YUV555">V4L2_PIX_FMT_YUV555</link> v4l2_fourcc('Y', 'U', 'V', 'O') /* 16 YUV-5-5-5 */
316#define <link linkend="V4L2-PIX-FMT-YUV565">V4L2_PIX_FMT_YUV565</link> v4l2_fourcc('Y', 'U', 'V', 'P') /* 16 YUV-5-6-5 */
317#define <link linkend="V4L2-PIX-FMT-YUV32">V4L2_PIX_FMT_YUV32</link> v4l2_fourcc('Y', 'U', 'V', '4') /* 32 YUV-8-8-8-8 */
318#define <link linkend="V4L2-PIX-FMT-YUV410">V4L2_PIX_FMT_YUV410</link> v4l2_fourcc('Y', 'U', 'V', '9') /* 9 YUV 4:1:0 */
319#define <link linkend="V4L2-PIX-FMT-YUV420">V4L2_PIX_FMT_YUV420</link> v4l2_fourcc('Y', 'U', '1', '2') /* 12 YUV 4:2:0 */
320#define <link linkend="V4L2-PIX-FMT-HI240">V4L2_PIX_FMT_HI240</link> v4l2_fourcc('H', 'I', '2', '4') /* 8 8-bit color */
321#define <link linkend="V4L2-PIX-FMT-HM12">V4L2_PIX_FMT_HM12</link> v4l2_fourcc('H', 'M', '1', '2') /* 8 YUV 4:2:0 16x16 macroblocks */
322
323/* two planes -- one Y, one Cr + Cb interleaved */
324#define <link linkend="V4L2-PIX-FMT-NV12">V4L2_PIX_FMT_NV12</link> v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */
325#define <link linkend="V4L2-PIX-FMT-NV21">V4L2_PIX_FMT_NV21</link> v4l2_fourcc('N', 'V', '2', '1') /* 12 Y/CrCb 4:2:0 */
326#define <link linkend="V4L2-PIX-FMT-NV16">V4L2_PIX_FMT_NV16</link> v4l2_fourcc('N', 'V', '1', '6') /* 16 Y/CbCr 4:2:2 */
327#define <link linkend="V4L2-PIX-FMT-NV61">V4L2_PIX_FMT_NV61</link> v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */
328
329/* Bayer formats - see http://www.siliconimaging.com/RGB%20Bayer.htm */
330#define <link linkend="V4L2-PIX-FMT-SBGGR8">V4L2_PIX_FMT_SBGGR8</link> v4l2_fourcc('B', 'A', '8', '1') /* 8 BGBG.. GRGR.. */
331#define <link linkend="V4L2-PIX-FMT-SGBRG8">V4L2_PIX_FMT_SGBRG8</link> v4l2_fourcc('G', 'B', 'R', 'G') /* 8 GBGB.. RGRG.. */
332#define <link linkend="V4L2-PIX-FMT-SGRBG8">V4L2_PIX_FMT_SGRBG8</link> v4l2_fourcc('G', 'R', 'B', 'G') /* 8 GRGR.. BGBG.. */
333#define <link linkend="V4L2-PIX-FMT-SGRBG10">V4L2_PIX_FMT_SGRBG10</link> v4l2_fourcc('B', 'A', '1', '0') /* 10bit raw bayer */
334 /* 10bit raw bayer DPCM compressed to 8 bits */
335#define <link linkend="V4L2-PIX-FMT-SGRBG10DPCM8">V4L2_PIX_FMT_SGRBG10DPCM8</link> v4l2_fourcc('B', 'D', '1', '0')
336 /*
337 * 10bit raw bayer, expanded to 16 bits
338 * xxxxrrrrrrrrrrxxxxgggggggggg xxxxggggggggggxxxxbbbbbbbbbb...
339 */
340#define <link linkend="V4L2-PIX-FMT-SBGGR16">V4L2_PIX_FMT_SBGGR16</link> v4l2_fourcc('B', 'Y', 'R', '2') /* 16 BGBG.. GRGR.. */
341
342/* compressed formats */
343#define <link linkend="V4L2-PIX-FMT-MJPEG">V4L2_PIX_FMT_MJPEG</link> v4l2_fourcc('M', 'J', 'P', 'G') /* Motion-JPEG */
344#define <link linkend="V4L2-PIX-FMT-JPEG">V4L2_PIX_FMT_JPEG</link> v4l2_fourcc('J', 'P', 'E', 'G') /* JFIF JPEG */
345#define <link linkend="V4L2-PIX-FMT-DV">V4L2_PIX_FMT_DV</link> v4l2_fourcc('d', 'v', 's', 'd') /* 1394 */
346#define <link linkend="V4L2-PIX-FMT-MPEG">V4L2_PIX_FMT_MPEG</link> v4l2_fourcc('M', 'P', 'E', 'G') /* MPEG-1/2/4 */
347
348/* Vendor-specific formats */
349#define <link linkend="V4L2-PIX-FMT-WNVA">V4L2_PIX_FMT_WNVA</link> v4l2_fourcc('W', 'N', 'V', 'A') /* Winnov hw compress */
350#define <link linkend="V4L2-PIX-FMT-SN9C10X">V4L2_PIX_FMT_SN9C10X</link> v4l2_fourcc('S', '9', '1', '0') /* SN9C10x compression */
351#define <link linkend="V4L2-PIX-FMT-SN9C20X-I420">V4L2_PIX_FMT_SN9C20X_I420</link> v4l2_fourcc('S', '9', '2', '0') /* SN9C20x YUV 4:2:0 */
352#define <link linkend="V4L2-PIX-FMT-PWC1">V4L2_PIX_FMT_PWC1</link> v4l2_fourcc('P', 'W', 'C', '1') /* pwc older webcam */
353#define <link linkend="V4L2-PIX-FMT-PWC2">V4L2_PIX_FMT_PWC2</link> v4l2_fourcc('P', 'W', 'C', '2') /* pwc newer webcam */
354#define <link linkend="V4L2-PIX-FMT-ET61X251">V4L2_PIX_FMT_ET61X251</link> v4l2_fourcc('E', '6', '2', '5') /* ET61X251 compression */
355#define <link linkend="V4L2-PIX-FMT-SPCA501">V4L2_PIX_FMT_SPCA501</link> v4l2_fourcc('S', '5', '0', '1') /* YUYV per line */
356#define <link linkend="V4L2-PIX-FMT-SPCA505">V4L2_PIX_FMT_SPCA505</link> v4l2_fourcc('S', '5', '0', '5') /* YYUV per line */
357#define <link linkend="V4L2-PIX-FMT-SPCA508">V4L2_PIX_FMT_SPCA508</link> v4l2_fourcc('S', '5', '0', '8') /* YUVY per line */
358#define <link linkend="V4L2-PIX-FMT-SPCA561">V4L2_PIX_FMT_SPCA561</link> v4l2_fourcc('S', '5', '6', '1') /* compressed GBRG bayer */
359#define <link linkend="V4L2-PIX-FMT-PAC207">V4L2_PIX_FMT_PAC207</link> v4l2_fourcc('P', '2', '0', '7') /* compressed BGGR bayer */
360#define <link linkend="V4L2-PIX-FMT-MR97310A">V4L2_PIX_FMT_MR97310A</link> v4l2_fourcc('M', '3', '1', '0') /* compressed BGGR bayer */
361#define <link linkend="V4L2-PIX-FMT-SQ905C">V4L2_PIX_FMT_SQ905C</link> v4l2_fourcc('9', '0', '5', 'C') /* compressed RGGB bayer */
362#define <link linkend="V4L2-PIX-FMT-PJPG">V4L2_PIX_FMT_PJPG</link> v4l2_fourcc('P', 'J', 'P', 'G') /* Pixart 73xx JPEG */
363#define <link linkend="V4L2-PIX-FMT-OV511">V4L2_PIX_FMT_OV511</link> v4l2_fourcc('O', '5', '1', '1') /* ov511 JPEG */
364#define <link linkend="V4L2-PIX-FMT-OV518">V4L2_PIX_FMT_OV518</link> v4l2_fourcc('O', '5', '1', '8') /* ov518 JPEG */
365
366/*
367 * F O R M A T E N U M E R A T I O N
368 */
369struct <link linkend="v4l2-fmtdesc">v4l2_fmtdesc</link> {
370 __u32 index; /* Format number */
371 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type; /* buffer type */
372 __u32 flags;
373 __u8 description[32]; /* Description string */
374 __u32 pixelformat; /* Format fourcc */
375 __u32 reserved[4];
376};
377
378#define V4L2_FMT_FLAG_COMPRESSED 0x0001
379#define V4L2_FMT_FLAG_EMULATED 0x0002
380
381#if 1 /*KEEP*/
382 /* Experimental Frame Size and frame rate enumeration */
383/*
384 * F R A M E S I Z E E N U M E R A T I O N
385 */
386enum <link linkend="v4l2-frmsizetypes">v4l2_frmsizetypes</link> {
387 V4L2_FRMSIZE_TYPE_DISCRETE = 1,
388 V4L2_FRMSIZE_TYPE_CONTINUOUS = 2,
389 V4L2_FRMSIZE_TYPE_STEPWISE = 3,
390};
391
392struct <link linkend="v4l2-frmsize-discrete">v4l2_frmsize_discrete</link> {
393 __u32 width; /* Frame width [pixel] */
394 __u32 height; /* Frame height [pixel] */
395};
396
397struct <link linkend="v4l2-frmsize-stepwise">v4l2_frmsize_stepwise</link> {
398 __u32 min_width; /* Minimum frame width [pixel] */
399 __u32 max_width; /* Maximum frame width [pixel] */
400 __u32 step_width; /* Frame width step size [pixel] */
401 __u32 min_height; /* Minimum frame height [pixel] */
402 __u32 max_height; /* Maximum frame height [pixel] */
403 __u32 step_height; /* Frame height step size [pixel] */
404};
405
406struct <link linkend="v4l2-frmsizeenum">v4l2_frmsizeenum</link> {
407 __u32 index; /* Frame size number */
408 __u32 pixel_format; /* Pixel format */
409 __u32 type; /* Frame size type the device supports. */
410
411 union { /* Frame size */
412 struct <link linkend="v4l2-frmsize-discrete">v4l2_frmsize_discrete</link> discrete;
413 struct <link linkend="v4l2-frmsize-stepwise">v4l2_frmsize_stepwise</link> stepwise;
414 };
415
416 __u32 reserved[2]; /* Reserved space for future use */
417};
418
419/*
420 * F R A M E R A T E E N U M E R A T I O N
421 */
422enum <link linkend="v4l2-frmivaltypes">v4l2_frmivaltypes</link> {
423 V4L2_FRMIVAL_TYPE_DISCRETE = 1,
424 V4L2_FRMIVAL_TYPE_CONTINUOUS = 2,
425 V4L2_FRMIVAL_TYPE_STEPWISE = 3,
426};
427
428struct <link linkend="v4l2-frmival-stepwise">v4l2_frmival_stepwise</link> {
429 struct <link linkend="v4l2-fract">v4l2_fract</link> min; /* Minimum frame interval [s] */
430 struct <link linkend="v4l2-fract">v4l2_fract</link> max; /* Maximum frame interval [s] */
431 struct <link linkend="v4l2-fract">v4l2_fract</link> step; /* Frame interval step size [s] */
432};
433
434struct <link linkend="v4l2-frmivalenum">v4l2_frmivalenum</link> {
435 __u32 index; /* Frame format index */
436 __u32 pixel_format; /* Pixel format */
437 __u32 width; /* Frame width */
438 __u32 height; /* Frame height */
439 __u32 type; /* Frame interval type the device supports. */
440
441 union { /* Frame interval */
442 struct <link linkend="v4l2-fract">v4l2_fract</link> discrete;
443 struct <link linkend="v4l2-frmival-stepwise">v4l2_frmival_stepwise</link> stepwise;
444 };
445
446 __u32 reserved[2]; /* Reserved space for future use */
447};
448#endif
449
450/*
451 * T I M E C O D E
452 */
453struct <link linkend="v4l2-timecode">v4l2_timecode</link> {
454 __u32 type;
455 __u32 flags;
456 __u8 frames;
457 __u8 seconds;
458 __u8 minutes;
459 __u8 hours;
460 __u8 userbits[4];
461};
462
463/* Type */
464#define V4L2_TC_TYPE_24FPS 1
465#define V4L2_TC_TYPE_25FPS 2
466#define V4L2_TC_TYPE_30FPS 3
467#define V4L2_TC_TYPE_50FPS 4
468#define V4L2_TC_TYPE_60FPS 5
469
470/* Flags */
471#define V4L2_TC_FLAG_DROPFRAME 0x0001 /* "drop-frame" mode */
472#define V4L2_TC_FLAG_COLORFRAME 0x0002
473#define V4L2_TC_USERBITS_field 0x000C
474#define V4L2_TC_USERBITS_USERDEFINED 0x0000
475#define V4L2_TC_USERBITS_8BITCHARS 0x0008
476/* The above is based on SMPTE timecodes */
477
478struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link> {
479 int quality;
480
481 int APPn; /* Number of APP segment to be written,
482 * must be 0..15 */
483 int APP_len; /* Length of data in JPEG APPn segment */
484 char APP_data[60]; /* Data in the JPEG APPn segment. */
485
486 int COM_len; /* Length of data in JPEG COM segment */
487 char COM_data[60]; /* Data in JPEG COM segment */
488
489 __u32 jpeg_markers; /* Which markers should go into the JPEG
490 * output. Unless you exactly know what
491 * you do, leave them untouched.
492 * Inluding less markers will make the
493 * resulting code smaller, but there will
494 * be fewer aplications which can read it.
495 * The presence of the APP and COM marker
496 * is influenced by APP_len and COM_len
497 * ONLY, not by this property! */
498
499#define V4L2_JPEG_MARKER_DHT (1&lt;&lt;3) /* Define Huffman Tables */
500#define V4L2_JPEG_MARKER_DQT (1&lt;&lt;4) /* Define Quantization Tables */
501#define V4L2_JPEG_MARKER_DRI (1&lt;&lt;5) /* Define Restart Interval */
502#define V4L2_JPEG_MARKER_COM (1&lt;&lt;6) /* Comment segment */
503#define V4L2_JPEG_MARKER_APP (1&lt;&lt;7) /* App segment, driver will
504 * allways use APP0 */
505};
506
507/*
508 * M E M O R Y - M A P P I N G B U F F E R S
509 */
510struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link> {
511 __u32 count;
512 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
513 enum <link linkend="v4l2-memory">v4l2_memory</link> memory;
514 __u32 reserved[2];
515};
516
517struct <link linkend="v4l2-buffer">v4l2_buffer</link> {
518 __u32 index;
519 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
520 __u32 bytesused;
521 __u32 flags;
522 enum <link linkend="v4l2-field">v4l2_field</link> field;
523 struct timeval timestamp;
524 struct <link linkend="v4l2-timecode">v4l2_timecode</link> timecode;
525 __u32 sequence;
526
527 /* memory location */
528 enum <link linkend="v4l2-memory">v4l2_memory</link> memory;
529 union {
530 __u32 offset;
531 unsigned long userptr;
532 } m;
533 __u32 length;
534 __u32 input;
535 __u32 reserved;
536};
537
538/* Flags for 'flags' field */
539#define V4L2_BUF_FLAG_MAPPED 0x0001 /* Buffer is mapped (flag) */
540#define V4L2_BUF_FLAG_QUEUED 0x0002 /* Buffer is queued for processing */
541#define V4L2_BUF_FLAG_DONE 0x0004 /* Buffer is ready */
542#define V4L2_BUF_FLAG_KEYFRAME 0x0008 /* Image is a keyframe (I-frame) */
543#define V4L2_BUF_FLAG_PFRAME 0x0010 /* Image is a P-frame */
544#define V4L2_BUF_FLAG_BFRAME 0x0020 /* Image is a B-frame */
545#define V4L2_BUF_FLAG_TIMECODE 0x0100 /* timecode field is valid */
546#define V4L2_BUF_FLAG_INPUT 0x0200 /* input field is valid */
547
548/*
549 * O V E R L A Y P R E V I E W
550 */
551struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link> {
552 __u32 capability;
553 __u32 flags;
554/* FIXME: in theory we should pass something like PCI device + memory
555 * region + offset instead of some physical address */
556 void *base;
557 struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> fmt;
558};
559/* Flags for the 'capability' field. Read only */
560#define V4L2_FBUF_CAP_EXTERNOVERLAY 0x0001
561#define V4L2_FBUF_CAP_CHROMAKEY 0x0002
562#define V4L2_FBUF_CAP_LIST_CLIPPING 0x0004
563#define V4L2_FBUF_CAP_BITMAP_CLIPPING 0x0008
564#define V4L2_FBUF_CAP_LOCAL_ALPHA 0x0010
565#define V4L2_FBUF_CAP_GLOBAL_ALPHA 0x0020
566#define V4L2_FBUF_CAP_LOCAL_INV_ALPHA 0x0040
567/* Flags for the 'flags' field. */
568#define V4L2_FBUF_FLAG_PRIMARY 0x0001
569#define V4L2_FBUF_FLAG_OVERLAY 0x0002
570#define V4L2_FBUF_FLAG_CHROMAKEY 0x0004
571#define V4L2_FBUF_FLAG_LOCAL_ALPHA 0x0008
572#define V4L2_FBUF_FLAG_GLOBAL_ALPHA 0x0010
573#define V4L2_FBUF_FLAG_LOCAL_INV_ALPHA 0x0020
574
575struct <link linkend="v4l2-clip">v4l2_clip</link> {
576 struct <link linkend="v4l2-rect">v4l2_rect</link> c;
577 struct <link linkend="v4l2-clip">v4l2_clip</link> __user *next;
578};
579
580struct <link linkend="v4l2-window">v4l2_window</link> {
581 struct <link linkend="v4l2-rect">v4l2_rect</link> w;
582 enum <link linkend="v4l2-field">v4l2_field</link> field;
583 __u32 chromakey;
584 struct <link linkend="v4l2-clip">v4l2_clip</link> __user *clips;
585 __u32 clipcount;
586 void __user *bitmap;
587 __u8 global_alpha;
588};
589
590/*
591 * C A P T U R E P A R A M E T E R S
592 */
593struct <link linkend="v4l2-captureparm">v4l2_captureparm</link> {
594 __u32 capability; /* Supported modes */
595 __u32 capturemode; /* Current mode */
596 struct <link linkend="v4l2-fract">v4l2_fract</link> timeperframe; /* Time per frame in .1us units */
597 __u32 extendedmode; /* Driver-specific extensions */
598 __u32 readbuffers; /* # of buffers for read */
599 __u32 reserved[4];
600};
601
602/* Flags for 'capability' and 'capturemode' fields */
603#define V4L2_MODE_HIGHQUALITY 0x0001 /* High quality imaging mode */
604#define V4L2_CAP_TIMEPERFRAME 0x1000 /* timeperframe field is supported */
605
606struct <link linkend="v4l2-outputparm">v4l2_outputparm</link> {
607 __u32 capability; /* Supported modes */
608 __u32 outputmode; /* Current mode */
609 struct <link linkend="v4l2-fract">v4l2_fract</link> timeperframe; /* Time per frame in seconds */
610 __u32 extendedmode; /* Driver-specific extensions */
611 __u32 writebuffers; /* # of buffers for write */
612 __u32 reserved[4];
613};
614
615/*
616 * I N P U T I M A G E C R O P P I N G
617 */
618struct <link linkend="v4l2-cropcap">v4l2_cropcap</link> {
619 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
620 struct <link linkend="v4l2-rect">v4l2_rect</link> bounds;
621 struct <link linkend="v4l2-rect">v4l2_rect</link> defrect;
622 struct <link linkend="v4l2-fract">v4l2_fract</link> pixelaspect;
623};
624
625struct <link linkend="v4l2-crop">v4l2_crop</link> {
626 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
627 struct <link linkend="v4l2-rect">v4l2_rect</link> c;
628};
629
630/*
631 * A N A L O G V I D E O S T A N D A R D
632 */
633
634typedef __u64 v4l2_std_id;
635
636/* one bit for each */
637#define V4L2_STD_PAL_B ((v4l2_std_id)0x00000001)
638#define V4L2_STD_PAL_B1 ((v4l2_std_id)0x00000002)
639#define V4L2_STD_PAL_G ((v4l2_std_id)0x00000004)
640#define V4L2_STD_PAL_H ((v4l2_std_id)0x00000008)
641#define V4L2_STD_PAL_I ((v4l2_std_id)0x00000010)
642#define V4L2_STD_PAL_D ((v4l2_std_id)0x00000020)
643#define V4L2_STD_PAL_D1 ((v4l2_std_id)0x00000040)
644#define V4L2_STD_PAL_K ((v4l2_std_id)0x00000080)
645
646#define V4L2_STD_PAL_M ((v4l2_std_id)0x00000100)
647#define V4L2_STD_PAL_N ((v4l2_std_id)0x00000200)
648#define V4L2_STD_PAL_Nc ((v4l2_std_id)0x00000400)
649#define V4L2_STD_PAL_60 ((v4l2_std_id)0x00000800)
650
651#define V4L2_STD_NTSC_M ((v4l2_std_id)0x00001000)
652#define V4L2_STD_NTSC_M_JP ((v4l2_std_id)0x00002000)
653#define V4L2_STD_NTSC_443 ((v4l2_std_id)0x00004000)
654#define V4L2_STD_NTSC_M_KR ((v4l2_std_id)0x00008000)
655
656#define V4L2_STD_SECAM_B ((v4l2_std_id)0x00010000)
657#define V4L2_STD_SECAM_D ((v4l2_std_id)0x00020000)
658#define V4L2_STD_SECAM_G ((v4l2_std_id)0x00040000)
659#define V4L2_STD_SECAM_H ((v4l2_std_id)0x00080000)
660#define V4L2_STD_SECAM_K ((v4l2_std_id)0x00100000)
661#define V4L2_STD_SECAM_K1 ((v4l2_std_id)0x00200000)
662#define V4L2_STD_SECAM_L ((v4l2_std_id)0x00400000)
663#define V4L2_STD_SECAM_LC ((v4l2_std_id)0x00800000)
664
665/* ATSC/HDTV */
666#define V4L2_STD_ATSC_8_VSB ((v4l2_std_id)0x01000000)
667#define V4L2_STD_ATSC_16_VSB ((v4l2_std_id)0x02000000)
668
669/* FIXME:
670 Although std_id is 64 bits, there is an issue on PPC32 architecture that
671 makes switch(__u64) to break. So, there's a hack on v4l2-common.c rounding
672 this value to 32 bits.
673 As, currently, the max value is for V4L2_STD_ATSC_16_VSB (30 bits wide),
674 it should work fine. However, if needed to add more than two standards,
675 v4l2-common.c should be fixed.
676 */
677
678/* some merged standards */
679#define V4L2_STD_MN (V4L2_STD_PAL_M|V4L2_STD_PAL_N|V4L2_STD_PAL_Nc|V4L2_STD_NTSC)
680#define V4L2_STD_B (V4L2_STD_PAL_B|V4L2_STD_PAL_B1|V4L2_STD_SECAM_B)
681#define V4L2_STD_GH (V4L2_STD_PAL_G|V4L2_STD_PAL_H|V4L2_STD_SECAM_G|V4L2_STD_SECAM_H)
682#define V4L2_STD_DK (V4L2_STD_PAL_DK|V4L2_STD_SECAM_DK)
683
684/* some common needed stuff */
685#define V4L2_STD_PAL_BG (V4L2_STD_PAL_B |\
686 V4L2_STD_PAL_B1 |\
687 V4L2_STD_PAL_G)
688#define V4L2_STD_PAL_DK (V4L2_STD_PAL_D |\
689 V4L2_STD_PAL_D1 |\
690 V4L2_STD_PAL_K)
691#define V4L2_STD_PAL (V4L2_STD_PAL_BG |\
692 V4L2_STD_PAL_DK |\
693 V4L2_STD_PAL_H |\
694 V4L2_STD_PAL_I)
695#define V4L2_STD_NTSC (V4L2_STD_NTSC_M |\
696 V4L2_STD_NTSC_M_JP |\
697 V4L2_STD_NTSC_M_KR)
698#define V4L2_STD_SECAM_DK (V4L2_STD_SECAM_D |\
699 V4L2_STD_SECAM_K |\
700 V4L2_STD_SECAM_K1)
701#define V4L2_STD_SECAM (V4L2_STD_SECAM_B |\
702 V4L2_STD_SECAM_G |\
703 V4L2_STD_SECAM_H |\
704 V4L2_STD_SECAM_DK |\
705 V4L2_STD_SECAM_L |\
706 V4L2_STD_SECAM_LC)
707
708#define V4L2_STD_525_60 (V4L2_STD_PAL_M |\
709 V4L2_STD_PAL_60 |\
710 V4L2_STD_NTSC |\
711 V4L2_STD_NTSC_443)
712#define V4L2_STD_625_50 (V4L2_STD_PAL |\
713 V4L2_STD_PAL_N |\
714 V4L2_STD_PAL_Nc |\
715 V4L2_STD_SECAM)
716#define V4L2_STD_ATSC (V4L2_STD_ATSC_8_VSB |\
717 V4L2_STD_ATSC_16_VSB)
718
719#define V4L2_STD_UNKNOWN 0
720#define V4L2_STD_ALL (V4L2_STD_525_60 |\
721 V4L2_STD_625_50)
722
723struct <link linkend="v4l2-standard">v4l2_standard</link> {
724 __u32 index;
725 v4l2_std_id id;
726 __u8 name[24];
727 struct <link linkend="v4l2-fract">v4l2_fract</link> frameperiod; /* Frames, not fields */
728 __u32 framelines;
729 __u32 reserved[4];
730};
731
732/*
733 * V I D E O I N P U T S
734 */
735struct <link linkend="v4l2-input">v4l2_input</link> {
736 __u32 index; /* Which input */
737 __u8 name[32]; /* Label */
738 __u32 type; /* Type of input */
739 __u32 audioset; /* Associated audios (bitfield) */
740 __u32 tuner; /* Associated tuner */
741 v4l2_std_id std;
742 __u32 status;
743 __u32 reserved[4];
744};
745
746/* Values for the 'type' field */
747#define V4L2_INPUT_TYPE_TUNER 1
748#define V4L2_INPUT_TYPE_CAMERA 2
749
750/* field 'status' - general */
751#define V4L2_IN_ST_NO_POWER 0x00000001 /* Attached device is off */
752#define V4L2_IN_ST_NO_SIGNAL 0x00000002
753#define V4L2_IN_ST_NO_COLOR 0x00000004
754
755/* field 'status' - sensor orientation */
756/* If sensor is mounted upside down set both bits */
757#define V4L2_IN_ST_HFLIP 0x00000010 /* Frames are flipped horizontally */
758#define V4L2_IN_ST_VFLIP 0x00000020 /* Frames are flipped vertically */
759
760/* field 'status' - analog */
761#define V4L2_IN_ST_NO_H_LOCK 0x00000100 /* No horizontal sync lock */
762#define V4L2_IN_ST_COLOR_KILL 0x00000200 /* Color killer is active */
763
764/* field 'status' - digital */
765#define V4L2_IN_ST_NO_SYNC 0x00010000 /* No synchronization lock */
766#define V4L2_IN_ST_NO_EQU 0x00020000 /* No equalizer lock */
767#define V4L2_IN_ST_NO_CARRIER 0x00040000 /* Carrier recovery failed */
768
769/* field 'status' - VCR and set-top box */
770#define V4L2_IN_ST_MACROVISION 0x01000000 /* Macrovision detected */
771#define V4L2_IN_ST_NO_ACCESS 0x02000000 /* Conditional access denied */
772#define V4L2_IN_ST_VTR 0x04000000 /* VTR time constant */
773
774/*
775 * V I D E O O U T P U T S
776 */
777struct <link linkend="v4l2-output">v4l2_output</link> {
778 __u32 index; /* Which output */
779 __u8 name[32]; /* Label */
780 __u32 type; /* Type of output */
781 __u32 audioset; /* Associated audios (bitfield) */
782 __u32 modulator; /* Associated modulator */
783 v4l2_std_id std;
784 __u32 reserved[4];
785};
786/* Values for the 'type' field */
787#define V4L2_OUTPUT_TYPE_MODULATOR 1
788#define V4L2_OUTPUT_TYPE_ANALOG 2
789#define V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY 3
790
791/*
792 * C O N T R O L S
793 */
794struct <link linkend="v4l2-control">v4l2_control</link> {
795 __u32 id;
796 __s32 value;
797};
798
799struct <link linkend="v4l2-ext-control">v4l2_ext_control</link> {
800 __u32 id;
801 __u32 size;
802 __u32 reserved2[1];
803 union {
804 __s32 value;
805 __s64 value64;
806 char *string;
807 };
808} __attribute__ ((packed));
809
810struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link> {
811 __u32 ctrl_class;
812 __u32 count;
813 __u32 error_idx;
814 __u32 reserved[2];
815 struct <link linkend="v4l2-ext-control">v4l2_ext_control</link> *controls;
816};
817
818/* Values for ctrl_class field */
819#define V4L2_CTRL_CLASS_USER 0x00980000 /* Old-style 'user' controls */
820#define V4L2_CTRL_CLASS_MPEG 0x00990000 /* MPEG-compression controls */
821#define V4L2_CTRL_CLASS_CAMERA 0x009a0000 /* Camera class controls */
822#define V4L2_CTRL_CLASS_FM_TX 0x009b0000 /* FM Modulator control class */
823
824#define V4L2_CTRL_ID_MASK (0x0fffffff)
825#define V4L2_CTRL_ID2CLASS(id) ((id) &amp; 0x0fff0000UL)
826#define V4L2_CTRL_DRIVER_PRIV(id) (((id) &amp; 0xffff) &gt;= 0x1000)
827
828/* Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
829struct <link linkend="v4l2-queryctrl">v4l2_queryctrl</link> {
830 __u32 id;
831 enum <link linkend="v4l2-ctrl-type">v4l2_ctrl_type</link> type;
832 __u8 name[32]; /* Whatever */
833 __s32 minimum; /* Note signedness */
834 __s32 maximum;
835 __s32 step;
836 __s32 default_value;
837 __u32 flags;
838 __u32 reserved[2];
839};
840
841/* Used in the VIDIOC_QUERYMENU ioctl for querying menu items */
842struct <link linkend="v4l2-querymenu">v4l2_querymenu</link> {
843 __u32 id;
844 __u32 index;
845 __u8 name[32]; /* Whatever */
846 __u32 reserved;
847};
848
849/* Control flags */
850#define V4L2_CTRL_FLAG_DISABLED 0x0001
851#define V4L2_CTRL_FLAG_GRABBED 0x0002
852#define V4L2_CTRL_FLAG_READ_ONLY 0x0004
853#define V4L2_CTRL_FLAG_UPDATE 0x0008
854#define V4L2_CTRL_FLAG_INACTIVE 0x0010
855#define V4L2_CTRL_FLAG_SLIDER 0x0020
856#define V4L2_CTRL_FLAG_WRITE_ONLY 0x0040
857
858/* Query flag, to be ORed with the control ID */
859#define V4L2_CTRL_FLAG_NEXT_CTRL 0x80000000
860
861/* User-class control IDs defined by V4L2 */
862#define V4L2_CID_BASE (V4L2_CTRL_CLASS_USER | 0x900)
863#define V4L2_CID_USER_BASE V4L2_CID_BASE
864/* IDs reserved for driver specific controls */
865#define V4L2_CID_PRIVATE_BASE 0x08000000
866
867#define V4L2_CID_USER_CLASS (V4L2_CTRL_CLASS_USER | 1)
868#define V4L2_CID_BRIGHTNESS (V4L2_CID_BASE+0)
869#define V4L2_CID_CONTRAST (V4L2_CID_BASE+1)
870#define V4L2_CID_SATURATION (V4L2_CID_BASE+2)
871#define V4L2_CID_HUE (V4L2_CID_BASE+3)
872#define V4L2_CID_AUDIO_VOLUME (V4L2_CID_BASE+5)
873#define V4L2_CID_AUDIO_BALANCE (V4L2_CID_BASE+6)
874#define V4L2_CID_AUDIO_BASS (V4L2_CID_BASE+7)
875#define V4L2_CID_AUDIO_TREBLE (V4L2_CID_BASE+8)
876#define V4L2_CID_AUDIO_MUTE (V4L2_CID_BASE+9)
877#define V4L2_CID_AUDIO_LOUDNESS (V4L2_CID_BASE+10)
878#define V4L2_CID_BLACK_LEVEL (V4L2_CID_BASE+11) /* Deprecated */
879#define V4L2_CID_AUTO_WHITE_BALANCE (V4L2_CID_BASE+12)
880#define V4L2_CID_DO_WHITE_BALANCE (V4L2_CID_BASE+13)
881#define V4L2_CID_RED_BALANCE (V4L2_CID_BASE+14)
882#define V4L2_CID_BLUE_BALANCE (V4L2_CID_BASE+15)
883#define V4L2_CID_GAMMA (V4L2_CID_BASE+16)
884#define V4L2_CID_WHITENESS (V4L2_CID_GAMMA) /* Deprecated */
885#define V4L2_CID_EXPOSURE (V4L2_CID_BASE+17)
886#define V4L2_CID_AUTOGAIN (V4L2_CID_BASE+18)
887#define V4L2_CID_GAIN (V4L2_CID_BASE+19)
888#define V4L2_CID_HFLIP (V4L2_CID_BASE+20)
889#define V4L2_CID_VFLIP (V4L2_CID_BASE+21)
890
891/* Deprecated; use V4L2_CID_PAN_RESET and V4L2_CID_TILT_RESET */
892#define V4L2_CID_HCENTER (V4L2_CID_BASE+22)
893#define V4L2_CID_VCENTER (V4L2_CID_BASE+23)
894
895#define V4L2_CID_POWER_LINE_FREQUENCY (V4L2_CID_BASE+24)
896enum <link linkend="v4l2-power-line-frequency">v4l2_power_line_frequency</link> {
897 V4L2_CID_POWER_LINE_FREQUENCY_DISABLED = 0,
898 V4L2_CID_POWER_LINE_FREQUENCY_50HZ = 1,
899 V4L2_CID_POWER_LINE_FREQUENCY_60HZ = 2,
900};
901#define V4L2_CID_HUE_AUTO (V4L2_CID_BASE+25)
902#define V4L2_CID_WHITE_BALANCE_TEMPERATURE (V4L2_CID_BASE+26)
903#define V4L2_CID_SHARPNESS (V4L2_CID_BASE+27)
904#define V4L2_CID_BACKLIGHT_COMPENSATION (V4L2_CID_BASE+28)
905#define V4L2_CID_CHROMA_AGC (V4L2_CID_BASE+29)
906#define V4L2_CID_COLOR_KILLER (V4L2_CID_BASE+30)
907#define V4L2_CID_COLORFX (V4L2_CID_BASE+31)
908enum <link linkend="v4l2-colorfx">v4l2_colorfx</link> {
909 V4L2_COLORFX_NONE = 0,
910 V4L2_COLORFX_BW = 1,
911 V4L2_COLORFX_SEPIA = 2,
912};
913#define V4L2_CID_AUTOBRIGHTNESS (V4L2_CID_BASE+32)
914#define V4L2_CID_BAND_STOP_FILTER (V4L2_CID_BASE+33)
915
916/* last CID + 1 */
917#define V4L2_CID_LASTP1 (V4L2_CID_BASE+34)
918
919/* MPEG-class control IDs defined by V4L2 */
920#define V4L2_CID_MPEG_BASE (V4L2_CTRL_CLASS_MPEG | 0x900)
921#define V4L2_CID_MPEG_CLASS (V4L2_CTRL_CLASS_MPEG | 1)
922
923/* MPEG streams */
924#define V4L2_CID_MPEG_STREAM_TYPE (V4L2_CID_MPEG_BASE+0)
925enum <link linkend="v4l2-mpeg-stream-type">v4l2_mpeg_stream_type</link> {
926 V4L2_MPEG_STREAM_TYPE_MPEG2_PS = 0, /* MPEG-2 program stream */
927 V4L2_MPEG_STREAM_TYPE_MPEG2_TS = 1, /* MPEG-2 transport stream */
928 V4L2_MPEG_STREAM_TYPE_MPEG1_SS = 2, /* MPEG-1 system stream */
929 V4L2_MPEG_STREAM_TYPE_MPEG2_DVD = 3, /* MPEG-2 DVD-compatible stream */
930 V4L2_MPEG_STREAM_TYPE_MPEG1_VCD = 4, /* MPEG-1 VCD-compatible stream */
931 V4L2_MPEG_STREAM_TYPE_MPEG2_SVCD = 5, /* MPEG-2 SVCD-compatible stream */
932};
933#define V4L2_CID_MPEG_STREAM_PID_PMT (V4L2_CID_MPEG_BASE+1)
934#define V4L2_CID_MPEG_STREAM_PID_AUDIO (V4L2_CID_MPEG_BASE+2)
935#define V4L2_CID_MPEG_STREAM_PID_VIDEO (V4L2_CID_MPEG_BASE+3)
936#define V4L2_CID_MPEG_STREAM_PID_PCR (V4L2_CID_MPEG_BASE+4)
937#define V4L2_CID_MPEG_STREAM_PES_ID_AUDIO (V4L2_CID_MPEG_BASE+5)
938#define V4L2_CID_MPEG_STREAM_PES_ID_VIDEO (V4L2_CID_MPEG_BASE+6)
939#define V4L2_CID_MPEG_STREAM_VBI_FMT (V4L2_CID_MPEG_BASE+7)
940enum <link linkend="v4l2-mpeg-stream-vbi-fmt">v4l2_mpeg_stream_vbi_fmt</link> {
941 V4L2_MPEG_STREAM_VBI_FMT_NONE = 0, /* No VBI in the MPEG stream */
942 V4L2_MPEG_STREAM_VBI_FMT_IVTV = 1, /* VBI in private packets, IVTV format */
943};
944
945/* MPEG audio */
946#define V4L2_CID_MPEG_AUDIO_SAMPLING_FREQ (V4L2_CID_MPEG_BASE+100)
947enum <link linkend="v4l2-mpeg-audio-sampling-freq">v4l2_mpeg_audio_sampling_freq</link> {
948 V4L2_MPEG_AUDIO_SAMPLING_FREQ_44100 = 0,
949 V4L2_MPEG_AUDIO_SAMPLING_FREQ_48000 = 1,
950 V4L2_MPEG_AUDIO_SAMPLING_FREQ_32000 = 2,
951};
952#define V4L2_CID_MPEG_AUDIO_ENCODING (V4L2_CID_MPEG_BASE+101)
953enum <link linkend="v4l2-mpeg-audio-encoding">v4l2_mpeg_audio_encoding</link> {
954 V4L2_MPEG_AUDIO_ENCODING_LAYER_1 = 0,
955 V4L2_MPEG_AUDIO_ENCODING_LAYER_2 = 1,
956 V4L2_MPEG_AUDIO_ENCODING_LAYER_3 = 2,
957 V4L2_MPEG_AUDIO_ENCODING_AAC = 3,
958 V4L2_MPEG_AUDIO_ENCODING_AC3 = 4,
959};
960#define V4L2_CID_MPEG_AUDIO_L1_BITRATE (V4L2_CID_MPEG_BASE+102)
961enum <link linkend="v4l2-mpeg-audio-l1-bitrate">v4l2_mpeg_audio_l1_bitrate</link> {
962 V4L2_MPEG_AUDIO_L1_BITRATE_32K = 0,
963 V4L2_MPEG_AUDIO_L1_BITRATE_64K = 1,
964 V4L2_MPEG_AUDIO_L1_BITRATE_96K = 2,
965 V4L2_MPEG_AUDIO_L1_BITRATE_128K = 3,
966 V4L2_MPEG_AUDIO_L1_BITRATE_160K = 4,
967 V4L2_MPEG_AUDIO_L1_BITRATE_192K = 5,
968 V4L2_MPEG_AUDIO_L1_BITRATE_224K = 6,
969 V4L2_MPEG_AUDIO_L1_BITRATE_256K = 7,
970 V4L2_MPEG_AUDIO_L1_BITRATE_288K = 8,
971 V4L2_MPEG_AUDIO_L1_BITRATE_320K = 9,
972 V4L2_MPEG_AUDIO_L1_BITRATE_352K = 10,
973 V4L2_MPEG_AUDIO_L1_BITRATE_384K = 11,
974 V4L2_MPEG_AUDIO_L1_BITRATE_416K = 12,
975 V4L2_MPEG_AUDIO_L1_BITRATE_448K = 13,
976};
977#define V4L2_CID_MPEG_AUDIO_L2_BITRATE (V4L2_CID_MPEG_BASE+103)
978enum <link linkend="v4l2-mpeg-audio-l2-bitrate">v4l2_mpeg_audio_l2_bitrate</link> {
979 V4L2_MPEG_AUDIO_L2_BITRATE_32K = 0,
980 V4L2_MPEG_AUDIO_L2_BITRATE_48K = 1,
981 V4L2_MPEG_AUDIO_L2_BITRATE_56K = 2,
982 V4L2_MPEG_AUDIO_L2_BITRATE_64K = 3,
983 V4L2_MPEG_AUDIO_L2_BITRATE_80K = 4,
984 V4L2_MPEG_AUDIO_L2_BITRATE_96K = 5,
985 V4L2_MPEG_AUDIO_L2_BITRATE_112K = 6,
986 V4L2_MPEG_AUDIO_L2_BITRATE_128K = 7,
987 V4L2_MPEG_AUDIO_L2_BITRATE_160K = 8,
988 V4L2_MPEG_AUDIO_L2_BITRATE_192K = 9,
989 V4L2_MPEG_AUDIO_L2_BITRATE_224K = 10,
990 V4L2_MPEG_AUDIO_L2_BITRATE_256K = 11,
991 V4L2_MPEG_AUDIO_L2_BITRATE_320K = 12,
992 V4L2_MPEG_AUDIO_L2_BITRATE_384K = 13,
993};
994#define V4L2_CID_MPEG_AUDIO_L3_BITRATE (V4L2_CID_MPEG_BASE+104)
995enum <link linkend="v4l2-mpeg-audio-l3-bitrate">v4l2_mpeg_audio_l3_bitrate</link> {
996 V4L2_MPEG_AUDIO_L3_BITRATE_32K = 0,
997 V4L2_MPEG_AUDIO_L3_BITRATE_40K = 1,
998 V4L2_MPEG_AUDIO_L3_BITRATE_48K = 2,
999 V4L2_MPEG_AUDIO_L3_BITRATE_56K = 3,
1000 V4L2_MPEG_AUDIO_L3_BITRATE_64K = 4,
1001 V4L2_MPEG_AUDIO_L3_BITRATE_80K = 5,
1002 V4L2_MPEG_AUDIO_L3_BITRATE_96K = 6,
1003 V4L2_MPEG_AUDIO_L3_BITRATE_112K = 7,
1004 V4L2_MPEG_AUDIO_L3_BITRATE_128K = 8,
1005 V4L2_MPEG_AUDIO_L3_BITRATE_160K = 9,
1006 V4L2_MPEG_AUDIO_L3_BITRATE_192K = 10,
1007 V4L2_MPEG_AUDIO_L3_BITRATE_224K = 11,
1008 V4L2_MPEG_AUDIO_L3_BITRATE_256K = 12,
1009 V4L2_MPEG_AUDIO_L3_BITRATE_320K = 13,
1010};
1011#define V4L2_CID_MPEG_AUDIO_MODE (V4L2_CID_MPEG_BASE+105)
1012enum <link linkend="v4l2-mpeg-audio-mode">v4l2_mpeg_audio_mode</link> {
1013 V4L2_MPEG_AUDIO_MODE_STEREO = 0,
1014 V4L2_MPEG_AUDIO_MODE_JOINT_STEREO = 1,
1015 V4L2_MPEG_AUDIO_MODE_DUAL = 2,
1016 V4L2_MPEG_AUDIO_MODE_MONO = 3,
1017};
1018#define V4L2_CID_MPEG_AUDIO_MODE_EXTENSION (V4L2_CID_MPEG_BASE+106)
1019enum <link linkend="v4l2-mpeg-audio-mode-extension">v4l2_mpeg_audio_mode_extension</link> {
1020 V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_4 = 0,
1021 V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_8 = 1,
1022 V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_12 = 2,
1023 V4L2_MPEG_AUDIO_MODE_EXTENSION_BOUND_16 = 3,
1024};
1025#define V4L2_CID_MPEG_AUDIO_EMPHASIS (V4L2_CID_MPEG_BASE+107)
1026enum <link linkend="v4l2-mpeg-audio-emphasis">v4l2_mpeg_audio_emphasis</link> {
1027 V4L2_MPEG_AUDIO_EMPHASIS_NONE = 0,
1028 V4L2_MPEG_AUDIO_EMPHASIS_50_DIV_15_uS = 1,
1029 V4L2_MPEG_AUDIO_EMPHASIS_CCITT_J17 = 2,
1030};
1031#define V4L2_CID_MPEG_AUDIO_CRC (V4L2_CID_MPEG_BASE+108)
1032enum <link linkend="v4l2-mpeg-audio-crc">v4l2_mpeg_audio_crc</link> {
1033 V4L2_MPEG_AUDIO_CRC_NONE = 0,
1034 V4L2_MPEG_AUDIO_CRC_CRC16 = 1,
1035};
1036#define V4L2_CID_MPEG_AUDIO_MUTE (V4L2_CID_MPEG_BASE+109)
1037#define V4L2_CID_MPEG_AUDIO_AAC_BITRATE (V4L2_CID_MPEG_BASE+110)
1038#define V4L2_CID_MPEG_AUDIO_AC3_BITRATE (V4L2_CID_MPEG_BASE+111)
1039enum <link linkend="v4l2-mpeg-audio-ac3-bitrate">v4l2_mpeg_audio_ac3_bitrate</link> {
1040 V4L2_MPEG_AUDIO_AC3_BITRATE_32K = 0,
1041 V4L2_MPEG_AUDIO_AC3_BITRATE_40K = 1,
1042 V4L2_MPEG_AUDIO_AC3_BITRATE_48K = 2,
1043 V4L2_MPEG_AUDIO_AC3_BITRATE_56K = 3,
1044 V4L2_MPEG_AUDIO_AC3_BITRATE_64K = 4,
1045 V4L2_MPEG_AUDIO_AC3_BITRATE_80K = 5,
1046 V4L2_MPEG_AUDIO_AC3_BITRATE_96K = 6,
1047 V4L2_MPEG_AUDIO_AC3_BITRATE_112K = 7,
1048 V4L2_MPEG_AUDIO_AC3_BITRATE_128K = 8,
1049 V4L2_MPEG_AUDIO_AC3_BITRATE_160K = 9,
1050 V4L2_MPEG_AUDIO_AC3_BITRATE_192K = 10,
1051 V4L2_MPEG_AUDIO_AC3_BITRATE_224K = 11,
1052 V4L2_MPEG_AUDIO_AC3_BITRATE_256K = 12,
1053 V4L2_MPEG_AUDIO_AC3_BITRATE_320K = 13,
1054 V4L2_MPEG_AUDIO_AC3_BITRATE_384K = 14,
1055 V4L2_MPEG_AUDIO_AC3_BITRATE_448K = 15,
1056 V4L2_MPEG_AUDIO_AC3_BITRATE_512K = 16,
1057 V4L2_MPEG_AUDIO_AC3_BITRATE_576K = 17,
1058 V4L2_MPEG_AUDIO_AC3_BITRATE_640K = 18,
1059};
1060
1061/* MPEG video */
1062#define V4L2_CID_MPEG_VIDEO_ENCODING (V4L2_CID_MPEG_BASE+200)
1063enum <link linkend="v4l2-mpeg-video-encoding">v4l2_mpeg_video_encoding</link> {
1064 V4L2_MPEG_VIDEO_ENCODING_MPEG_1 = 0,
1065 V4L2_MPEG_VIDEO_ENCODING_MPEG_2 = 1,
1066 V4L2_MPEG_VIDEO_ENCODING_MPEG_4_AVC = 2,
1067};
1068#define V4L2_CID_MPEG_VIDEO_ASPECT (V4L2_CID_MPEG_BASE+201)
1069enum <link linkend="v4l2-mpeg-video-aspect">v4l2_mpeg_video_aspect</link> {
1070 V4L2_MPEG_VIDEO_ASPECT_1x1 = 0,
1071 V4L2_MPEG_VIDEO_ASPECT_4x3 = 1,
1072 V4L2_MPEG_VIDEO_ASPECT_16x9 = 2,
1073 V4L2_MPEG_VIDEO_ASPECT_221x100 = 3,
1074};
1075#define V4L2_CID_MPEG_VIDEO_B_FRAMES (V4L2_CID_MPEG_BASE+202)
1076#define V4L2_CID_MPEG_VIDEO_GOP_SIZE (V4L2_CID_MPEG_BASE+203)
1077#define V4L2_CID_MPEG_VIDEO_GOP_CLOSURE (V4L2_CID_MPEG_BASE+204)
1078#define V4L2_CID_MPEG_VIDEO_PULLDOWN (V4L2_CID_MPEG_BASE+205)
1079#define V4L2_CID_MPEG_VIDEO_BITRATE_MODE (V4L2_CID_MPEG_BASE+206)
1080enum <link linkend="v4l2-mpeg-video-bitrate-mode">v4l2_mpeg_video_bitrate_mode</link> {
1081 V4L2_MPEG_VIDEO_BITRATE_MODE_VBR = 0,
1082 V4L2_MPEG_VIDEO_BITRATE_MODE_CBR = 1,
1083};
1084#define V4L2_CID_MPEG_VIDEO_BITRATE (V4L2_CID_MPEG_BASE+207)
1085#define V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (V4L2_CID_MPEG_BASE+208)
1086#define V4L2_CID_MPEG_VIDEO_TEMPORAL_DECIMATION (V4L2_CID_MPEG_BASE+209)
1087#define V4L2_CID_MPEG_VIDEO_MUTE (V4L2_CID_MPEG_BASE+210)
1088#define V4L2_CID_MPEG_VIDEO_MUTE_YUV (V4L2_CID_MPEG_BASE+211)
1089
1090/* MPEG-class control IDs specific to the CX2341x driver as defined by V4L2 */
1091#define V4L2_CID_MPEG_CX2341X_BASE (V4L2_CTRL_CLASS_MPEG | 0x1000)
1092#define V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE (V4L2_CID_MPEG_CX2341X_BASE+0)
1093enum <link linkend="v4l2-mpeg-cx2341x-video-spatial-filter-mode">v4l2_mpeg_cx2341x_video_spatial_filter_mode</link> {
1094 V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_MANUAL = 0,
1095 V4L2_MPEG_CX2341X_VIDEO_SPATIAL_FILTER_MODE_AUTO = 1,
1096};
1097#define V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER (V4L2_CID_MPEG_CX2341X_BASE+1)
1098#define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+2)
1099enum <link linkend="luma-spatial-filter-type">v4l2_mpeg_cx2341x_video_luma_spatial_filter_type</link> {
1100 V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_OFF = 0,
1101 V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_HOR = 1,
1102 V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_1D_VERT = 2,
1103 V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_HV_SEPARABLE = 3,
1104 V4L2_MPEG_CX2341X_VIDEO_LUMA_SPATIAL_FILTER_TYPE_2D_SYM_NON_SEPARABLE = 4,
1105};
1106#define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+3)
1107enum <link linkend="chroma-spatial-filter-type">v4l2_mpeg_cx2341x_video_chroma_spatial_filter_type</link> {
1108 V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_OFF = 0,
1109 V4L2_MPEG_CX2341X_VIDEO_CHROMA_SPATIAL_FILTER_TYPE_1D_HOR = 1,
1110};
1111#define V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE (V4L2_CID_MPEG_CX2341X_BASE+4)
1112enum <link linkend="v4l2-mpeg-cx2341x-video-temporal-filter-mode">v4l2_mpeg_cx2341x_video_temporal_filter_mode</link> {
1113 V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_MANUAL = 0,
1114 V4L2_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER_MODE_AUTO = 1,
1115};
1116#define V4L2_CID_MPEG_CX2341X_VIDEO_TEMPORAL_FILTER (V4L2_CID_MPEG_CX2341X_BASE+5)
1117#define V4L2_CID_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE (V4L2_CID_MPEG_CX2341X_BASE+6)
1118enum <link linkend="v4l2-mpeg-cx2341x-video-median-filter-type">v4l2_mpeg_cx2341x_video_median_filter_type</link> {
1119 V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_OFF = 0,
1120 V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR = 1,
1121 V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_VERT = 2,
1122 V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_HOR_VERT = 3,
1123 V4L2_MPEG_CX2341X_VIDEO_MEDIAN_FILTER_TYPE_DIAG = 4,
1124};
1125#define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_BOTTOM (V4L2_CID_MPEG_CX2341X_BASE+7)
1126#define V4L2_CID_MPEG_CX2341X_VIDEO_LUMA_MEDIAN_FILTER_TOP (V4L2_CID_MPEG_CX2341X_BASE+8)
1127#define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_BOTTOM (V4L2_CID_MPEG_CX2341X_BASE+9)
1128#define V4L2_CID_MPEG_CX2341X_VIDEO_CHROMA_MEDIAN_FILTER_TOP (V4L2_CID_MPEG_CX2341X_BASE+10)
1129#define V4L2_CID_MPEG_CX2341X_STREAM_INSERT_NAV_PACKETS (V4L2_CID_MPEG_CX2341X_BASE+11)
1130
1131/* Camera class control IDs */
1132#define V4L2_CID_CAMERA_CLASS_BASE (V4L2_CTRL_CLASS_CAMERA | 0x900)
1133#define V4L2_CID_CAMERA_CLASS (V4L2_CTRL_CLASS_CAMERA | 1)
1134
1135#define V4L2_CID_EXPOSURE_AUTO (V4L2_CID_CAMERA_CLASS_BASE+1)
1136enum <link linkend="v4l2-exposure-auto-type">v4l2_exposure_auto_type</link> {
1137 V4L2_EXPOSURE_AUTO = 0,
1138 V4L2_EXPOSURE_MANUAL = 1,
1139 V4L2_EXPOSURE_SHUTTER_PRIORITY = 2,
1140 V4L2_EXPOSURE_APERTURE_PRIORITY = 3
1141};
1142#define V4L2_CID_EXPOSURE_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+2)
1143#define V4L2_CID_EXPOSURE_AUTO_PRIORITY (V4L2_CID_CAMERA_CLASS_BASE+3)
1144
1145#define V4L2_CID_PAN_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+4)
1146#define V4L2_CID_TILT_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+5)
1147#define V4L2_CID_PAN_RESET (V4L2_CID_CAMERA_CLASS_BASE+6)
1148#define V4L2_CID_TILT_RESET (V4L2_CID_CAMERA_CLASS_BASE+7)
1149
1150#define V4L2_CID_PAN_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+8)
1151#define V4L2_CID_TILT_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+9)
1152
1153#define V4L2_CID_FOCUS_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+10)
1154#define V4L2_CID_FOCUS_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+11)
1155#define V4L2_CID_FOCUS_AUTO (V4L2_CID_CAMERA_CLASS_BASE+12)
1156
1157#define V4L2_CID_ZOOM_ABSOLUTE (V4L2_CID_CAMERA_CLASS_BASE+13)
1158#define V4L2_CID_ZOOM_RELATIVE (V4L2_CID_CAMERA_CLASS_BASE+14)
1159#define V4L2_CID_ZOOM_CONTINUOUS (V4L2_CID_CAMERA_CLASS_BASE+15)
1160
1161#define V4L2_CID_PRIVACY (V4L2_CID_CAMERA_CLASS_BASE+16)
1162
1163/* FM Modulator class control IDs */
1164#define V4L2_CID_FM_TX_CLASS_BASE (V4L2_CTRL_CLASS_FM_TX | 0x900)
1165#define V4L2_CID_FM_TX_CLASS (V4L2_CTRL_CLASS_FM_TX | 1)
1166
1167#define V4L2_CID_RDS_TX_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 1)
1168#define V4L2_CID_RDS_TX_PI (V4L2_CID_FM_TX_CLASS_BASE + 2)
1169#define V4L2_CID_RDS_TX_PTY (V4L2_CID_FM_TX_CLASS_BASE + 3)
1170#define V4L2_CID_RDS_TX_PS_NAME (V4L2_CID_FM_TX_CLASS_BASE + 5)
1171#define V4L2_CID_RDS_TX_RADIO_TEXT (V4L2_CID_FM_TX_CLASS_BASE + 6)
1172
1173#define V4L2_CID_AUDIO_LIMITER_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 64)
1174#define V4L2_CID_AUDIO_LIMITER_RELEASE_TIME (V4L2_CID_FM_TX_CLASS_BASE + 65)
1175#define V4L2_CID_AUDIO_LIMITER_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 66)
1176
1177#define V4L2_CID_AUDIO_COMPRESSION_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 80)
1178#define V4L2_CID_AUDIO_COMPRESSION_GAIN (V4L2_CID_FM_TX_CLASS_BASE + 81)
1179#define V4L2_CID_AUDIO_COMPRESSION_THRESHOLD (V4L2_CID_FM_TX_CLASS_BASE + 82)
1180#define V4L2_CID_AUDIO_COMPRESSION_ATTACK_TIME (V4L2_CID_FM_TX_CLASS_BASE + 83)
1181#define V4L2_CID_AUDIO_COMPRESSION_RELEASE_TIME (V4L2_CID_FM_TX_CLASS_BASE + 84)
1182
1183#define V4L2_CID_PILOT_TONE_ENABLED (V4L2_CID_FM_TX_CLASS_BASE + 96)
1184#define V4L2_CID_PILOT_TONE_DEVIATION (V4L2_CID_FM_TX_CLASS_BASE + 97)
1185#define V4L2_CID_PILOT_TONE_FREQUENCY (V4L2_CID_FM_TX_CLASS_BASE + 98)
1186
1187#define V4L2_CID_TUNE_PREEMPHASIS (V4L2_CID_FM_TX_CLASS_BASE + 112)
1188enum <link linkend="v4l2-preemphasis">v4l2_preemphasis</link> {
1189 V4L2_PREEMPHASIS_DISABLED = 0,
1190 V4L2_PREEMPHASIS_50_uS = 1,
1191 V4L2_PREEMPHASIS_75_uS = 2,
1192};
1193#define V4L2_CID_TUNE_POWER_LEVEL (V4L2_CID_FM_TX_CLASS_BASE + 113)
1194#define V4L2_CID_TUNE_ANTENNA_CAPACITOR (V4L2_CID_FM_TX_CLASS_BASE + 114)
1195
1196/*
1197 * T U N I N G
1198 */
1199struct <link linkend="v4l2-tuner">v4l2_tuner</link> {
1200 __u32 index;
1201 __u8 name[32];
1202 enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type;
1203 __u32 capability;
1204 __u32 rangelow;
1205 __u32 rangehigh;
1206 __u32 rxsubchans;
1207 __u32 audmode;
1208 __s32 signal;
1209 __s32 afc;
1210 __u32 reserved[4];
1211};
1212
1213struct <link linkend="v4l2-modulator">v4l2_modulator</link> {
1214 __u32 index;
1215 __u8 name[32];
1216 __u32 capability;
1217 __u32 rangelow;
1218 __u32 rangehigh;
1219 __u32 txsubchans;
1220 __u32 reserved[4];
1221};
1222
1223/* Flags for the 'capability' field */
1224#define V4L2_TUNER_CAP_LOW 0x0001
1225#define V4L2_TUNER_CAP_NORM 0x0002
1226#define V4L2_TUNER_CAP_STEREO 0x0010
1227#define V4L2_TUNER_CAP_LANG2 0x0020
1228#define V4L2_TUNER_CAP_SAP 0x0020
1229#define V4L2_TUNER_CAP_LANG1 0x0040
1230#define V4L2_TUNER_CAP_RDS 0x0080
1231
1232/* Flags for the 'rxsubchans' field */
1233#define V4L2_TUNER_SUB_MONO 0x0001
1234#define V4L2_TUNER_SUB_STEREO 0x0002
1235#define V4L2_TUNER_SUB_LANG2 0x0004
1236#define V4L2_TUNER_SUB_SAP 0x0004
1237#define V4L2_TUNER_SUB_LANG1 0x0008
1238#define V4L2_TUNER_SUB_RDS 0x0010
1239
1240/* Values for the 'audmode' field */
1241#define V4L2_TUNER_MODE_MONO 0x0000
1242#define V4L2_TUNER_MODE_STEREO 0x0001
1243#define V4L2_TUNER_MODE_LANG2 0x0002
1244#define V4L2_TUNER_MODE_SAP 0x0002
1245#define V4L2_TUNER_MODE_LANG1 0x0003
1246#define V4L2_TUNER_MODE_LANG1_LANG2 0x0004
1247
1248struct <link linkend="v4l2-frequency">v4l2_frequency</link> {
1249 __u32 tuner;
1250 enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type;
1251 __u32 frequency;
1252 __u32 reserved[8];
1253};
1254
1255struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link> {
1256 __u32 tuner;
1257 enum <link linkend="v4l2-tuner-type">v4l2_tuner_type</link> type;
1258 __u32 seek_upward;
1259 __u32 wrap_around;
1260 __u32 reserved[8];
1261};
1262
1263/*
1264 * R D S
1265 */
1266
1267struct <link linkend="v4l2-rds-data">v4l2_rds_data</link> {
1268 __u8 lsb;
1269 __u8 msb;
1270 __u8 block;
1271} __attribute__ ((packed));
1272
1273#define V4L2_RDS_BLOCK_MSK 0x7
1274#define V4L2_RDS_BLOCK_A 0
1275#define V4L2_RDS_BLOCK_B 1
1276#define V4L2_RDS_BLOCK_C 2
1277#define V4L2_RDS_BLOCK_D 3
1278#define V4L2_RDS_BLOCK_C_ALT 4
1279#define V4L2_RDS_BLOCK_INVALID 7
1280
1281#define V4L2_RDS_BLOCK_CORRECTED 0x40
1282#define V4L2_RDS_BLOCK_ERROR 0x80
1283
1284/*
1285 * A U D I O
1286 */
1287struct <link linkend="v4l2-audio">v4l2_audio</link> {
1288 __u32 index;
1289 __u8 name[32];
1290 __u32 capability;
1291 __u32 mode;
1292 __u32 reserved[2];
1293};
1294
1295/* Flags for the 'capability' field */
1296#define V4L2_AUDCAP_STEREO 0x00001
1297#define V4L2_AUDCAP_AVL 0x00002
1298
1299/* Flags for the 'mode' field */
1300#define V4L2_AUDMODE_AVL 0x00001
1301
1302struct <link linkend="v4l2-audioout">v4l2_audioout</link> {
1303 __u32 index;
1304 __u8 name[32];
1305 __u32 capability;
1306 __u32 mode;
1307 __u32 reserved[2];
1308};
1309
1310/*
1311 * M P E G S E R V I C E S
1312 *
1313 * NOTE: EXPERIMENTAL API
1314 */
1315#if 1 /*KEEP*/
1316#define V4L2_ENC_IDX_FRAME_I (0)
1317#define V4L2_ENC_IDX_FRAME_P (1)
1318#define V4L2_ENC_IDX_FRAME_B (2)
1319#define V4L2_ENC_IDX_FRAME_MASK (0xf)
1320
1321struct <link linkend="v4l2-enc-idx-entry">v4l2_enc_idx_entry</link> {
1322 __u64 offset;
1323 __u64 pts;
1324 __u32 length;
1325 __u32 flags;
1326 __u32 reserved[2];
1327};
1328
1329#define V4L2_ENC_IDX_ENTRIES (64)
1330struct <link linkend="v4l2-enc-idx">v4l2_enc_idx</link> {
1331 __u32 entries;
1332 __u32 entries_cap;
1333 __u32 reserved[4];
1334 struct <link linkend="v4l2-enc-idx-entry">v4l2_enc_idx_entry</link> entry[V4L2_ENC_IDX_ENTRIES];
1335};
1336
1337
1338#define V4L2_ENC_CMD_START (0)
1339#define V4L2_ENC_CMD_STOP (1)
1340#define V4L2_ENC_CMD_PAUSE (2)
1341#define V4L2_ENC_CMD_RESUME (3)
1342
1343/* Flags for V4L2_ENC_CMD_STOP */
1344#define V4L2_ENC_CMD_STOP_AT_GOP_END (1 &lt;&lt; 0)
1345
1346struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link> {
1347 __u32 cmd;
1348 __u32 flags;
1349 union {
1350 struct {
1351 __u32 data[8];
1352 } raw;
1353 };
1354};
1355
1356#endif
1357
1358
1359/*
1360 * D A T A S E R V I C E S ( V B I )
1361 *
1362 * Data services API by Michael Schimek
1363 */
1364
1365/* Raw VBI */
1366struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> {
1367 __u32 sampling_rate; /* in 1 Hz */
1368 __u32 offset;
1369 __u32 samples_per_line;
1370 __u32 sample_format; /* V4L2_PIX_FMT_* */
1371 __s32 start[2];
1372 __u32 count[2];
1373 __u32 flags; /* V4L2_VBI_* */
1374 __u32 reserved[2]; /* must be zero */
1375};
1376
1377/* VBI flags */
1378#define V4L2_VBI_UNSYNC (1 &lt;&lt; 0)
1379#define V4L2_VBI_INTERLACED (1 &lt;&lt; 1)
1380
1381/* Sliced VBI
1382 *
1383 * This implements is a proposal V4L2 API to allow SLICED VBI
1384 * required for some hardware encoders. It should change without
1385 * notice in the definitive implementation.
1386 */
1387
1388struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> {
1389 __u16 service_set;
1390 /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field
1391 service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field
1392 (equals frame lines 313-336 for 625 line video
1393 standards, 263-286 for 525 line standards) */
1394 __u16 service_lines[2][24];
1395 __u32 io_size;
1396 __u32 reserved[2]; /* must be zero */
1397};
1398
1399/* Teletext World System Teletext
1400 (WST), defined on ITU-R BT.653-2 */
1401#define V4L2_SLICED_TELETEXT_B (0x0001)
1402/* Video Program System, defined on ETS 300 231*/
1403#define V4L2_SLICED_VPS (0x0400)
1404/* Closed Caption, defined on EIA-608 */
1405#define V4L2_SLICED_CAPTION_525 (0x1000)
1406/* Wide Screen System, defined on ITU-R BT1119.1 */
1407#define V4L2_SLICED_WSS_625 (0x4000)
1408
1409#define V4L2_SLICED_VBI_525 (V4L2_SLICED_CAPTION_525)
1410#define V4L2_SLICED_VBI_625 (V4L2_SLICED_TELETEXT_B | V4L2_SLICED_VPS | V4L2_SLICED_WSS_625)
1411
1412struct <link linkend="v4l2-sliced-vbi-cap">v4l2_sliced_vbi_cap</link> {
1413 __u16 service_set;
1414 /* service_lines[0][...] specifies lines 0-23 (1-23 used) of the first field
1415 service_lines[1][...] specifies lines 0-23 (1-23 used) of the second field
1416 (equals frame lines 313-336 for 625 line video
1417 standards, 263-286 for 525 line standards) */
1418 __u16 service_lines[2][24];
1419 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
1420 __u32 reserved[3]; /* must be 0 */
1421};
1422
1423struct <link linkend="v4l2-sliced-vbi-data">v4l2_sliced_vbi_data</link> {
1424 __u32 id;
1425 __u32 field; /* 0: first field, 1: second field */
1426 __u32 line; /* 1-23 */
1427 __u32 reserved; /* must be 0 */
1428 __u8 data[48];
1429};
1430
1431/*
1432 * Sliced VBI data inserted into MPEG Streams
1433 */
1434
1435/*
1436 * V4L2_MPEG_STREAM_VBI_FMT_IVTV:
1437 *
1438 * Structure of payload contained in an MPEG 2 Private Stream 1 PES Packet in an
1439 * MPEG-2 Program Pack that contains V4L2_MPEG_STREAM_VBI_FMT_IVTV Sliced VBI
1440 * data
1441 *
1442 * Note, the MPEG-2 Program Pack and Private Stream 1 PES packet header
1443 * definitions are not included here. See the MPEG-2 specifications for details
1444 * on these headers.
1445 */
1446
1447/* Line type IDs */
1448#define V4L2_MPEG_VBI_IVTV_TELETEXT_B (1)
1449#define V4L2_MPEG_VBI_IVTV_CAPTION_525 (4)
1450#define V4L2_MPEG_VBI_IVTV_WSS_625 (5)
1451#define V4L2_MPEG_VBI_IVTV_VPS (7)
1452
1453struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> {
1454 __u8 id; /* One of V4L2_MPEG_VBI_IVTV_* above */
1455 __u8 data[42]; /* Sliced VBI data for the line */
1456} __attribute__ ((packed));
1457
1458struct <link linkend="v4l2-mpeg-vbi-itv0">v4l2_mpeg_vbi_itv0</link> {
1459 __le32 linemask[2]; /* Bitmasks of VBI service lines present */
1460 struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> line[35];
1461} __attribute__ ((packed));
1462
1463struct <link linkend="v4l2-mpeg-vbi-itv0-1">v4l2_mpeg_vbi_ITV0</link> {
1464 struct <link linkend="v4l2-mpeg-vbi-itv0-line">v4l2_mpeg_vbi_itv0_line</link> line[36];
1465} __attribute__ ((packed));
1466
1467#define V4L2_MPEG_VBI_IVTV_MAGIC0 "itv0"
1468#define V4L2_MPEG_VBI_IVTV_MAGIC1 "ITV0"
1469
1470struct <link linkend="v4l2-mpeg-vbi-fmt-ivtv">v4l2_mpeg_vbi_fmt_ivtv</link> {
1471 __u8 magic[4];
1472 union {
1473 struct <link linkend="v4l2-mpeg-vbi-itv0">v4l2_mpeg_vbi_itv0</link> itv0;
1474 struct <link linkend="v4l2-mpeg-vbi-itv0-1">v4l2_mpeg_vbi_ITV0</link> ITV0;
1475 };
1476} __attribute__ ((packed));
1477
1478/*
1479 * A G G R E G A T E S T R U C T U R E S
1480 */
1481
1482/* Stream data format
1483 */
1484struct <link linkend="v4l2-format">v4l2_format</link> {
1485 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
1486 union {
1487 struct <link linkend="v4l2-pix-format">v4l2_pix_format</link> pix; /* V4L2_BUF_TYPE_VIDEO_CAPTURE */
1488 struct <link linkend="v4l2-window">v4l2_window</link> win; /* V4L2_BUF_TYPE_VIDEO_OVERLAY */
1489 struct <link linkend="v4l2-vbi-format">v4l2_vbi_format</link> vbi; /* V4L2_BUF_TYPE_VBI_CAPTURE */
1490 struct <link linkend="v4l2-sliced-vbi-format">v4l2_sliced_vbi_format</link> sliced; /* V4L2_BUF_TYPE_SLICED_VBI_CAPTURE */
1491 __u8 raw_data[200]; /* user-defined */
1492 } fmt;
1493};
1494
1495
1496/* Stream type-dependent parameters
1497 */
1498struct <link linkend="v4l2-streamparm">v4l2_streamparm</link> {
1499 enum <link linkend="v4l2-buf-type">v4l2_buf_type</link> type;
1500 union {
1501 struct <link linkend="v4l2-captureparm">v4l2_captureparm</link> capture;
1502 struct <link linkend="v4l2-outputparm">v4l2_outputparm</link> output;
1503 __u8 raw_data[200]; /* user-defined */
1504 } parm;
1505};
1506
1507/*
1508 * A D V A N C E D D E B U G G I N G
1509 *
1510 * NOTE: EXPERIMENTAL API, NEVER RELY ON THIS IN APPLICATIONS!
1511 * FOR DEBUGGING, TESTING AND INTERNAL USE ONLY!
1512 */
1513
1514/* VIDIOC_DBG_G_REGISTER and VIDIOC_DBG_S_REGISTER */
1515
1516#define V4L2_CHIP_MATCH_HOST 0 /* Match against chip ID on host (0 for the host) */
1517#define V4L2_CHIP_MATCH_I2C_DRIVER 1 /* Match against I2C driver name */
1518#define V4L2_CHIP_MATCH_I2C_ADDR 2 /* Match against I2C 7-bit address */
1519#define V4L2_CHIP_MATCH_AC97 3 /* Match against anciliary AC97 chip */
1520
1521struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> {
1522 __u32 type; /* Match type */
1523 union { /* Match this chip, meaning determined by type */
1524 __u32 addr;
1525 char name[32];
1526 };
1527} __attribute__ ((packed));
1528
1529struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link> {
1530 struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> match;
1531 __u32 size; /* register size in bytes */
1532 __u64 reg;
1533 __u64 val;
1534} __attribute__ ((packed));
1535
1536/* VIDIOC_DBG_G_CHIP_IDENT */
1537struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link> {
1538 struct <link linkend="v4l2-dbg-match">v4l2_dbg_match</link> match;
1539 __u32 ident; /* chip identifier as specified in &lt;media/v4l2-chip-ident.h&gt; */
1540 __u32 revision; /* chip revision, chip specific */
1541} __attribute__ ((packed));
1542
1543/*
1544 * I O C T L C O D E S F O R V I D E O D E V I C E S
1545 *
1546 */
1547#define VIDIOC_QUERYCAP _IOR('V', 0, struct <link linkend="v4l2-capability">v4l2_capability</link>)
1548#define VIDIOC_RESERVED _IO('V', 1)
1549#define VIDIOC_ENUM_FMT _IOWR('V', 2, struct <link linkend="v4l2-fmtdesc">v4l2_fmtdesc</link>)
1550#define VIDIOC_G_FMT _IOWR('V', 4, struct <link linkend="v4l2-format">v4l2_format</link>)
1551#define VIDIOC_S_FMT _IOWR('V', 5, struct <link linkend="v4l2-format">v4l2_format</link>)
1552#define VIDIOC_REQBUFS _IOWR('V', 8, struct <link linkend="v4l2-requestbuffers">v4l2_requestbuffers</link>)
1553#define VIDIOC_QUERYBUF _IOWR('V', 9, struct <link linkend="v4l2-buffer">v4l2_buffer</link>)
1554#define VIDIOC_G_FBUF _IOR('V', 10, struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link>)
1555#define VIDIOC_S_FBUF _IOW('V', 11, struct <link linkend="v4l2-framebuffer">v4l2_framebuffer</link>)
1556#define VIDIOC_OVERLAY _IOW('V', 14, int)
1557#define VIDIOC_QBUF _IOWR('V', 15, struct <link linkend="v4l2-buffer">v4l2_buffer</link>)
1558#define VIDIOC_DQBUF _IOWR('V', 17, struct <link linkend="v4l2-buffer">v4l2_buffer</link>)
1559#define VIDIOC_STREAMON _IOW('V', 18, int)
1560#define VIDIOC_STREAMOFF _IOW('V', 19, int)
1561#define VIDIOC_G_PARM _IOWR('V', 21, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>)
1562#define VIDIOC_S_PARM _IOWR('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>)
1563#define VIDIOC_G_STD _IOR('V', 23, v4l2_std_id)
1564#define VIDIOC_S_STD _IOW('V', 24, v4l2_std_id)
1565#define VIDIOC_ENUMSTD _IOWR('V', 25, struct <link linkend="v4l2-standard">v4l2_standard</link>)
1566#define VIDIOC_ENUMINPUT _IOWR('V', 26, struct <link linkend="v4l2-input">v4l2_input</link>)
1567#define VIDIOC_G_CTRL _IOWR('V', 27, struct <link linkend="v4l2-control">v4l2_control</link>)
1568#define VIDIOC_S_CTRL _IOWR('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>)
1569#define VIDIOC_G_TUNER _IOWR('V', 29, struct <link linkend="v4l2-tuner">v4l2_tuner</link>)
1570#define VIDIOC_S_TUNER _IOW('V', 30, struct <link linkend="v4l2-tuner">v4l2_tuner</link>)
1571#define VIDIOC_G_AUDIO _IOR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>)
1572#define VIDIOC_S_AUDIO _IOW('V', 34, struct <link linkend="v4l2-audio">v4l2_audio</link>)
1573#define VIDIOC_QUERYCTRL _IOWR('V', 36, struct <link linkend="v4l2-queryctrl">v4l2_queryctrl</link>)
1574#define VIDIOC_QUERYMENU _IOWR('V', 37, struct <link linkend="v4l2-querymenu">v4l2_querymenu</link>)
1575#define VIDIOC_G_INPUT _IOR('V', 38, int)
1576#define VIDIOC_S_INPUT _IOWR('V', 39, int)
1577#define VIDIOC_G_OUTPUT _IOR('V', 46, int)
1578#define VIDIOC_S_OUTPUT _IOWR('V', 47, int)
1579#define VIDIOC_ENUMOUTPUT _IOWR('V', 48, struct <link linkend="v4l2-output">v4l2_output</link>)
1580#define VIDIOC_G_AUDOUT _IOR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>)
1581#define VIDIOC_S_AUDOUT _IOW('V', 50, struct <link linkend="v4l2-audioout">v4l2_audioout</link>)
1582#define VIDIOC_G_MODULATOR _IOWR('V', 54, struct <link linkend="v4l2-modulator">v4l2_modulator</link>)
1583#define VIDIOC_S_MODULATOR _IOW('V', 55, struct <link linkend="v4l2-modulator">v4l2_modulator</link>)
1584#define VIDIOC_G_FREQUENCY _IOWR('V', 56, struct <link linkend="v4l2-frequency">v4l2_frequency</link>)
1585#define VIDIOC_S_FREQUENCY _IOW('V', 57, struct <link linkend="v4l2-frequency">v4l2_frequency</link>)
1586#define VIDIOC_CROPCAP _IOWR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>)
1587#define VIDIOC_G_CROP _IOWR('V', 59, struct <link linkend="v4l2-crop">v4l2_crop</link>)
1588#define VIDIOC_S_CROP _IOW('V', 60, struct <link linkend="v4l2-crop">v4l2_crop</link>)
1589#define VIDIOC_G_JPEGCOMP _IOR('V', 61, struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link>)
1590#define VIDIOC_S_JPEGCOMP _IOW('V', 62, struct <link linkend="v4l2-jpegcompression">v4l2_jpegcompression</link>)
1591#define VIDIOC_QUERYSTD _IOR('V', 63, v4l2_std_id)
1592#define VIDIOC_TRY_FMT _IOWR('V', 64, struct <link linkend="v4l2-format">v4l2_format</link>)
1593#define VIDIOC_ENUMAUDIO _IOWR('V', 65, struct <link linkend="v4l2-audio">v4l2_audio</link>)
1594#define VIDIOC_ENUMAUDOUT _IOWR('V', 66, struct <link linkend="v4l2-audioout">v4l2_audioout</link>)
1595#define VIDIOC_G_PRIORITY _IOR('V', 67, enum <link linkend="v4l2-priority">v4l2_priority</link>)
1596#define VIDIOC_S_PRIORITY _IOW('V', 68, enum <link linkend="v4l2-priority">v4l2_priority</link>)
1597#define VIDIOC_G_SLICED_VBI_CAP _IOWR('V', 69, struct <link linkend="v4l2-sliced-vbi-cap">v4l2_sliced_vbi_cap</link>)
1598#define VIDIOC_LOG_STATUS _IO('V', 70)
1599#define VIDIOC_G_EXT_CTRLS _IOWR('V', 71, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>)
1600#define VIDIOC_S_EXT_CTRLS _IOWR('V', 72, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>)
1601#define VIDIOC_TRY_EXT_CTRLS _IOWR('V', 73, struct <link linkend="v4l2-ext-controls">v4l2_ext_controls</link>)
1602#if 1 /*KEEP*/
1603#define VIDIOC_ENUM_FRAMESIZES _IOWR('V', 74, struct <link linkend="v4l2-frmsizeenum">v4l2_frmsizeenum</link>)
1604#define VIDIOC_ENUM_FRAMEINTERVALS _IOWR('V', 75, struct <link linkend="v4l2-frmivalenum">v4l2_frmivalenum</link>)
1605#define VIDIOC_G_ENC_INDEX _IOR('V', 76, struct <link linkend="v4l2-enc-idx">v4l2_enc_idx</link>)
1606#define VIDIOC_ENCODER_CMD _IOWR('V', 77, struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link>)
1607#define VIDIOC_TRY_ENCODER_CMD _IOWR('V', 78, struct <link linkend="v4l2-encoder-cmd">v4l2_encoder_cmd</link>)
1608#endif
1609
1610#if 1 /*KEEP*/
1611/* Experimental, meant for debugging, testing and internal use.
1612 Only implemented if CONFIG_VIDEO_ADV_DEBUG is defined.
1613 You must be root to use these ioctls. Never use these in applications! */
1614#define VIDIOC_DBG_S_REGISTER _IOW('V', 79, struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link>)
1615#define VIDIOC_DBG_G_REGISTER _IOWR('V', 80, struct <link linkend="v4l2-dbg-register">v4l2_dbg_register</link>)
1616
1617/* Experimental, meant for debugging, testing and internal use.
1618 Never use this ioctl in applications! */
1619#define VIDIOC_DBG_G_CHIP_IDENT _IOWR('V', 81, struct <link linkend="v4l2-dbg-chip-ident">v4l2_dbg_chip_ident</link>)
1620#endif
1621
1622#define VIDIOC_S_HW_FREQ_SEEK _IOW('V', 82, struct <link linkend="v4l2-hw-freq-seek">v4l2_hw_freq_seek</link>)
1623/* Reminder: when adding new ioctls please add support for them to
1624 drivers/media/video/v4l2-compat-ioctl32.c as well! */
1625
1626#ifdef __OLD_VIDIOC_
1627/* for compatibility, will go away some day */
1628#define VIDIOC_OVERLAY_OLD _IOWR('V', 14, int)
1629#define VIDIOC_S_PARM_OLD _IOW('V', 22, struct <link linkend="v4l2-streamparm">v4l2_streamparm</link>)
1630#define VIDIOC_S_CTRL_OLD _IOW('V', 28, struct <link linkend="v4l2-control">v4l2_control</link>)
1631#define VIDIOC_G_AUDIO_OLD _IOWR('V', 33, struct <link linkend="v4l2-audio">v4l2_audio</link>)
1632#define VIDIOC_G_AUDOUT_OLD _IOWR('V', 49, struct <link linkend="v4l2-audioout">v4l2_audioout</link>)
1633#define VIDIOC_CROPCAP_OLD _IOR('V', 58, struct <link linkend="v4l2-cropcap">v4l2_cropcap</link>)
1634#endif
1635
1636#define BASE_VIDIOC_PRIVATE 192 /* 192-255 are private */
1637
1638#endif /* __LINUX_VIDEODEV2_H */
1639</programlisting>
diff --git a/Documentation/DocBook/v4l/vidioc-cropcap.xml b/Documentation/DocBook/v4l/vidioc-cropcap.xml
new file mode 100644
index 000000000000..816e90e283c5
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-dbg-g-chip-ident.xml b/Documentation/DocBook/v4l/vidioc-dbg-g-chip-ident.xml
new file mode 100644
index 000000000000..4a09e203af0f
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-dbg-g-register.xml b/Documentation/DocBook/v4l/vidioc-dbg-g-register.xml
new file mode 100644
index 000000000000..980c7f3e2fd6
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/v4l/vidioc-encoder-cmd.xml
new file mode 100644
index 000000000000..b0dde943825c
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
new file mode 100644
index 000000000000..960d44615ca6
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-enum-fmt.xml
@@ -0,0 +1,164 @@
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_OUTPUT</constant>,
80<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver
81defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant>
82and higher.</entry>
83 </row>
84 <row>
85 <entry>__u32</entry>
86 <entry><structfield>flags</structfield></entry>
87 <entry>See <xref linkend="fmtdesc-flags" /></entry>
88 </row>
89 <row>
90 <entry>__u8</entry>
91 <entry><structfield>description</structfield>[32]</entry>
92 <entry>Description of the format, a NUL-terminated ASCII
93string. This information is intended for the user, for example: "YUV
944:2:2".</entry>
95 </row>
96 <row>
97 <entry>__u32</entry>
98 <entry><structfield>pixelformat</structfield></entry>
99 <entry>The image format identifier. This is a
100four character code as computed by the v4l2_fourcc()
101macro:</entry>
102 </row>
103 <row>
104 <entry spanname="hspan"><para><programlisting id="v4l2-fourcc">
105#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))
106</programlisting></para><para>Several image formats are already
107defined by this specification in <xref linkend="pixfmt" />. Note these
108codes are not the same as those used in the Windows world.</para></entry>
109 </row>
110 <row>
111 <entry>__u32</entry>
112 <entry><structfield>reserved</structfield>[4]</entry>
113 <entry>Reserved for future extensions. Drivers must set
114the array to zero.</entry>
115 </row>
116 </tbody>
117 </tgroup>
118 </table>
119
120 <table pgwide="1" frame="none" id="fmtdesc-flags">
121 <title>Image Format Description Flags</title>
122 <tgroup cols="3">
123 &cs-def;
124 <tbody valign="top">
125 <row>
126 <entry><constant>V4L2_FMT_FLAG_COMPRESSED</constant></entry>
127 <entry>0x0001</entry>
128 <entry>This is a compressed format.</entry>
129 </row>
130 <row>
131 <entry><constant>V4L2_FMT_FLAG_EMULATED</constant></entry>
132 <entry>0x0002</entry>
133 <entry>This format is not native to the device but emulated
134through software (usually libv4l2), where possible try to use a native format
135instead for better performance.</entry>
136 </row>
137 </tbody>
138 </tgroup>
139 </table>
140 </refsect1>
141
142 <refsect1>
143 &return-value;
144
145 <variablelist>
146 <varlistentry>
147 <term><errorcode>EINVAL</errorcode></term>
148 <listitem>
149 <para>The &v4l2-fmtdesc; <structfield>type</structfield>
150is not supported or the <structfield>index</structfield> is out of
151bounds.</para>
152 </listitem>
153 </varlistentry>
154 </variablelist>
155 </refsect1>
156</refentry>
157
158<!--
159Local Variables:
160mode: sgml
161sgml-parent-document: "v4l2.sgml"
162indent-tabs-mode: nil
163End:
164-->
diff --git a/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml b/Documentation/DocBook/v4l/vidioc-enum-frameintervals.xml
new file mode 100644
index 000000000000..3c216e113a54
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/v4l/vidioc-enum-framesizes.xml
new file mode 100644
index 000000000000..6afa4542c818
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-enumaudio.xml b/Documentation/DocBook/v4l/vidioc-enumaudio.xml
new file mode 100644
index 000000000000..9ae8f2d3a96f
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-enumaudioout.xml b/Documentation/DocBook/v4l/vidioc-enumaudioout.xml
new file mode 100644
index 000000000000..d3d7c0ab17b8
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-enuminput.xml b/Documentation/DocBook/v4l/vidioc-enuminput.xml
new file mode 100644
index 000000000000..414856b82473
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-enuminput.xml
@@ -0,0 +1,287 @@
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>reserved</structfield>[4]</entry>
128 <entry>Reserved for future extensions. Drivers must set
129the array to zero.</entry>
130 </row>
131 </tbody>
132 </tgroup>
133 </table>
134
135 <table frame="none" pgwide="1" id="input-type">
136 <title>Input Types</title>
137 <tgroup cols="3">
138 &cs-def;
139 <tbody valign="top">
140 <row>
141 <entry><constant>V4L2_INPUT_TYPE_TUNER</constant></entry>
142 <entry>1</entry>
143 <entry>This input uses a tuner (RF demodulator).</entry>
144 </row>
145 <row>
146 <entry><constant>V4L2_INPUT_TYPE_CAMERA</constant></entry>
147 <entry>2</entry>
148 <entry>Analog baseband input, for example CVBS /
149Composite Video, S-Video, RGB.</entry>
150 </row>
151 </tbody>
152 </tgroup>
153 </table>
154
155 <!-- Status flags based on proposal by Mark McClelland,
156video4linux-list@redhat.com on 18 Oct 2002, subject "Re: [V4L] Re:
157v4l2 api". "Why are some of them inverted? So that the driver doesn't
158have to lie about the status in cases where it can't tell one way or
159the other. Plus, a status of zero would generally mean that everything
160is OK." -->
161
162 <table frame="none" pgwide="1" id="input-status">
163 <title>Input Status Flags</title>
164 <tgroup cols="3">
165 <colspec colname="c1" />
166 <colspec colname="c2" align="center" />
167 <colspec colname="c3" />
168 <spanspec namest="c1" nameend="c3" spanname="hspan"
169 align="left" />
170 <tbody valign="top">
171 <row>
172 <entry spanname="hspan">General</entry>
173 </row>
174 <row>
175 <entry><constant>V4L2_IN_ST_NO_POWER</constant></entry>
176 <entry>0x00000001</entry>
177 <entry>Attached device is off.</entry>
178 </row>
179 <row>
180 <entry><constant>V4L2_IN_ST_NO_SIGNAL</constant></entry>
181 <entry>0x00000002</entry>
182 <entry></entry>
183 </row>
184 <row>
185 <entry><constant>V4L2_IN_ST_NO_COLOR</constant></entry>
186 <entry>0x00000004</entry>
187 <entry>The hardware supports color decoding, but does not
188detect color modulation in the signal.</entry>
189 </row>
190 <row>
191 <entry spanname="hspan">Sensor Orientation</entry>
192 </row>
193 <row>
194 <entry><constant>V4L2_IN_ST_HFLIP</constant></entry>
195 <entry>0x00000010</entry>
196 <entry>The input is connected to a device that produces a signal
197that is flipped horizontally and does not correct this before passing the
198signal to userspace.</entry>
199 </row>
200 <row>
201 <entry><constant>V4L2_IN_ST_VFLIP</constant></entry>
202 <entry>0x00000020</entry>
203 <entry>The input is connected to a device that produces a signal
204that is flipped vertically and does not correct this before passing the
205signal to userspace. Note that a 180 degree rotation is the same as HFLIP | VFLIP</entry>
206 </row>
207 <row>
208 <entry spanname="hspan">Analog Video</entry>
209 </row>
210 <row>
211 <entry><constant>V4L2_IN_ST_NO_H_LOCK</constant></entry>
212 <entry>0x00000100</entry>
213 <entry>No horizontal sync lock.</entry>
214 </row>
215 <row>
216 <entry><constant>V4L2_IN_ST_COLOR_KILL</constant></entry>
217 <entry>0x00000200</entry>
218 <entry>A color killer circuit automatically disables color
219decoding when it detects no color modulation. When this flag is set
220the color killer is enabled <emphasis>and</emphasis> has shut off
221color decoding.</entry>
222 </row>
223 <row>
224 <entry spanname="hspan">Digital Video</entry>
225 </row>
226 <row>
227 <entry><constant>V4L2_IN_ST_NO_SYNC</constant></entry>
228 <entry>0x00010000</entry>
229 <entry>No synchronization lock.</entry>
230 </row>
231 <row>
232 <entry><constant>V4L2_IN_ST_NO_EQU</constant></entry>
233 <entry>0x00020000</entry>
234 <entry>No equalizer lock.</entry>
235 </row>
236 <row>
237 <entry><constant>V4L2_IN_ST_NO_CARRIER</constant></entry>
238 <entry>0x00040000</entry>
239 <entry>Carrier recovery failed.</entry>
240 </row>
241 <row>
242 <entry spanname="hspan">VCR and Set-Top Box</entry>
243 </row>
244 <row>
245 <entry><constant>V4L2_IN_ST_MACROVISION</constant></entry>
246 <entry>0x01000000</entry>
247 <entry>Macrovision is an analog copy prevention system
248mangling the video signal to confuse video recorders. When this
249flag is set Macrovision has been detected.</entry>
250 </row>
251 <row>
252 <entry><constant>V4L2_IN_ST_NO_ACCESS</constant></entry>
253 <entry>0x02000000</entry>
254 <entry>Conditional access denied.</entry>
255 </row>
256 <row>
257 <entry><constant>V4L2_IN_ST_VTR</constant></entry>
258 <entry>0x04000000</entry>
259 <entry>VTR time constant. [?]</entry>
260 </row>
261 </tbody>
262 </tgroup>
263 </table>
264 </refsect1>
265
266 <refsect1>
267 &return-value;
268
269 <variablelist>
270 <varlistentry>
271 <term><errorcode>EINVAL</errorcode></term>
272 <listitem>
273 <para>The &v4l2-input; <structfield>index</structfield> is
274out of bounds.</para>
275 </listitem>
276 </varlistentry>
277 </variablelist>
278 </refsect1>
279</refentry>
280
281<!--
282Local Variables:
283mode: sgml
284sgml-parent-document: "v4l2.sgml"
285indent-tabs-mode: nil
286End:
287-->
diff --git a/Documentation/DocBook/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/v4l/vidioc-enumoutput.xml
new file mode 100644
index 000000000000..e8d16dcd50cf
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-enumoutput.xml
@@ -0,0 +1,172 @@
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>reserved</structfield>[4]</entry>
118 <entry>Reserved for future extensions. Drivers must set
119the array to zero.</entry>
120 </row>
121 </tbody>
122 </tgroup>
123 </table>
124
125 <table frame="none" pgwide="1" id="output-type">
126 <title>Output Type</title>
127 <tgroup cols="3">
128 &cs-def;
129 <tbody valign="top">
130 <row>
131 <entry><constant>V4L2_OUTPUT_TYPE_MODULATOR</constant></entry>
132 <entry>1</entry>
133 <entry>This output is an analog TV modulator.</entry>
134 </row>
135 <row>
136 <entry><constant>V4L2_OUTPUT_TYPE_ANALOG</constant></entry>
137 <entry>2</entry>
138 <entry>Analog baseband output, for example Composite /
139CVBS, S-Video, RGB.</entry>
140 </row>
141 <row>
142 <entry><constant>V4L2_OUTPUT_TYPE_ANALOGVGAOVERLAY</constant></entry>
143 <entry>3</entry>
144 <entry>[?]</entry>
145 </row>
146 </tbody>
147 </tgroup>
148 </table>
149
150 </refsect1>
151 <refsect1>
152 &return-value;
153
154 <variablelist>
155 <varlistentry>
156 <term><errorcode>EINVAL</errorcode></term>
157 <listitem>
158 <para>The &v4l2-output; <structfield>index</structfield>
159is out of bounds.</para>
160 </listitem>
161 </varlistentry>
162 </variablelist>
163 </refsect1>
164</refentry>
165
166<!--
167Local Variables:
168mode: sgml
169sgml-parent-document: "v4l2.sgml"
170indent-tabs-mode: nil
171End:
172-->
diff --git a/Documentation/DocBook/v4l/vidioc-enumstd.xml b/Documentation/DocBook/v4l/vidioc-enumstd.xml
new file mode 100644
index 000000000000..95803fe2c8e4
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-audio.xml b/Documentation/DocBook/v4l/vidioc-g-audio.xml
new file mode 100644
index 000000000000..65361a8c2b05
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-audioout.xml b/Documentation/DocBook/v4l/vidioc-g-audioout.xml
new file mode 100644
index 000000000000..3632730c5c6e
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-crop.xml b/Documentation/DocBook/v4l/vidioc-g-crop.xml
new file mode 100644
index 000000000000..d235b1dedbed
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-ctrl.xml b/Documentation/DocBook/v4l/vidioc-g-ctrl.xml
new file mode 100644
index 000000000000..8b5e6ff7f3df
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/v4l/vidioc-g-enc-index.xml
new file mode 100644
index 000000000000..9f242e4b2948
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/v4l/vidioc-g-ext-ctrls.xml
new file mode 100644
index 000000000000..3aa7f8f9ff0c
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-fbuf.xml b/Documentation/DocBook/v4l/vidioc-g-fbuf.xml
new file mode 100644
index 000000000000..f7017062656e
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-g-fbuf.xml
@@ -0,0 +1,456 @@
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 </tbody>
340 </tgroup>
341 </table>
342
343 <table pgwide="1" frame="none" id="framebuffer-flags">
344 <title>Frame Buffer Flags</title>
345 <tgroup cols="3">
346 &cs-def;
347 <tbody valign="top">
348 <row>
349 <entry><constant>V4L2_FBUF_FLAG_PRIMARY</constant></entry>
350 <entry>0x0001</entry>
351 <entry>The framebuffer is the primary graphics surface.
352In other words, the overlay is destructive. [?]</entry>
353 </row>
354 <row>
355 <entry><constant>V4L2_FBUF_FLAG_OVERLAY</constant></entry>
356 <entry>0x0002</entry>
357 <entry>The frame buffer is an overlay surface the same
358size as the capture. [?]</entry>
359 </row>
360 <row>
361 <entry spanname="hspan">The purpose of
362<constant>V4L2_FBUF_FLAG_PRIMARY</constant> and
363<constant>V4L2_FBUF_FLAG_OVERLAY</constant> was never quite clear.
364Most drivers seem to ignore these flags. For compatibility with the
365<wordasword>bttv</wordasword> driver applications should set the
366<constant>V4L2_FBUF_FLAG_OVERLAY</constant> flag.</entry>
367 </row>
368 <row>
369 <entry><constant>V4L2_FBUF_FLAG_CHROMAKEY</constant></entry>
370 <entry>0x0004</entry>
371 <entry>Use chroma-keying. The chroma-key color is
372determined by the <structfield>chromakey</structfield> field of
373&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
374 linkend="overlay" />
375and
376 <xref linkend="osd" />.</entry>
377 </row>
378 <row>
379 <entry spanname="hspan">There are no flags to enable
380clipping using a list of clip rectangles or a bitmap. These methods
381are negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
382 linkend="overlay" /> and <xref linkend="osd" />.</entry>
383 </row>
384 <row>
385 <entry><constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant></entry>
386 <entry>0x0008</entry>
387 <entry>Use the alpha channel of the framebuffer to clip or
388blend framebuffer pixels with video images. The blend
389function is: output = framebuffer pixel * alpha + video pixel * (1 -
390alpha). The actual alpha depth depends on the framebuffer pixel
391format.</entry>
392 </row>
393 <row>
394 <entry><constant>V4L2_FBUF_FLAG_GLOBAL_ALPHA</constant></entry>
395 <entry>0x0010</entry>
396 <entry>Use a global alpha value to blend the framebuffer
397with video images. The blend function is: output = (framebuffer pixel
398* alpha + video pixel * (255 - alpha)) / 255. The alpha value is
399determined by the <structfield>global_alpha</structfield> field of
400&v4l2-window; and negotiated with the &VIDIOC-S-FMT; ioctl, see <xref
401 linkend="overlay" />
402and <xref linkend="osd" />.</entry>
403 </row>
404 <row>
405 <entry><constant>V4L2_FBUF_FLAG_LOCAL_INV_ALPHA</constant></entry>
406 <entry>0x0020</entry>
407 <entry>Like
408<constant>V4L2_FBUF_FLAG_LOCAL_ALPHA</constant>, use the alpha channel
409of the framebuffer to clip or blend framebuffer pixels with video
410images, but with an inverted alpha value. The blend function is:
411output = framebuffer pixel * (1 - alpha) + video pixel * alpha. The
412actual alpha depth depends on the framebuffer pixel format.</entry>
413 </row>
414 </tbody>
415 </tgroup>
416 </table>
417 </refsect1>
418
419 <refsect1>
420 &return-value;
421
422 <variablelist>
423 <varlistentry>
424 <term><errorcode>EPERM</errorcode></term>
425 <listitem>
426 <para><constant>VIDIOC_S_FBUF</constant> can only be called
427by a privileged user to negotiate the parameters for a destructive
428overlay.</para>
429 </listitem>
430 </varlistentry>
431 <varlistentry>
432 <term><errorcode>EBUSY</errorcode></term>
433 <listitem>
434 <para>The framebuffer parameters cannot be changed at this
435time because overlay is already enabled, or capturing is enabled
436and the hardware cannot capture and overlay simultaneously.</para>
437 </listitem>
438 </varlistentry>
439 <varlistentry>
440 <term><errorcode>EINVAL</errorcode></term>
441 <listitem>
442 <para>The ioctl is not supported or the
443<constant>VIDIOC_S_FBUF</constant> parameters are unsuitable.</para>
444 </listitem>
445 </varlistentry>
446 </variablelist>
447 </refsect1>
448</refentry>
449
450<!--
451Local Variables:
452mode: sgml
453sgml-parent-document: "v4l2.sgml"
454indent-tabs-mode: nil
455End:
456-->
diff --git a/Documentation/DocBook/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/v4l/vidioc-g-fmt.xml
new file mode 100644
index 000000000000..7c7d1b72c40d
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-g-fmt.xml
@@ -0,0 +1,201 @@
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>. When the application
64calls the <constant>VIDIOC_G_FMT</constant> ioctl with a pointer to
65this structure the driver fills the respective member of the
66<structfield>fmt</structfield> union. In case of video capture devices
67that is the &v4l2-pix-format; <structfield>pix</structfield> member.
68When the requested buffer type is not supported drivers return an
69&EINVAL;.</para>
70
71 <para>To change the current format parameters applications
72initialize the <structfield>type</structfield> field and all
73fields of the respective <structfield>fmt</structfield>
74union member. For details see the documentation of the various devices
75types in <xref linkend="devices" />. Good practice is to query the
76current parameters first, and to
77modify only those parameters not suitable for the application. When
78the application calls the <constant>VIDIOC_S_FMT</constant> ioctl
79with a pointer to a <structname>v4l2_format</structname> structure
80the driver checks
81and adjusts the parameters against hardware abilities. Drivers
82should not return an error code unless the input is ambiguous, this is
83a mechanism to fathom device capabilities and to approach parameters
84acceptable for both the application and driver. On success the driver
85may program the hardware, allocate resources and generally prepare for
86data exchange.
87Finally the <constant>VIDIOC_S_FMT</constant> ioctl returns the
88current format parameters as <constant>VIDIOC_G_FMT</constant> does.
89Very simple, inflexible devices may even ignore all input and always
90return the default parameters. However all V4L2 devices exchanging
91data with the application must implement the
92<constant>VIDIOC_G_FMT</constant> and
93<constant>VIDIOC_S_FMT</constant> ioctl. When the requested buffer
94type is not supported drivers return an &EINVAL; on a
95<constant>VIDIOC_S_FMT</constant> attempt. When I/O is already in
96progress or the resource is not available for other reasons drivers
97return the &EBUSY;.</para>
98
99 <para>The <constant>VIDIOC_TRY_FMT</constant> ioctl is equivalent
100to <constant>VIDIOC_S_FMT</constant> with one exception: it does not
101change driver state. It can also be called at any time, never
102returning <errorcode>EBUSY</errorcode>. This function is provided to
103negotiate parameters, to learn about hardware limitations, without
104disabling I/O or possibly time consuming hardware preparations.
105Although strongly recommended drivers are not required to implement
106this ioctl.</para>
107
108 <table pgwide="1" frame="none" id="v4l2-format">
109 <title>struct <structname>v4l2_format</structname></title>
110 <tgroup cols="4">
111 <colspec colname="c1" />
112 <colspec colname="c2" />
113 <colspec colname="c3" />
114 <colspec colname="c4" />
115 <tbody valign="top">
116 <row>
117 <entry>&v4l2-buf-type;</entry>
118 <entry><structfield>type</structfield></entry>
119 <entry></entry>
120 <entry>Type of the data stream, see <xref
121 linkend="v4l2-buf-type" />.</entry>
122 </row>
123 <row>
124 <entry>union</entry>
125 <entry><structfield>fmt</structfield></entry>
126 </row>
127 <row>
128 <entry></entry>
129 <entry>&v4l2-pix-format;</entry>
130 <entry><structfield>pix</structfield></entry>
131 <entry>Definition of an image format, see <xref
132 linkend="pixfmt" />, used by video capture and output
133devices.</entry>
134 </row>
135 <row>
136 <entry></entry>
137 <entry>&v4l2-window;</entry>
138 <entry><structfield>win</structfield></entry>
139 <entry>Definition of an overlaid image, see <xref
140 linkend="overlay" />, used by video overlay devices.</entry>
141 </row>
142 <row>
143 <entry></entry>
144 <entry>&v4l2-vbi-format;</entry>
145 <entry><structfield>vbi</structfield></entry>
146 <entry>Raw VBI capture or output parameters. This is
147discussed in more detail in <xref linkend="raw-vbi" />. Used by raw VBI
148capture and output devices.</entry>
149 </row>
150 <row>
151 <entry></entry>
152 <entry>&v4l2-sliced-vbi-format;</entry>
153 <entry><structfield>sliced</structfield></entry>
154 <entry>Sliced VBI capture or output parameters. See
155<xref linkend="sliced" /> for details. Used by sliced VBI
156capture and output devices.</entry>
157 </row>
158 <row>
159 <entry></entry>
160 <entry>__u8</entry>
161 <entry><structfield>raw_data</structfield>[200]</entry>
162 <entry>Place holder for future extensions and custom
163(driver defined) formats with <structfield>type</structfield>
164<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry>
165 </row>
166 </tbody>
167 </tgroup>
168 </table>
169 </refsect1>
170
171 <refsect1>
172 &return-value;
173
174 <variablelist>
175 <varlistentry>
176 <term><errorcode>EBUSY</errorcode></term>
177 <listitem>
178 <para>The data format cannot be changed at this
179time, for example because I/O is already in progress.</para>
180 </listitem>
181 </varlistentry>
182 <varlistentry>
183 <term><errorcode>EINVAL</errorcode></term>
184 <listitem>
185 <para>The &v4l2-format; <structfield>type</structfield>
186field is invalid, the requested buffer type not supported, or
187<constant>VIDIOC_TRY_FMT</constant> was called and is not
188supported with this buffer type.</para>
189 </listitem>
190 </varlistentry>
191 </variablelist>
192 </refsect1>
193</refentry>
194
195<!--
196Local Variables:
197mode: sgml
198sgml-parent-document: "v4l2.sgml"
199indent-tabs-mode: nil
200End:
201-->
diff --git a/Documentation/DocBook/v4l/vidioc-g-frequency.xml b/Documentation/DocBook/v4l/vidioc-g-frequency.xml
new file mode 100644
index 000000000000..062d72069090
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-input.xml b/Documentation/DocBook/v4l/vidioc-g-input.xml
new file mode 100644
index 000000000000..ed076e92760d
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-jpegcomp.xml b/Documentation/DocBook/v4l/vidioc-g-jpegcomp.xml
new file mode 100644
index 000000000000..77394b287411
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-modulator.xml b/Documentation/DocBook/v4l/vidioc-g-modulator.xml
new file mode 100644
index 000000000000..15ce660f0f5a
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-output.xml b/Documentation/DocBook/v4l/vidioc-g-output.xml
new file mode 100644
index 000000000000..3ea8c0ed812e
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-parm.xml b/Documentation/DocBook/v4l/vidioc-g-parm.xml
new file mode 100644
index 000000000000..78332d365ce9
--- /dev/null
+++ b/Documentation/DocBook/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
58unneccessary 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/v4l/vidioc-g-priority.xml b/Documentation/DocBook/v4l/vidioc-g-priority.xml
new file mode 100644
index 000000000000..5fb001978645
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-sliced-vbi-cap.xml b/Documentation/DocBook/v4l/vidioc-g-sliced-vbi-cap.xml
new file mode 100644
index 000000000000..10e721b17374
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-g-std.xml b/Documentation/DocBook/v4l/vidioc-g-std.xml
new file mode 100644
index 000000000000..b6f5d267e856
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-g-std.xml
@@ -0,0 +1,99 @@
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 </variablelist>
90 </refsect1>
91</refentry>
92
93<!--
94Local Variables:
95mode: sgml
96sgml-parent-document: "v4l2.sgml"
97indent-tabs-mode: nil
98End:
99-->
diff --git a/Documentation/DocBook/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/v4l/vidioc-g-tuner.xml
new file mode 100644
index 000000000000..bd98c734c06b
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-log-status.xml b/Documentation/DocBook/v4l/vidioc-log-status.xml
new file mode 100644
index 000000000000..2634b7c88b58
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-overlay.xml b/Documentation/DocBook/v4l/vidioc-overlay.xml
new file mode 100644
index 000000000000..1036c582cc15
--- /dev/null
+++ b/Documentation/DocBook/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/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml
new file mode 100644
index 000000000000..187081778154
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml
@@ -0,0 +1,168 @@
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 <link linkend="mmap">memory mapped</link>
58buffer applications set the <structfield>type</structfield> field of a
59&v4l2-buffer; to the same buffer type as previously &v4l2-format;
60<structfield>type</structfield> and &v4l2-requestbuffers;
61<structfield>type</structfield>, the <structfield>memory</structfield>
62field to <constant>V4L2_MEMORY_MMAP</constant> and the
63<structfield>index</structfield> field. Valid index numbers range from
64zero to the number of buffers allocated with &VIDIOC-REQBUFS;
65(&v4l2-requestbuffers; <structfield>count</structfield>) minus one. The
66contents of the struct <structname>v4l2_buffer</structname> returned
67by a &VIDIOC-QUERYBUF; ioctl will do as well. When the buffer is
68intended for output (<structfield>type</structfield> is
69<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> or
70<constant>V4L2_BUF_TYPE_VBI_OUTPUT</constant>) applications must also
71initialize the <structfield>bytesused</structfield>,
72<structfield>field</structfield> and
73<structfield>timestamp</structfield> fields. See <xref
74 linkend="buffer" /> for details. When
75<constant>VIDIOC_QBUF</constant> is called with a pointer to this
76structure the driver sets the
77<constant>V4L2_BUF_FLAG_MAPPED</constant> and
78<constant>V4L2_BUF_FLAG_QUEUED</constant> flags and clears the
79<constant>V4L2_BUF_FLAG_DONE</constant> flag in the
80<structfield>flags</structfield> field, or it returns an
81&EINVAL;.</para>
82
83 <para>To enqueue a <link linkend="userp">user pointer</link>
84buffer applications set the <structfield>type</structfield> field of a
85&v4l2-buffer; to the same buffer type as previously &v4l2-format;
86<structfield>type</structfield> and &v4l2-requestbuffers;
87<structfield>type</structfield>, the <structfield>memory</structfield>
88field to <constant>V4L2_MEMORY_USERPTR</constant> and the
89<structfield>m.userptr</structfield> field to the address of the
90buffer and <structfield>length</structfield> to its size. When the
91buffer is intended for output additional fields must be set as above.
92When <constant>VIDIOC_QBUF</constant> is called with a pointer to this
93structure the driver sets the <constant>V4L2_BUF_FLAG_QUEUED</constant>
94flag and clears the <constant>V4L2_BUF_FLAG_MAPPED</constant> and
95<constant>V4L2_BUF_FLAG_DONE</constant> flags in the
96<structfield>flags</structfield> field, or it returns an error code.
97This ioctl locks the memory pages of the buffer in physical memory,
98they cannot be swapped out to disk. Buffers remain locked until
99dequeued, until the &VIDIOC-STREAMOFF; or &VIDIOC-REQBUFS; ioctl are
100called, or until the device is closed.</para>
101
102 <para>Applications call the <constant>VIDIOC_DQBUF</constant>
103ioctl to dequeue a filled (capturing) or displayed (output) buffer
104from the driver's outgoing queue. They just set the
105<structfield>type</structfield> and <structfield>memory</structfield>
106fields of a &v4l2-buffer; as above, when <constant>VIDIOC_DQBUF</constant>
107is called with a pointer to this structure the driver fills the
108remaining fields or returns an error code.</para>
109
110 <para>By default <constant>VIDIOC_DQBUF</constant> blocks when no
111buffer is in the outgoing queue. When the
112<constant>O_NONBLOCK</constant> flag was given to the &func-open;
113function, <constant>VIDIOC_DQBUF</constant> returns immediately
114with an &EAGAIN; when no buffer is available.</para>
115
116 <para>The <structname>v4l2_buffer</structname> structure is
117specified in <xref linkend="buffer" />.</para>
118 </refsect1>
119
120 <refsect1>
121 &return-value;
122
123 <variablelist>
124 <varlistentry>
125 <term><errorcode>EAGAIN</errorcode></term>
126 <listitem>
127 <para>Non-blocking I/O has been selected using
128<constant>O_NONBLOCK</constant> and no buffer was in the outgoing
129queue.</para>
130 </listitem>
131 </varlistentry>
132 <varlistentry>
133 <term><errorcode>EINVAL</errorcode></term>
134 <listitem>
135 <para>The buffer <structfield>type</structfield> is not
136supported, or the <structfield>index</structfield> is out of bounds,
137or no buffers have been allocated yet, or the
138<structfield>userptr</structfield> or
139<structfield>length</structfield> are invalid.</para>
140 </listitem>
141 </varlistentry>
142 <varlistentry>
143 <term><errorcode>ENOMEM</errorcode></term>
144 <listitem>
145 <para>Not enough physical or virtual memory was available to
146enqueue a user pointer buffer.</para>
147 </listitem>
148 </varlistentry>
149 <varlistentry>
150 <term><errorcode>EIO</errorcode></term>
151 <listitem>
152 <para><constant>VIDIOC_DQBUF</constant> failed due to an
153internal error. Can also indicate temporary problems like signal
154loss. Note the driver might dequeue an (empty) buffer despite
155returning an error, or even stop capturing.</para>
156 </listitem>
157 </varlistentry>
158 </variablelist>
159 </refsect1>
160</refentry>
161
162<!--
163Local Variables:
164mode: sgml
165sgml-parent-document: "v4l2.sgml"
166indent-tabs-mode: nil
167End:
168-->
diff --git a/Documentation/DocBook/v4l/vidioc-querybuf.xml b/Documentation/DocBook/v4l/vidioc-querybuf.xml
new file mode 100644
index 000000000000..d834993e6191
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-querybuf.xml
@@ -0,0 +1,103 @@
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 previously
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.
63After calling <constant>VIDIOC_QUERYBUF</constant> with a pointer to
64 this structure drivers return an error code or fill the rest of
65the structure.</para>
66
67 <para>In the <structfield>flags</structfield> field the
68<constant>V4L2_BUF_FLAG_MAPPED</constant>,
69<constant>V4L2_BUF_FLAG_QUEUED</constant> and
70<constant>V4L2_BUF_FLAG_DONE</constant> flags will be valid. The
71<structfield>memory</structfield> field will be set to
72<constant>V4L2_MEMORY_MMAP</constant>, the <structfield>m.offset</structfield>
73contains the offset of the buffer from the start of the device memory,
74the <structfield>length</structfield> field its size. The driver may
75or may not set the remaining fields and flags, they are meaningless in
76this context.</para>
77
78 <para>The <structname>v4l2_buffer</structname> structure is
79 specified in <xref linkend="buffer" />.</para>
80 </refsect1>
81
82 <refsect1>
83 &return-value;
84
85 <variablelist>
86 <varlistentry>
87 <term><errorcode>EINVAL</errorcode></term>
88 <listitem>
89 <para>The buffer <structfield>type</structfield> is not
90supported, or the <structfield>index</structfield> is out of bounds.</para>
91 </listitem>
92 </varlistentry>
93 </variablelist>
94 </refsect1>
95</refentry>
96
97<!--
98Local Variables:
99mode: sgml
100sgml-parent-document: "v4l2.sgml"
101indent-tabs-mode: nil
102End:
103-->
diff --git a/Documentation/DocBook/v4l/vidioc-querycap.xml b/Documentation/DocBook/v4l/vidioc-querycap.xml
new file mode 100644
index 000000000000..6ab7e25b31b6
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-querycap.xml
@@ -0,0 +1,284 @@
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 <link
146linkend="capture">Video Capture</link> interface.</entry>
147 </row>
148 <row>
149 <entry><constant>V4L2_CAP_VIDEO_OUTPUT</constant></entry>
150 <entry>0x00000002</entry>
151 <entry>The device supports the <link
152linkend="output">Video Output</link> interface.</entry>
153 </row>
154 <row>
155 <entry><constant>V4L2_CAP_VIDEO_OVERLAY</constant></entry>
156 <entry>0x00000004</entry>
157 <entry>The device supports the <link
158linkend="overlay">Video Overlay</link> interface. A video overlay device
159typically stores captured images directly in the video memory of a
160graphics card, with hardware clipping and scaling.</entry>
161 </row>
162 <row>
163 <entry><constant>V4L2_CAP_VBI_CAPTURE</constant></entry>
164 <entry>0x00000010</entry>
165 <entry>The device supports the <link linkend="raw-vbi">Raw
166VBI Capture</link> interface, providing Teletext and Closed Caption
167data.</entry>
168 </row>
169 <row>
170 <entry><constant>V4L2_CAP_VBI_OUTPUT</constant></entry>
171 <entry>0x00000020</entry>
172 <entry>The device supports the <link linkend="raw-vbi">Raw VBI Output</link> interface.</entry>
173 </row>
174 <row>
175 <entry><constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant></entry>
176 <entry>0x00000040</entry>
177 <entry>The device supports the <link linkend="sliced">Sliced VBI Capture</link> interface.</entry>
178 </row>
179 <row>
180 <entry><constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant></entry>
181 <entry>0x00000080</entry>
182 <entry>The device supports the <link linkend="sliced">Sliced VBI Output</link> interface.</entry>
183 </row>
184 <row>
185 <entry><constant>V4L2_CAP_RDS_CAPTURE</constant></entry>
186 <entry>0x00000100</entry>
187 <entry>The device supports the <link linkend="rds">RDS</link> interface.</entry>
188 </row>
189 <row>
190 <entry><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant></entry>
191 <entry>0x00000200</entry>
192 <entry>The device supports the <link linkend="osd">Video
193Output Overlay</link> (OSD) interface. Unlike the <wordasword>Video
194Overlay</wordasword> interface, this is a secondary function of video
195output devices and overlays an image onto an outgoing video signal.
196When the driver sets this flag, it must clear the
197<constant>V4L2_CAP_VIDEO_OVERLAY</constant> flag and vice
198versa.<footnote><para>The &v4l2-framebuffer; lacks an
199&v4l2-buf-type; field, therefore the type of overlay is implied by the
200driver capabilities.</para></footnote></entry>
201 </row>
202 <row>
203 <entry><constant>V4L2_CAP_HW_FREQ_SEEK</constant></entry>
204 <entry>0x00000400</entry>
205 <entry>The device supports the &VIDIOC-S-HW-FREQ-SEEK; ioctl for
206hardware frequency seeking.</entry>
207 </row>
208 <row>
209 <entry><constant>V4L2_CAP_TUNER</constant></entry>
210 <entry>0x00010000</entry>
211 <entry>The device has some sort of tuner to
212receive RF-modulated video signals. For more information about
213tuner programming see
214<xref linkend="tuner" />.</entry>
215 </row>
216 <row>
217 <entry><constant>V4L2_CAP_AUDIO</constant></entry>
218 <entry>0x00020000</entry>
219 <entry>The device has audio inputs or outputs. It may or
220may not support audio recording or playback, in PCM or compressed
221formats. PCM audio support must be implemented as ALSA or OSS
222interface. For more information on audio inputs and outputs see <xref
223 linkend="audio" />.</entry>
224 </row>
225 <row>
226 <entry><constant>V4L2_CAP_RADIO</constant></entry>
227 <entry>0x00040000</entry>
228 <entry>This is a radio receiver.</entry>
229 </row>
230 <row>
231 <entry><constant>V4L2_CAP_MODULATOR</constant></entry>
232 <entry>0x00080000</entry>
233 <entry>The device has some sort of modulator to
234emit RF-modulated video/audio signals. For more information about
235modulator programming see
236<xref linkend="tuner" />.</entry>
237 </row>
238 <row>
239 <entry><constant>V4L2_CAP_READWRITE</constant></entry>
240 <entry>0x01000000</entry>
241 <entry>The device supports the <link
242linkend="rw">read()</link> and/or <link linkend="rw">write()</link>
243I/O methods.</entry>
244 </row>
245 <row>
246 <entry><constant>V4L2_CAP_ASYNCIO</constant></entry>
247 <entry>0x02000000</entry>
248 <entry>The device supports the <link
249linkend="async">asynchronous</link> I/O methods.</entry>
250 </row>
251 <row>
252 <entry><constant>V4L2_CAP_STREAMING</constant></entry>
253 <entry>0x04000000</entry>
254 <entry>The device supports the <link
255linkend="mmap">streaming</link> I/O method.</entry>
256 </row>
257 </tbody>
258 </tgroup>
259 </table>
260 </refsect1>
261
262 <refsect1>
263 &return-value;
264
265 <variablelist>
266 <varlistentry>
267 <term><errorcode>EINVAL</errorcode></term>
268 <listitem>
269 <para>The device is not compatible with this
270specification.</para>
271 </listitem>
272 </varlistentry>
273 </variablelist>
274 </refsect1>
275</refentry>
276
277<!--
278Local Variables:
279mode: sgml
280sgml-parent-document: "v4l2.sgml"
281indent-tabs-mode: nil
282End:
283-->
284
diff --git a/Documentation/DocBook/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/v4l/vidioc-queryctrl.xml
new file mode 100644
index 000000000000..4876ff1a1a04
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-queryctrl.xml
@@ -0,0 +1,428 @@
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> (0) to
107<structfield>maximum</structfield>, inclusive.</para>
108
109 <para>See also the examples in <xref linkend="control" />.</para>
110
111 <table pgwide="1" frame="none" id="v4l2-queryctrl">
112 <title>struct <structname>v4l2_queryctrl</structname></title>
113 <tgroup cols="3">
114 &cs-str;
115 <tbody valign="top">
116 <row>
117 <entry>__u32</entry>
118 <entry><structfield>id</structfield></entry>
119 <entry>Identifies the control, set by the application. See
120<xref linkend="control-id" /> for predefined IDs. When the ID is ORed
121with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and returns
122the first control with a higher ID. Drivers which do not support this
123flag yet always return an &EINVAL;.</entry>
124 </row>
125 <row>
126 <entry>&v4l2-ctrl-type;</entry>
127 <entry><structfield>type</structfield></entry>
128 <entry>Type of control, see <xref
129 linkend="v4l2-ctrl-type" />.</entry>
130 </row>
131 <row>
132 <entry>__u8</entry>
133 <entry><structfield>name</structfield>[32]</entry>
134 <entry>Name of the control, a NUL-terminated ASCII
135string. This information is intended for the user.</entry>
136 </row>
137 <row>
138 <entry>__s32</entry>
139 <entry><structfield>minimum</structfield></entry>
140 <entry>Minimum value, inclusive. This field gives a lower
141bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
142lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls.
143For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value
144gives the minimum length of the string. This length <emphasis>does not include the terminating
145zero</emphasis>. It may not be valid for any other type of control, including
146<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
147signed value.</entry>
148 </row>
149 <row>
150 <entry>__s32</entry>
151 <entry><structfield>maximum</structfield></entry>
152 <entry>Maximum value, inclusive. This field gives an upper
153bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
154highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant>
155controls.
156For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value
157gives the maximum length of the string. This length <emphasis>does not include the terminating
158zero</emphasis>. It may not be valid for any other type of control, including
159<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
160signed value.</entry>
161 </row>
162 <row>
163 <entry>__s32</entry>
164 <entry><structfield>step</structfield></entry>
165 <entry><para>This field gives a step size for
166<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For
167<constant>V4L2_CTRL_TYPE_STRING</constant> controls this field refers to
168the string length that has to be a multiple of this step size.
169It may not be valid for any other type of control, including
170<constant>V4L2_CTRL_TYPE_INTEGER64</constant>
171controls.</para><para>Generally drivers should not scale hardware
172control values. It may be necessary for example when the
173<structfield>name</structfield> or <structfield>id</structfield> imply
174a particular unit and the hardware actually accepts only multiples of
175said unit. If so, drivers must take care values are properly rounded
176when scaling, such that errors will not accumulate on repeated
177read-write cycles.</para><para>This field gives the smallest change of
178an integer control actually affecting hardware. Often the information
179is needed when the user can change controls by keyboard or GUI
180buttons, rather than a slider. When for example a hardware register
181accepts values 0-511 and the driver reports 0-65535, step should be
182128.</para><para>Note that although signed, the step value is supposed to
183be always positive.</para></entry>
184 </row>
185 <row>
186 <entry>__s32</entry>
187 <entry><structfield>default_value</structfield></entry>
188 <entry>The default value of a
189<constant>V4L2_CTRL_TYPE_INTEGER</constant>,
190<constant>_BOOLEAN</constant> or <constant>_MENU</constant> control.
191Not valid for other types of controls. Drivers reset controls only
192when the driver is loaded, not later, in particular not when the
193func-open; is called.</entry>
194 </row>
195 <row>
196 <entry>__u32</entry>
197 <entry><structfield>flags</structfield></entry>
198 <entry>Control flags, see <xref
199 linkend="control-flags" />.</entry>
200 </row>
201 <row>
202 <entry>__u32</entry>
203 <entry><structfield>reserved</structfield>[2]</entry>
204 <entry>Reserved for future extensions. Drivers must set
205the array to zero.</entry>
206 </row>
207 </tbody>
208 </tgroup>
209 </table>
210
211 <table pgwide="1" frame="none" id="v4l2-querymenu">
212 <title>struct <structname>v4l2_querymenu</structname></title>
213 <tgroup cols="3">
214 &cs-str;
215 <tbody valign="top">
216 <row>
217 <entry>__u32</entry>
218 <entry><structfield>id</structfield></entry>
219 <entry>Identifies the control, set by the application
220from the respective &v4l2-queryctrl;
221<structfield>id</structfield>.</entry>
222 </row>
223 <row>
224 <entry>__u32</entry>
225 <entry><structfield>index</structfield></entry>
226 <entry>Index of the menu item, starting at zero, set by
227 the application.</entry>
228 </row>
229 <row>
230 <entry>__u8</entry>
231 <entry><structfield>name</structfield>[32]</entry>
232 <entry>Name of the menu item, a NUL-terminated ASCII
233string. This information is intended for the user.</entry>
234 </row>
235 <row>
236 <entry>__u32</entry>
237 <entry><structfield>reserved</structfield></entry>
238 <entry>Reserved for future extensions. Drivers must set
239the array to zero.</entry>
240 </row>
241 </tbody>
242 </tgroup>
243 </table>
244
245 <table pgwide="1" frame="none" id="v4l2-ctrl-type">
246 <title>enum v4l2_ctrl_type</title>
247 <tgroup cols="5" align="left">
248 <colspec colwidth="30*" />
249 <colspec colwidth="5*" align="center" />
250 <colspec colwidth="5*" align="center" />
251 <colspec colwidth="5*" align="center" />
252 <colspec colwidth="55*" />
253 <thead>
254 <row>
255 <entry>Type</entry>
256 <entry><structfield>minimum</structfield></entry>
257 <entry><structfield>step</structfield></entry>
258 <entry><structfield>maximum</structfield></entry>
259 <entry>Description</entry>
260 </row>
261 </thead>
262 <tbody valign="top">
263 <row>
264 <entry><constant>V4L2_CTRL_TYPE_INTEGER</constant></entry>
265 <entry>any</entry>
266 <entry>any</entry>
267 <entry>any</entry>
268 <entry>An integer-valued control ranging from minimum to
269maximum inclusive. The step value indicates the increment between
270values which are actually different on the hardware.</entry>
271 </row>
272 <row>
273 <entry><constant>V4L2_CTRL_TYPE_BOOLEAN</constant></entry>
274 <entry>0</entry>
275 <entry>1</entry>
276 <entry>1</entry>
277 <entry>A boolean-valued control. Zero corresponds to
278"disabled", and one means "enabled".</entry>
279 </row>
280 <row>
281 <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry>
282 <entry>0</entry>
283 <entry>1</entry>
284 <entry>N-1</entry>
285 <entry>The control has a menu of N choices. The names of
286the menu items can be enumerated with the
287<constant>VIDIOC_QUERYMENU</constant> ioctl.</entry>
288 </row>
289 <row>
290 <entry><constant>V4L2_CTRL_TYPE_BUTTON</constant></entry>
291 <entry>0</entry>
292 <entry>0</entry>
293 <entry>0</entry>
294 <entry>A control which performs an action when set.
295Drivers must ignore the value passed with
296<constant>VIDIOC_S_CTRL</constant> and return an &EINVAL; on a
297<constant>VIDIOC_G_CTRL</constant> attempt.</entry>
298 </row>
299 <row>
300 <entry><constant>V4L2_CTRL_TYPE_INTEGER64</constant></entry>
301 <entry>n/a</entry>
302 <entry>n/a</entry>
303 <entry>n/a</entry>
304 <entry>A 64-bit integer valued control. Minimum, maximum
305and step size cannot be queried.</entry>
306 </row>
307 <row>
308 <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
309 <entry>&ge; 0</entry>
310 <entry>&ge; 1</entry>
311 <entry>&ge; 0</entry>
312 <entry>The minimum and maximum string lengths. The step size
313means that the string must be (minimum + N * step) characters long for
314N &ge; 0. These lengths do not include the terminating zero, so in order to
315pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the
316<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can
317set the <structfield>size</structfield> field to <structfield>maximum</structfield> + 1.
318Which character encoding is used will depend on the string control itself and
319should be part of the control documentation.</entry>
320 </row>
321 <row>
322 <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry>
323 <entry>n/a</entry>
324 <entry>n/a</entry>
325 <entry>n/a</entry>
326 <entry>This is not a control. When
327<constant>VIDIOC_QUERYCTRL</constant> is called with a control ID
328equal to a control class code (see <xref linkend="ctrl-class" />), the
329ioctl returns the name of the control class and this control type.
330Older drivers which do not support this feature return an
331&EINVAL;.</entry>
332 </row>
333 </tbody>
334 </tgroup>
335 </table>
336
337 <table pgwide="1" frame="none" id="control-flags">
338 <title>Control Flags</title>
339 <tgroup cols="3">
340 &cs-def;
341 <tbody valign="top">
342 <row>
343 <entry><constant>V4L2_CTRL_FLAG_DISABLED</constant></entry>
344 <entry>0x0001</entry>
345 <entry>This control is permanently disabled and should be
346ignored by the application. Any attempt to change the control will
347result in an &EINVAL;.</entry>
348 </row>
349 <row>
350 <entry><constant>V4L2_CTRL_FLAG_GRABBED</constant></entry>
351 <entry>0x0002</entry>
352 <entry>This control is temporarily unchangeable, for
353example because another application took over control of the
354respective resource. Such controls may be displayed specially in a
355user interface. Attempts to change the control may result in an
356&EBUSY;.</entry>
357 </row>
358 <row>
359 <entry><constant>V4L2_CTRL_FLAG_READ_ONLY</constant></entry>
360 <entry>0x0004</entry>
361 <entry>This control is permanently readable only. Any
362attempt to change the control will result in an &EINVAL;.</entry>
363 </row>
364 <row>
365 <entry><constant>V4L2_CTRL_FLAG_UPDATE</constant></entry>
366 <entry>0x0008</entry>
367 <entry>A hint that changing this control may affect the
368value of other controls within the same control class. Applications
369should update their user interface accordingly.</entry>
370 </row>
371 <row>
372 <entry><constant>V4L2_CTRL_FLAG_INACTIVE</constant></entry>
373 <entry>0x0010</entry>
374 <entry>This control is not applicable to the current
375configuration and should be displayed accordingly in a user interface.
376For example the flag may be set on a MPEG audio level 2 bitrate
377control when MPEG audio encoding level 1 was selected with another
378control.</entry>
379 </row>
380 <row>
381 <entry><constant>V4L2_CTRL_FLAG_SLIDER</constant></entry>
382 <entry>0x0020</entry>
383 <entry>A hint that this control is best represented as a
384slider-like element in a user interface.</entry>
385 </row>
386 <row>
387 <entry><constant>V4L2_CTRL_FLAG_WRITE_ONLY</constant></entry>
388 <entry>0x0040</entry>
389 <entry>This control is permanently writable only. Any
390attempt to read the control will result in an &EACCES; error code. This
391flag is typically present for relative controls or action controls where
392writing a value will cause the device to carry out a given action
393(&eg; motor control) but no meaningful value can be returned.</entry>
394 </row>
395 </tbody>
396 </tgroup>
397 </table>
398 </refsect1>
399
400 <refsect1>
401 &return-value;
402
403 <variablelist>
404 <varlistentry>
405 <term><errorcode>EINVAL</errorcode></term>
406 <listitem>
407 <para>The &v4l2-queryctrl; <structfield>id</structfield>
408is invalid. The &v4l2-querymenu; <structfield>id</structfield> or
409<structfield>index</structfield> is invalid.</para>
410 </listitem>
411 </varlistentry>
412 <varlistentry>
413 <term><errorcode>EACCES</errorcode></term>
414 <listitem>
415 <para>An attempt was made to read a write-only control.</para>
416 </listitem>
417 </varlistentry>
418 </variablelist>
419 </refsect1>
420</refentry>
421
422<!--
423Local Variables:
424mode: sgml
425sgml-parent-document: "v4l2.sgml"
426indent-tabs-mode: nil
427End:
428-->
diff --git a/Documentation/DocBook/v4l/vidioc-querystd.xml b/Documentation/DocBook/v4l/vidioc-querystd.xml
new file mode 100644
index 000000000000..b5a7ff934486
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-querystd.xml
@@ -0,0 +1,83 @@
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 </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/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/v4l/vidioc-reqbufs.xml
new file mode 100644
index 000000000000..bab38084454f
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-reqbufs.xml
@@ -0,0 +1,160 @@
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.</para>
58
59 <para>To allocate device buffers applications initialize three
60fields of a <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, and <structfield>memory</structfield>
64must be set to <constant>V4L2_MEMORY_MMAP</constant>. When the ioctl
65is called with a pointer to this structure the driver attempts to
66allocate the requested number of buffers and stores the actual number
67allocated in the <structfield>count</structfield> field. It can be
68smaller than the number requested, even zero, when the driver runs out
69of free memory. A larger number is possible when the driver requires
70more buffers to function correctly.<footnote>
71 <para>For example video output requires at least two buffers,
72one displayed and one filled by the application.</para>
73 </footnote> When memory mapping I/O 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 <para>To negotiate user pointer I/O, applications initialize only
85the <structfield>type</structfield> field and set
86<structfield>memory</structfield> to
87<constant>V4L2_MEMORY_USERPTR</constant>. When the ioctl is called
88with a pointer to this structure the driver prepares for user pointer
89I/O, when this I/O method is not supported the ioctl returns an
90&EINVAL;.</para>
91
92 <table pgwide="1" frame="none" id="v4l2-requestbuffers">
93 <title>struct <structname>v4l2_requestbuffers</structname></title>
94 <tgroup cols="3">
95 &cs-str;
96 <tbody valign="top">
97 <row>
98 <entry>__u32</entry>
99 <entry><structfield>count</structfield></entry>
100 <entry>The number of buffers requested or granted. This
101field is only used when <structfield>memory</structfield> is set to
102<constant>V4L2_MEMORY_MMAP</constant>.</entry>
103 </row>
104 <row>
105 <entry>&v4l2-buf-type;</entry>
106 <entry><structfield>type</structfield></entry>
107 <entry>Type of the stream or buffers, this is the same
108as the &v4l2-format; <structfield>type</structfield> field. See <xref
109 linkend="v4l2-buf-type" /> for valid values.</entry>
110 </row>
111 <row>
112 <entry>&v4l2-memory;</entry>
113 <entry><structfield>memory</structfield></entry>
114 <entry>Applications set this field to
115<constant>V4L2_MEMORY_MMAP</constant> or
116<constant>V4L2_MEMORY_USERPTR</constant>.</entry>
117 </row>
118 <row>
119 <entry>__u32</entry>
120 <entry><structfield>reserved</structfield>[2]</entry>
121 <entry>A place holder for future extensions and custom
122(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and
123higher.</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 driver supports multiple opens and I/O is already
138in progress, or reallocation of buffers was attempted although one or
139more are still mapped.</para>
140 </listitem>
141 </varlistentry>
142 <varlistentry>
143 <term><errorcode>EINVAL</errorcode></term>
144 <listitem>
145 <para>The buffer type (<structfield>type</structfield> field) or the
146requested I/O method (<structfield>memory</structfield>) is not
147supported.</para>
148 </listitem>
149 </varlistentry>
150 </variablelist>
151 </refsect1>
152</refentry>
153
154<!--
155Local Variables:
156mode: sgml
157sgml-parent-document: "v4l2.sgml"
158indent-tabs-mode: nil
159End:
160-->
diff --git a/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml
new file mode 100644
index 000000000000..14b3ec7ed75b
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-s-hw-freq-seek.xml
@@ -0,0 +1,129 @@
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> and
55<structfield>wrap_around</structfield> fields, and zero out the
56<structfield>reserved</structfield> array of a &v4l2-hw-freq-seek; and
57call the <constant>VIDIOC_S_HW_FREQ_SEEK</constant> ioctl with a pointer
58to this structure.</para>
59
60 <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para>
61
62 <table pgwide="1" frame="none" id="v4l2-hw-freq-seek">
63 <title>struct <structname>v4l2_hw_freq_seek</structname></title>
64 <tgroup cols="3">
65 &cs-str;
66 <tbody valign="top">
67 <row>
68 <entry>__u32</entry>
69 <entry><structfield>tuner</structfield></entry>
70 <entry>The tuner index number. This is the
71same value as in the &v4l2-input; <structfield>tuner</structfield>
72field and the &v4l2-tuner; <structfield>index</structfield> field.</entry>
73 </row>
74 <row>
75 <entry>&v4l2-tuner-type;</entry>
76 <entry><structfield>type</structfield></entry>
77 <entry>The tuner type. This is the same value as in the
78&v4l2-tuner; <structfield>type</structfield> field.</entry>
79 </row>
80 <row>
81 <entry>__u32</entry>
82 <entry><structfield>seek_upward</structfield></entry>
83 <entry>If non-zero, seek upward from the current frequency, else seek downward.</entry>
84 </row>
85 <row>
86 <entry>__u32</entry>
87 <entry><structfield>wrap_around</structfield></entry>
88 <entry>If non-zero, wrap around when at the end of the frequency range, else stop seeking.</entry>
89 </row>
90 <row>
91 <entry>__u32</entry>
92 <entry><structfield>reserved</structfield>[8]</entry>
93 <entry>Reserved for future extensions. Drivers and
94 applications must set the array to zero.</entry>
95 </row>
96 </tbody>
97 </tgroup>
98 </table>
99 </refsect1>
100
101 <refsect1>
102 &return-value;
103
104 <variablelist>
105 <varlistentry>
106 <term><errorcode>EINVAL</errorcode></term>
107 <listitem>
108 <para>The <structfield>tuner</structfield> index is out of
109bounds or the value in the <structfield>type</structfield> field is
110wrong.</para>
111 </listitem>
112 </varlistentry>
113 <varlistentry>
114 <term><errorcode>EAGAIN</errorcode></term>
115 <listitem>
116 <para>The ioctl timed-out. Try again.</para>
117 </listitem>
118 </varlistentry>
119 </variablelist>
120 </refsect1>
121</refentry>
122
123<!--
124Local Variables:
125mode: sgml
126sgml-parent-document: "v4l2.sgml"
127indent-tabs-mode: nil
128End:
129-->
diff --git a/Documentation/DocBook/v4l/vidioc-streamon.xml b/Documentation/DocBook/v4l/vidioc-streamon.xml
new file mode 100644
index 000000000000..e42bff1f2c0a
--- /dev/null
+++ b/Documentation/DocBook/v4l/vidioc-streamon.xml
@@ -0,0 +1,106 @@
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 </variablelist>
97 </refsect1>
98</refentry>
99
100<!--
101Local Variables:
102mode: sgml
103sgml-parent-document: "v4l2.sgml"
104indent-tabs-mode: nil
105End:
106-->