aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHans Verkuil <hans.verkuil@cisco.com>2012-05-15 07:04:28 -0400
committerMauro Carvalho Chehab <mchehab@redhat.com>2012-05-20 07:18:03 -0400
commit7dcc606b2a980222d9816d092a5c20b7c98cbd1a (patch)
treecf1ca07dbab8a0fb9a6e73963367310039e5c3a0
parent06bba75d2a3e0bf558421b7548a6248ed5c7bfec (diff)
[media] V4L2 spec: document the new V4L2 DV timings ioctls
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com> Reviewed-by: Mauro Carvalho Chehab <mchehab@redhat.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Diffstat
-rw-r--r--Documentation/DocBook/media/v4l/biblio.xml18
-rw-r--r--Documentation/DocBook/media/v4l/common.xml32
-rw-r--r--Documentation/DocBook/media/v4l/compat.xml13
-rw-r--r--Documentation/DocBook/media/v4l/v4l2.xml15
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-create-bufs.xml6
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml211
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml4
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml119
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enuminput.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-enumoutput.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml130
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml6
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml104
13 files changed, 633 insertions, 29 deletions
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml
index 66a0ef251c79..7c49facecd25 100644
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ b/Documentation/DocBook/media/v4l/biblio.xml
@@ -208,4 +208,22 @@ in the frequency range from 87,5 to 108,0 MHz</title>
208 recommended exposure index</title> 208 recommended exposure index</title>
209 </biblioentry> 209 </biblioentry>
210 210
211 <biblioentry id="cea861">
212 <abbrev>CEA-861-E</abbrev>
213 <authorgroup>
214 <corpauthor>Consumer Electronics Association
215(<ulink url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor>
216 </authorgroup>
217 <title>A DTV Profile for Uncompressed High Speed Digital Interfaces</title>
218 </biblioentry>
219
220 <biblioentry id="vesadmt">
221 <abbrev>VESA&nbsp;DMT</abbrev>
222 <authorgroup>
223 <corpauthor>Video Electronics Standards Association
224(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor>
225 </authorgroup>
226 <title>VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)</title>
227 </biblioentry>
228
211 </bibliography> 229 </bibliography>
diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
index c79278acfb0e..81b7cf384a39 100644
--- a/Documentation/DocBook/media/v4l/common.xml
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -724,41 +724,47 @@ if (-1 == ioctl (fd, &VIDIOC-S-STD;, &amp;std_id)) {
724} 724}
725 </programlisting> 725 </programlisting>
726 </example> 726 </example>
727 </section>
727 <section id="dv-timings"> 728 <section id="dv-timings">
728 <title>Digital Video (DV) Timings</title> 729 <title>Digital Video (DV) Timings</title>
729 <para> 730 <para>
730 The video standards discussed so far has been dealing with Analog TV and the 731 The video standards discussed so far have been dealing with Analog TV and the
731corresponding video timings. Today there are many more different hardware interfaces 732corresponding video timings. Today there are many more different hardware interfaces
732such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry 733such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry
733video signals and there is a need to extend the API to select the video timings 734video signals and there is a need to extend the API to select the video timings
734for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to 735for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to
735the limited bits available, a new set of IOCTLs is added to set/get video timings at 736the limited bits available, a new set of IOCTLs was added to set/get video timings at
736the input and output: </para><itemizedlist> 737the input and output: </para><itemizedlist>
737 <listitem> 738 <listitem>
739 <para>DV Timings: This will allow applications to define detailed
740video timings for the interface. This includes parameters such as width, height,
741polarities, frontporch, backporch etc. The <filename>linux/v4l2-dv-timings.h</filename>
742header can be used to get the timings of the formats in the <xref linkend="cea861" /> and
743<xref linkend="vesadmt" /> standards.
744 </para>
745 </listitem>
746 <listitem>
738 <para>DV Presets: Digital Video (DV) presets. These are IDs representing a 747 <para>DV Presets: Digital Video (DV) presets. These are IDs representing a
739video timing at the input/output. Presets are pre-defined timings implemented 748video timing at the input/output. Presets are pre-defined timings implemented
740by the hardware according to video standards. A __u32 data type is used to represent 749by the hardware according to video standards. A __u32 data type is used to represent
741a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions 750a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
742to support as many different presets as needed.</para> 751to support as many different presets as needed.</para>
743 </listitem> 752 </listitem>
744 <listitem>
745 <para>Custom DV Timings: This will allow applications to define more detailed
746custom video timings for the interface. This includes parameters such as width, height,
747polarities, frontporch, backporch etc.
748 </para>
749 </listitem>
750 </itemizedlist> 753 </itemizedlist>
754 <para>To enumerate and query the attributes of the DV timings supported by a device,
755 applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls.
756 To set DV timings for the device, applications use the
757&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the
758&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications
759use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para>
751 <para>To enumerate and query the attributes of DV presets supported by a device, 760 <para>To enumerate and query the attributes of DV presets supported by a device,
752applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset, 761applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset,
753applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the 762applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the
754&VIDIOC-S-DV-PRESET; ioctl.</para> 763&VIDIOC-S-DV-PRESET; ioctl. To detect the preset as seen by the video receiver applications
755 <para>To set custom DV timings for the device, applications use the 764use the &VIDIOC-QUERY-DV-PRESET; ioctl.</para>
756&VIDIOC-S-DV-TIMINGS; ioctl and to get current custom DV timings they use the
757&VIDIOC-G-DV-TIMINGS; ioctl.</para>
758 <para>Applications can make use of the <xref linkend="input-capabilities" /> and 765 <para>Applications can make use of the <xref linkend="input-capabilities" /> and
759<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the 766<xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the
760video timings for the device.</para> 767video timings for the device.</para>
761 </section>
762 </section> 768 </section>
763 769
764 &sub-controls; 770 &sub-controls;
diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index dc61b013b8a8..cd19d21085db 100644
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2407,6 +2407,11 @@ details.</para>
2407 <para>Added <link linkend="jpeg-controls">JPEG compression control 2407 <para>Added <link linkend="jpeg-controls">JPEG compression control
2408 class</link>.</para> 2408 class</link>.</para>
2409 </listitem> 2409 </listitem>
2410 <listitem>
2411 <para>Extended the DV Timings API:
2412 &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
2413 &VIDIOC-DV-TIMINGS-CAP;.</para>
2414 </listitem>
2410 </orderedlist> 2415 </orderedlist>
2411 </section> 2416 </section>
2412 2417
@@ -2551,6 +2556,10 @@ and may change in the future.</para>
2551ioctls.</para> 2556ioctls.</para>
2552 </listitem> 2557 </listitem>
2553 <listitem> 2558 <listitem>
2559 <para>&VIDIOC-DECODER-CMD; and &VIDIOC-TRY-DECODER-CMD;
2560ioctls.</para>
2561 </listitem>
2562 <listitem>
2554 <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; 2563 <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER;
2555ioctls.</para> 2564ioctls.</para>
2556 </listitem> 2565 </listitem>
@@ -2558,6 +2567,10 @@ ioctls.</para>
2558 <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> 2567 <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para>
2559 </listitem> 2568 </listitem>
2560 <listitem> 2569 <listitem>
2570 <para>&VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and
2571 &VIDIOC-DV-TIMINGS-CAP; ioctls.</para>
2572 </listitem>
2573 <listitem>
2561 <para>Flash API. <xref linkend="flash-controls" /></para> 2574 <para>Flash API. <xref linkend="flash-controls" /></para>
2562 </listitem> 2575 </listitem>
2563 <listitem> 2576 <listitem>
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index e6fbbc6c17e1..015c561754b7 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -28,8 +28,8 @@ documentation.</contrib>
28 <firstname>Hans</firstname> 28 <firstname>Hans</firstname>
29 <surname>Verkuil</surname> 29 <surname>Verkuil</surname>
30 <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl, 30 <contrib>Designed and documented the VIDIOC_LOG_STATUS ioctl,
31the extended control ioctls and major parts of the sliced VBI 31the extended control ioctls, major parts of the sliced VBI API, the
32API.</contrib> 32MPEG encoder and decoder APIs and the DV Timings API.</contrib>
33 <affiliation> 33 <affiliation>
34 <address> 34 <address>
35 <email>hverkuil@xs4all.nl</email> 35 <email>hverkuil@xs4all.nl</email>
@@ -123,6 +123,7 @@ Remote Controller chapter.</contrib>
123 <year>2009</year> 123 <year>2009</year>
124 <year>2010</year> 124 <year>2010</year>
125 <year>2011</year> 125 <year>2011</year>
126 <year>2012</year>
126 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin 127 <holder>Bill Dirks, Michael H. Schimek, Hans Verkuil, Martin
127Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab, 128Rubli, Andy Walls, Muralidharan Karicheri, Mauro Carvalho Chehab,
128 Pawel Osciak</holder> 129 Pawel Osciak</holder>
@@ -153,6 +154,11 @@ applications. -->
153 V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS 154 V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS
154 and V4L2_CID_AUTO_FOCUS_RANGE. 155 and V4L2_CID_AUTO_FOCUS_RANGE.
155 </revremark> 156 </revremark>
157 <date>2012-05-01</date>
158 <authorinitials>hv</authorinitials>
159 <revremark>Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and
160 VIDIOC_DV_TIMINGS_CAP.
161 </revremark>
156 </revision> 162 </revision>
157 163
158 <revision> 164 <revision>
@@ -461,7 +467,7 @@ and discussions on the V4L mailing list.</revremark>
461</partinfo> 467</partinfo>
462 468
463<title>Video for Linux Two API Specification</title> 469<title>Video for Linux Two API Specification</title>
464 <subtitle>Revision 3.3</subtitle> 470 <subtitle>Revision 3.5</subtitle>
465 471
466 <chapter id="common"> 472 <chapter id="common">
467 &sub-common; 473 &sub-common;
@@ -519,10 +525,12 @@ and discussions on the V4L mailing list.</revremark>
519 &sub-dbg-g-register; 525 &sub-dbg-g-register;
520 &sub-decoder-cmd; 526 &sub-decoder-cmd;
521 &sub-dqevent; 527 &sub-dqevent;
528 &sub-dv-timings-cap;
522 &sub-encoder-cmd; 529 &sub-encoder-cmd;
523 &sub-enumaudio; 530 &sub-enumaudio;
524 &sub-enumaudioout; 531 &sub-enumaudioout;
525 &sub-enum-dv-presets; 532 &sub-enum-dv-presets;
533 &sub-enum-dv-timings;
526 &sub-enum-fmt; 534 &sub-enum-fmt;
527 &sub-enum-framesizes; 535 &sub-enum-framesizes;
528 &sub-enum-frameintervals; 536 &sub-enum-frameintervals;
@@ -557,6 +565,7 @@ and discussions on the V4L mailing list.</revremark>
557 &sub-querycap; 565 &sub-querycap;
558 &sub-queryctrl; 566 &sub-queryctrl;
559 &sub-query-dv-preset; 567 &sub-query-dv-preset;
568 &sub-query-dv-timings;
560 &sub-querystd; 569 &sub-querystd;
561 &sub-prepare-buf; 570 &sub-prepare-buf;
562 &sub-reqbufs; 571 &sub-reqbufs;
diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
index 184cdfc13081..765549ff8a71 100644
--- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml
@@ -48,6 +48,12 @@
48 <refsect1> 48 <refsect1>
49 <title>Description</title> 49 <title>Description</title>
50 50
51 <note>
52 <title>Experimental</title>
53 <para>This is an <link linkend="experimental"> experimental </link>
54 interface and may change in the future.</para>
55 </note>
56
51 <para>This ioctl is used to create buffers for <link linkend="mmap">memory 57 <para>This ioctl is used to create buffers for <link linkend="mmap">memory
52mapped</link> or <link linkend="userp">user pointer</link> 58mapped</link> or <link linkend="userp">user pointer</link>
53I/O. It can be used as an alternative or in addition to the 59I/O. It can be used as an alternative or in addition to the
diff --git a/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
new file mode 100644
index 000000000000..6673ce582050
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
@@ -0,0 +1,211 @@
1<refentry id="vidioc-dv-timings-cap">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_DV_TIMINGS_CAP</refname>
9 <refpurpose>The capabilities of the Digital Video receiver/transmitter</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct v4l2_dv_timings_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_DV_TIMINGS_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 <note>
52 <title>Experimental</title>
53 <para>This is an <link linkend="experimental"> experimental </link>
54 interface and may change in the future.</para>
55 </note>
56
57 <para>To query the available timings, applications initialize the
58<structfield>index</structfield> field and zero the reserved array of &v4l2-dv-timings-cap;
59and call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl with a pointer to this
60structure. Drivers fill the rest of the structure or return an
61&EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
62applications shall begin at index zero, incrementing by one until the
63driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
64different set of DV timings after switching the video input or
65output.</para>
66
67 <table pgwide="1" frame="none" id="v4l2-bt-timings-cap">
68 <title>struct <structname>v4l2_bt_timings_cap</structname></title>
69 <tgroup cols="3">
70 &cs-str;
71 <tbody valign="top">
72 <row>
73 <entry>__u32</entry>
74 <entry><structfield>min_width</structfield></entry>
75 <entry>Minimum width of the active video in pixels.</entry>
76 </row>
77 <row>
78 <entry>__u32</entry>
79 <entry><structfield>max_width</structfield></entry>
80 <entry>Maximum width of the active video in pixels.</entry>
81 </row>
82 <row>
83 <entry>__u32</entry>
84 <entry><structfield>min_height</structfield></entry>
85 <entry>Minimum height of the active video in lines.</entry>
86 </row>
87 <row>
88 <entry>__u32</entry>
89 <entry><structfield>max_height</structfield></entry>
90 <entry>Maximum height of the active video in lines.</entry>
91 </row>
92 <row>
93 <entry>__u64</entry>
94 <entry><structfield>min_pixelclock</structfield></entry>
95 <entry>Minimum pixelclock frequency in Hz.</entry>
96 </row>
97 <row>
98 <entry>__u64</entry>
99 <entry><structfield>max_pixelclock</structfield></entry>
100 <entry>Maximum pixelclock frequency in Hz.</entry>
101 </row>
102 <row>
103 <entry>__u32</entry>
104 <entry><structfield>standards</structfield></entry>
105 <entry>The video standard(s) supported by the hardware.
106 See <xref linkend="dv-bt-standards"/> for a list of standards.</entry>
107 </row>
108 <row>
109 <entry>__u32</entry>
110 <entry><structfield>capabilities</structfield></entry>
111 <entry>Several flags giving more information about the capabilities.
112 See <xref linkend="dv-bt-cap-capabilities"/> for a description of the flags.
113 </entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>reserved</structfield>[16]</entry>
118 <entry></entry>
119 </row>
120 </tbody>
121 </tgroup>
122 </table>
123
124 <table pgwide="1" frame="none" id="v4l2-dv-timings-cap">
125 <title>struct <structname>v4l2_dv_timings_cap</structname></title>
126 <tgroup cols="4">
127 &cs-str;
128 <tbody valign="top">
129 <row>
130 <entry>__u32</entry>
131 <entry><structfield>type</structfield></entry>
132 <entry>Type of DV timings as listed in <xref linkend="dv-timing-types"/>.</entry>
133 </row>
134 <row>
135 <entry>__u32</entry>
136 <entry><structfield>reserved</structfield>[3]</entry>
137 <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
138 </row>
139 <row>
140 <entry>union</entry>
141 <entry><structfield></structfield></entry>
142 <entry></entry>
143 </row>
144 <row>
145 <entry></entry>
146 <entry>&v4l2-bt-timings-cap;</entry>
147 <entry><structfield>bt</structfield></entry>
148 <entry>BT.656/1120 timings capabilities of the hardware.</entry>
149 </row>
150 <row>
151 <entry></entry>
152 <entry>__u32</entry>
153 <entry><structfield>raw_data</structfield>[32]</entry>
154 <entry></entry>
155 </row>
156 </tbody>
157 </tgroup>
158 </table>
159
160 <table pgwide="1" frame="none" id="dv-bt-cap-capabilities">
161 <title>DV BT Timing capabilities</title>
162 <tgroup cols="2">
163 &cs-str;
164 <tbody valign="top">
165 <row>
166 <entry>Flag</entry>
167 <entry>Description</entry>
168 </row>
169 <row>
170 <entry></entry>
171 <entry></entry>
172 </row>
173 <row>
174 <entry>V4L2_DV_BT_CAP_INTERLACED</entry>
175 <entry>Interlaced formats are supported.
176 </entry>
177 </row>
178 <row>
179 <entry>V4L2_DV_BT_CAP_PROGRESSIVE</entry>
180 <entry>Progressive formats are supported.
181 </entry>
182 </row>
183 <row>
184 <entry>V4L2_DV_BT_CAP_REDUCED_BLANKING</entry>
185 <entry>CVT/GTF specific: the timings can make use of reduced blanking (CVT)
186or the 'Secondary GTF' curve (GTF).
187 </entry>
188 </row>
189 <row>
190 <entry>V4L2_DV_BT_CAP_CUSTOM</entry>
191 <entry>Can support non-standard timings, i.e. timings not belonging to the
192standards set in the <structfield>standards</structfield> field.
193 </entry>
194 </row>
195 </tbody>
196 </tgroup>
197 </table>
198 </refsect1>
199
200 <refsect1>
201 &return-value;
202 </refsect1>
203</refentry>
204
205<!--
206Local Variables:
207mode: sgml
208sgml-parent-document: "v4l2.sgml"
209indent-tabs-mode: nil
210End:
211-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml
index 0be17c232d3a..509f0012d2a6 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml
@@ -48,6 +48,10 @@
48 <refsect1> 48 <refsect1>
49 <title>Description</title> 49 <title>Description</title>
50 50
51 <para>This ioctl is <emphasis role="bold">deprecated</emphasis>.
52 New drivers and applications should use &VIDIOC-ENUM-DV-TIMINGS; instead.
53 </para>
54
51 <para>To query the attributes of a DV preset, applications initialize the 55 <para>To query the attributes of a DV preset, applications initialize the
52<structfield>index</structfield> field and zero the reserved array of &v4l2-dv-enum-preset; 56<structfield>index</structfield> field and zero the reserved array of &v4l2-dv-enum-preset;
53and call the <constant>VIDIOC_ENUM_DV_PRESETS</constant> ioctl with a pointer to this 57and call the <constant>VIDIOC_ENUM_DV_PRESETS</constant> ioctl with a pointer to this
diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
new file mode 100644
index 000000000000..24c3bf4fd29a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
@@ -0,0 +1,119 @@
1<refentry id="vidioc-enum-dv-timings">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_ENUM_DV_TIMINGS</refname>
9 <refpurpose>Enumerate supported Digital Video timings</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_enum_dv_timings *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>&fd;</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>request</parameter></term>
35 <listitem>
36 <para>VIDIOC_ENUM_DV_TIMINGS</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 <para>This is an <link linkend="experimental"> experimental </link>
54 interface and may change in the future.</para>
55 </note>
56
57 <para>While some DV receivers or transmitters support a wide range of timings, others
58support only a limited number of timings. With this ioctl applications can enumerate a list
59of known supported timings. Call &VIDIOC-DV-TIMINGS-CAP; to check if it also supports other
60standards or even custom timings that are not in this list.</para>
61
62 <para>To query the available timings, applications initialize the
63<structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings;
64and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl with a pointer to this
65structure. Drivers fill the rest of the structure or return an
66&EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
67applications shall begin at index zero, incrementing by one until the
68driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
69different set of DV timings after switching the video input or
70output.</para>
71
72 <table pgwide="1" frame="none" id="v4l2-enum-dv-timings">
73 <title>struct <structname>v4l2_enum_dv_timings</structname></title>
74 <tgroup cols="3">
75 &cs-str;
76 <tbody valign="top">
77 <row>
78 <entry>__u32</entry>
79 <entry><structfield>index</structfield></entry>
80 <entry>Number of the DV timings, set by the
81application.</entry>
82 </row>
83 <row>
84 <entry>__u32</entry>
85 <entry><structfield>reserved</structfield>[3]</entry>
86 <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
87 </row>
88 <row>
89 <entry>&v4l2-dv-timings;</entry>
90 <entry><structfield>timings</structfield></entry>
91 <entry>The timings.</entry>
92 </row>
93 </tbody>
94 </tgroup>
95 </table>
96 </refsect1>
97
98 <refsect1>
99 &return-value;
100
101 <variablelist>
102 <varlistentry>
103 <term><errorcode>EINVAL</errorcode></term>
104 <listitem>
105 <para>The &v4l2-enum-dv-timings; <structfield>index</structfield>
106is out of bounds.</para>
107 </listitem>
108 </varlistentry>
109 </variablelist>
110 </refsect1>
111</refentry>
112
113<!--
114Local Variables:
115mode: sgml
116sgml-parent-document: "v4l2.sgml"
117indent-tabs-mode: nil
118End:
119-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
index 9b8efcd6e947..46d5a044a537 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml
@@ -285,7 +285,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009.
285 <row> 285 <row>
286 <entry><constant>V4L2_IN_CAP_CUSTOM_TIMINGS</constant></entry> 286 <entry><constant>V4L2_IN_CAP_CUSTOM_TIMINGS</constant></entry>
287 <entry>0x00000002</entry> 287 <entry>0x00000002</entry>
288 <entry>This input supports setting custom video timings by using VIDIOC_S_DV_TIMINGS.</entry> 288 <entry>This input supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry>
289 </row> 289 </row>
290 <row> 290 <row>
291 <entry><constant>V4L2_IN_CAP_STD</constant></entry> 291 <entry><constant>V4L2_IN_CAP_STD</constant></entry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml
index a64d5ef103fa..428020000ef0 100644
--- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml
@@ -170,7 +170,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009.
170 <row> 170 <row>
171 <entry><constant>V4L2_OUT_CAP_CUSTOM_TIMINGS</constant></entry> 171 <entry><constant>V4L2_OUT_CAP_CUSTOM_TIMINGS</constant></entry>
172 <entry>0x00000002</entry> 172 <entry>0x00000002</entry>
173 <entry>This output supports setting custom video timings by using VIDIOC_S_DV_TIMINGS.</entry> 173 <entry>This output supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry>
174 </row> 174 </row>
175 <row> 175 <row>
176 <entry><constant>V4L2_OUT_CAP_STD</constant></entry> 176 <entry><constant>V4L2_OUT_CAP_STD</constant></entry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
index 4a8648ae9a63..eda1a2991bbe 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
@@ -7,7 +7,7 @@
7 <refnamediv> 7 <refnamediv>
8 <refname>VIDIOC_G_DV_TIMINGS</refname> 8 <refname>VIDIOC_G_DV_TIMINGS</refname>
9 <refname>VIDIOC_S_DV_TIMINGS</refname> 9 <refname>VIDIOC_S_DV_TIMINGS</refname>
10 <refpurpose>Get or set custom DV timings for input or output</refpurpose> 10 <refpurpose>Get or set DV timings for input or output</refpurpose>
11 </refnamediv> 11 </refnamediv>
12 12
13 <refsynopsisdiv> 13 <refsynopsisdiv>
@@ -48,12 +48,15 @@
48 48
49 <refsect1> 49 <refsect1>
50 <title>Description</title> 50 <title>Description</title>
51 <para>To set custom DV timings for the input or output, applications use the 51 <para>To set DV timings for the input or output, applications use the
52<constant>VIDIOC_S_DV_TIMINGS</constant> ioctl and to get the current custom timings, 52<constant>VIDIOC_S_DV_TIMINGS</constant> ioctl and to get the current timings,
53applications use the <constant>VIDIOC_G_DV_TIMINGS</constant> ioctl. The detailed timing 53applications use the <constant>VIDIOC_G_DV_TIMINGS</constant> ioctl. The detailed timing
54information is filled in using the structure &v4l2-dv-timings;. These ioctls take 54information is filled in using the structure &v4l2-dv-timings;. These ioctls take
55a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not supported 55a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not supported
56or the timing values are not correct, the driver returns &EINVAL;.</para> 56or the timing values are not correct, the driver returns &EINVAL;.</para>
57<para>The <filename>linux/v4l2-dv-timings.h</filename> header can be used to get the
58timings of the formats in the <xref linkend="cea861" /> and <xref linkend="vesadmt" />
59standards.</para>
57 </refsect1> 60 </refsect1>
58 61
59 <refsect1> 62 <refsect1>
@@ -83,12 +86,13 @@ or the timing values are not correct, the driver returns &EINVAL;.</para>
83 <row> 86 <row>
84 <entry>__u32</entry> 87 <entry>__u32</entry>
85 <entry><structfield>width</structfield></entry> 88 <entry><structfield>width</structfield></entry>
86 <entry>Width of the active video in pixels</entry> 89 <entry>Width of the active video in pixels.</entry>
87 </row> 90 </row>
88 <row> 91 <row>
89 <entry>__u32</entry> 92 <entry>__u32</entry>
90 <entry><structfield>height</structfield></entry> 93 <entry><structfield>height</structfield></entry>
91 <entry>Height of the active video in lines</entry> 94 <entry>Height of the active video frame in lines. So for interlaced formats the
95 height of the active video in each field is <structfield>height</structfield>/2.</entry>
92 </row> 96 </row>
93 <row> 97 <row>
94 <entry>__u32</entry> 98 <entry>__u32</entry>
@@ -125,32 +129,52 @@ bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_H
125 <row> 129 <row>
126 <entry>__u32</entry> 130 <entry>__u32</entry>
127 <entry><structfield>vfrontporch</structfield></entry> 131 <entry><structfield>vfrontporch</structfield></entry>
128 <entry>Vertical front porch in lines</entry> 132 <entry>Vertical front porch in lines. For interlaced formats this refers to the
133 odd field (aka field 1).</entry>
129 </row> 134 </row>
130 <row> 135 <row>
131 <entry>__u32</entry> 136 <entry>__u32</entry>
132 <entry><structfield>vsync</structfield></entry> 137 <entry><structfield>vsync</structfield></entry>
133 <entry>Vertical sync length in lines</entry> 138 <entry>Vertical sync length in lines. For interlaced formats this refers to the
139 odd field (aka field 1).</entry>
134 </row> 140 </row>
135 <row> 141 <row>
136 <entry>__u32</entry> 142 <entry>__u32</entry>
137 <entry><structfield>vbackporch</structfield></entry> 143 <entry><structfield>vbackporch</structfield></entry>
138 <entry>Vertical back porch in lines</entry> 144 <entry>Vertical back porch in lines. For interlaced formats this refers to the
145 odd field (aka field 1).</entry>
139 </row> 146 </row>
140 <row> 147 <row>
141 <entry>__u32</entry> 148 <entry>__u32</entry>
142 <entry><structfield>il_vfrontporch</structfield></entry> 149 <entry><structfield>il_vfrontporch</structfield></entry>
143 <entry>Vertical front porch in lines for bottom field of interlaced field formats</entry> 150 <entry>Vertical front porch in lines for the even field (aka field 2) of
151 interlaced field formats.</entry>
144 </row> 152 </row>
145 <row> 153 <row>
146 <entry>__u32</entry> 154 <entry>__u32</entry>
147 <entry><structfield>il_vsync</structfield></entry> 155 <entry><structfield>il_vsync</structfield></entry>
148 <entry>Vertical sync length in lines for bottom field of interlaced field formats</entry> 156 <entry>Vertical sync length in lines for the even field (aka field 2) of
157 interlaced field formats.</entry>
149 </row> 158 </row>
150 <row> 159 <row>
151 <entry>__u32</entry> 160 <entry>__u32</entry>
152 <entry><structfield>il_vbackporch</structfield></entry> 161 <entry><structfield>il_vbackporch</structfield></entry>
153 <entry>Vertical back porch in lines for bottom field of interlaced field formats</entry> 162 <entry>Vertical back porch in lines for the even field (aka field 2) of
163 interlaced field formats.</entry>
164 </row>
165 <row>
166 <entry>__u32</entry>
167 <entry><structfield>standards</structfield></entry>
168 <entry>The video standard(s) this format belongs to. This will be filled in by
169 the driver. Applications must set this to 0. See <xref linkend="dv-bt-standards"/>
170 for a list of standards.</entry>
171 </row>
172 <row>
173 <entry>__u32</entry>
174 <entry><structfield>flags</structfield></entry>
175 <entry>Several flags giving more information about the format.
176 See <xref linkend="dv-bt-flags"/> for a description of the flags.
177 </entry>
154 </row> 178 </row>
155 </tbody> 179 </tbody>
156 </tgroup> 180 </tgroup>
@@ -211,6 +235,90 @@ bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_H
211 </tbody> 235 </tbody>
212 </tgroup> 236 </tgroup>
213 </table> 237 </table>
238 <table pgwide="1" frame="none" id="dv-bt-standards">
239 <title>DV BT Timing standards</title>
240 <tgroup cols="2">
241 &cs-str;
242 <tbody valign="top">
243 <row>
244 <entry>Timing standard</entry>
245 <entry>Description</entry>
246 </row>
247 <row>
248 <entry></entry>
249 <entry></entry>
250 </row>
251 <row>
252 <entry>V4L2_DV_BT_STD_CEA861</entry>
253 <entry>The timings follow the CEA-861 Digital TV Profile standard</entry>
254 </row>
255 <row>
256 <entry>V4L2_DV_BT_STD_DMT</entry>
257 <entry>The timings follow the VESA Discrete Monitor Timings standard</entry>
258 </row>
259 <row>
260 <entry>V4L2_DV_BT_STD_CVT</entry>
261 <entry>The timings follow the VESA Coordinated Video Timings standard</entry>
262 </row>
263 <row>
264 <entry>V4L2_DV_BT_STD_GTF</entry>
265 <entry>The timings follow the VESA Generalized Timings Formula standard</entry>
266 </row>
267 </tbody>
268 </tgroup>
269 </table>
270 <table pgwide="1" frame="none" id="dv-bt-flags">
271 <title>DV BT Timing flags</title>
272 <tgroup cols="2">
273 &cs-str;
274 <tbody valign="top">
275 <row>
276 <entry>Flag</entry>
277 <entry>Description</entry>
278 </row>
279 <row>
280 <entry></entry>
281 <entry></entry>
282 </row>
283 <row>
284 <entry>V4L2_DV_FL_REDUCED_BLANKING</entry>
285 <entry>CVT/GTF specific: the timings use reduced blanking (CVT) or the 'Secondary
286GTF' curve (GTF). In both cases the horizontal and/or vertical blanking
287intervals are reduced, allowing a higher resolution over the same
288bandwidth. This is a read-only flag, applications must not set this.
289 </entry>
290 </row>
291 <row>
292 <entry>V4L2_DV_FL_CAN_REDUCE_FPS</entry>
293 <entry>CEA-861 specific: set for CEA-861 formats with a framerate that is a multiple
294of six. These formats can be optionally played at 1 / 1.001 speed to
295be compatible with 60 Hz based standards such as NTSC and PAL-M that use a framerate of
29629.97 frames per second. If the transmitter can't generate such frequencies, then the
297flag will also be cleared. This is a read-only flag, applications must not set this.
298 </entry>
299 </row>
300 <row>
301 <entry>V4L2_DV_FL_REDUCED_FPS</entry>
302 <entry>CEA-861 specific: only valid for video transmitters, the flag is cleared
303by receivers. It is also only valid for formats with the V4L2_DV_FL_CAN_REDUCE_FPS flag
304set, for other formats the flag will be cleared by the driver.
305
306If the application sets this flag, then the pixelclock used to set up the transmitter is
307divided by 1.001 to make it compatible with NTSC framerates. If the transmitter
308can't generate such frequencies, then the flag will also be cleared.
309 </entry>
310 </row>
311 <row>
312 <entry>V4L2_DV_FL_HALF_LINE</entry>
313 <entry>Specific to interlaced formats: if set, then field 1 (aka the odd field)
314is really one half-line longer and field 2 (aka the even field) is really one half-line
315shorter, so each field has exactly the same number of half-lines. Whether half-lines can be
316detected or used depends on the hardware.
317 </entry>
318 </row>
319 </tbody>
320 </tgroup>
321 </table>
214 </refsect1> 322 </refsect1>
215 <refsect1> 323 <refsect1>
216 &return-value; 324 &return-value;
diff --git a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml
index 7bde698760e4..fa7ad7e33228 100644
--- a/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-prepare-buf.xml
@@ -48,6 +48,12 @@
48 <refsect1> 48 <refsect1>
49 <title>Description</title> 49 <title>Description</title>
50 50
51 <note>
52 <title>Experimental</title>
53 <para>This is an <link linkend="experimental"> experimental </link>
54 interface and may change in the future.</para>
55 </note>
56
51 <para>Applications can optionally call the 57 <para>Applications can optionally call the
52<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer 58<constant>VIDIOC_PREPARE_BUF</constant> ioctl to pass ownership of the buffer
53to the driver before actually enqueuing it, using the 59to the driver before actually enqueuing it, using the
diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
new file mode 100644
index 000000000000..44935a0ffcf0
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
@@ -0,0 +1,104 @@
1<refentry id="vidioc-query-dv-timings">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_QUERY_DV_TIMINGS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>VIDIOC_QUERY_DV_TIMINGS</refname>
9 <refpurpose>Sense the DV preset received by the current
10input</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct v4l2_dv_timings *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>VIDIOC_QUERY_DV_TIMINGS</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <note>
53 <title>Experimental</title>
54 <para>This is an <link linkend="experimental"> experimental </link>
55 interface and may change in the future.</para>
56 </note>
57
58 <para>The hardware may be able to detect the current DV timings
59automatically, similar to sensing the video standard. To do so, applications
60call <constant>VIDIOC_QUERY_DV_TIMINGS</constant> with a pointer to a
61&v4l2-dv-timings;. Once the hardware detects the timings, it will fill in the
62timings structure.
63
64If the timings could not be detected because there was no signal, then
65<errorcode>ENOLINK</errorcode> is returned. If a signal was detected, but
66it was unstable and the receiver could not lock to the signal, then
67<errorcode>ENOLCK</errorcode> is returned. If the receiver could lock to the signal,
68but the format is unsupported (e.g. because the pixelclock is out of range
69of the hardware capabilities), then the driver fills in whatever timings it
70could find and returns <errorcode>ERANGE</errorcode>. In that case the application
71can call &VIDIOC-DV-TIMINGS-CAP; to compare the found timings with the hardware's
72capabilities in order to give more precise feedback to the user.
73</para>
74 </refsect1>
75
76 <refsect1>
77 &return-value;
78
79 <variablelist>
80 <varlistentry>
81 <term><errorcode>ENOLINK</errorcode></term>
82 <listitem>
83 <para>No timings could be detected because no signal was found.
84</para>
85 </listitem>
86 </varlistentry>
87 <varlistentry>
88 <term><errorcode>ENOLCK</errorcode></term>
89 <listitem>
90 <para>The signal was unstable and the hardware could not lock on to it.
91</para>
92 </listitem>
93 </varlistentry>
94 <varlistentry>
95 <term><errorcode>ERANGE</errorcode></term>
96 <listitem>
97 <para>Timings were found, but they are out of range of the hardware
98capabilities.
99</para>
100 </listitem>
101 </varlistentry>
102 </variablelist>
103 </refsect1>
104</refentry>
generated by cgit v1.2.2 (git 2.25.0) at 2026-05-27 13:21:38 -0400