From: Hans Verkuil <hans.verkuil@xxxxxxxxx>
Signed-off-by: Hans Verkuil <hans.verkuil@xxxxxxxxx>
---
Documentation/DocBook/media/v4l/v4l2.xml | 3 +
.../DocBook/media/v4l/vidioc-dv-timings-cap.xml | 205 ++++++++++++++++++++
.../DocBook/media/v4l/vidioc-enum-dv-timings.xml | 113 +++++++++++
.../DocBook/media/v4l/vidioc-g-dv-timings.xml | 120 +++++++++++-
.../DocBook/media/v4l/vidioc-query-dv-timings.xml | 98 ++++++++++
5 files changed, 531 insertions(+), 8 deletions(-)
create mode 100644 Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
create mode 100644 Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
create mode 100644 Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index dce3fef..8bc2ccd 100644
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -481,10 +481,12 @@ and discussions on the V4L mailing list.</revremark>
&sub-dbg-g-chip-ident;
&sub-dbg-g-register;
&sub-dqevent;
+ &sub-dv-timings-cap;
&sub-encoder-cmd;
&sub-enumaudio;
&sub-enumaudioout;
&sub-enum-dv-presets;
+ &sub-enum-dv-timings;
&sub-enum-fmt;
&sub-enum-framesizes;
&sub-enum-frameintervals;
@@ -519,6 +521,7 @@ and discussions on the V4L mailing list.</revremark>
&sub-querycap;
&sub-queryctrl;
&sub-query-dv-preset;
+ &sub-query-dv-timings;
&sub-querystd;
&sub-prepare-buf;
&sub-reqbufs;
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 0000000..0477de1
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
@@ -0,0 +1,205 @@
+<refentry id="vidioc-dv-timings-cap">
+ <refmeta>
+ <refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP</refentrytitle>
+ &manvol;
+ </refmeta>
+
+ <refnamediv>
+ <refname>VIDIOC_DV_TIMINGS_CAP</refname>
+ <refpurpose>The capabilities of the Digital Video receiver/transmitter</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>ioctl</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>int <parameter>request</parameter></paramdef>
+ <paramdef>struct v4l2_dv_timings_cap *<parameter>argp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Arguments</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>fd</parameter></term>
+ <listitem>
+ <para>&fd;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>request</parameter></term>
+ <listitem>
+ <para>VIDIOC_DV_TIMINGS_CAP</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>argp</parameter></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>To query the available timings, applications initialize the
+<structfield>index</structfield> field and zero the reserved array of &v4l2-dv-timings-cap;
+and call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl with a pointer to this
+structure. Drivers fill the rest of the structure or return an
+&EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
+applications shall begin at index zero, incrementing by one until the
+driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
+different set of DV timings after switching the video input or
+output.</para>
+
+ <table pgwide="1" frame="none" id="v4l2-bt-timings-cap">
+ <title>struct <structname>v4l2_bt_timings_cap</structname></title>
+ <tgroup cols="3">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>min_width</structfield></entry>
+ <entry>Minimum width of the active video in pixels.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>max_width</structfield></entry>
+ <entry>Maximum width of the active video in pixels.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>min_height</structfield></entry>
+ <entry>Minimum height of the active video in lines.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>max_height</structfield></entry>
+ <entry>Maximum height of the active video in lines.</entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>min_pixelclock</structfield></entry>
+ <entry>Minimum pixelclock frequency in Hz.</entry>
+ </row>
+ <row>
+ <entry>__u64</entry>
+ <entry><structfield>max_pixelclock</structfield></entry>
+ <entry>Maximum pixelclock frequency in Hz.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>standards</structfield></entry>
+ <entry>The video standard(s) supported by the hardware.
+ See <xref linkend="dv-bt-standards"/> for a list of standards.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>capabilities</structfield></entry>
+ <entry>Several flags giving more information about the capabilities.
+ See <xref linkend="dv-bt-cap-capabilities"/> for a description of the flags.
+ </entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[16]</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="v4l2-dv-timings-cap">
+ <title>struct <structname>v4l2_dv_timings_cap</structname></title>
+ <tgroup cols="4">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>type</structfield></entry>
+ <entry>Type of DV timings as listed in <xref linkend="dv-timing-types"/>.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[3]</entry>
+ <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
+ </row>
+ <row>
+ <entry>union</entry>
+ <entry><structfield></structfield></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>&v4l2-bt-timings-cap;</entry>
+ <entry><structfield>bt</structfield></entry>
+ <entry>BT.656/1120 timings capabilities of the hardware.</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry>__u32</entry>
+ <entry><structfield>raw_data</structfield>[32]</entry>
+ <entry></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table pgwide="1" frame="none" id="dv-bt-cap-capabilities">
+ <title>DV BT Timing capabilities</title>
+ <tgroup cols="2">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>Flag</entry>
+ <entry>Description</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_CAP_INTERLACED</entry>
+ <entry>Interlaced formats are supported.
+ </entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_CAP_PROGRESSIVE</entry>
+ <entry>Progressive formats are supported.
+ </entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_CAP_REDUCED_BLANKING</entry>
+ <entry>CVT/GTF specific: the timings can make use of reduced blanking (CVT)
+or the 'Secondary GTF' curve (GTF).
+ </entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_CAP_CUSTOM</entry>
+ <entry>Can support non-standard timings, i.e. timings not belonging to the
+standards set in the <structfield>standards</structfield> field.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </refsect1>
+
+ <refsect1>
+ &return-value;
+ </refsect1>
+</refentry>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-parent-document: "v4l2.sgml"
+indent-tabs-mode: nil
+End:
+-->
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 0000000..edd6964
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
@@ -0,0 +1,113 @@
+<refentry id="vidioc-enum-dv-timings">
+ <refmeta>
+ <refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS</refentrytitle>
+ &manvol;
+ </refmeta>
+
+ <refnamediv>
+ <refname>VIDIOC_ENUM_DV_TIMINGS</refname>
+ <refpurpose>Enumerate supported Digital Video timings</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>ioctl</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>int <parameter>request</parameter></paramdef>
+ <paramdef>struct v4l2_enum_dv_timings *<parameter>argp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Arguments</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>fd</parameter></term>
+ <listitem>
+ <para>&fd;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>request</parameter></term>
+ <listitem>
+ <para>VIDIOC_ENUM_DV_TIMINGS</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>argp</parameter></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>While some DV receivers or transmitters support a wide range of timings, others
+support only a limited number of timings. With this ioctl applications can enumerate a list
+of known supported timings. Call &VIDIOC-DV-TIMINGS-CAP; to check if it also supports other
+standards or even custom timings that are not in this list.</para>
+
+ <para>To query the available timings, applications initialize the
+<structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings;
+and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl with a pointer to this
+structure. Drivers fill the rest of the structure or return an
+&EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
+applications shall begin at index zero, incrementing by one until the
+driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
+different set of DV timings after switching the video input or
+output.</para>
+
+ <table pgwide="1" frame="none" id="v4l2-enum-dv-timings">
+ <title>struct <structname>v4l2_enum_dv_timings</structname></title>
+ <tgroup cols="3">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>index</structfield></entry>
+ <entry>Number of the DV timings, set by the
+application.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>reserved</structfield>[3]</entry>
+ <entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
+ </row>
+ <row>
+ <entry>&v4l2-dv-timings;</entry>
+ <entry><structfield>timings</structfield></entry>
+ <entry>The timings.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </refsect1>
+
+ <refsect1>
+ &return-value;
+
+ <variablelist>
+ <varlistentry>
+ <term><errorcode>EINVAL</errorcode></term>
+ <listitem>
+ <para>The &v4l2-enum-dv-timings; <structfield>index</structfield>
+is out of bounds.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+</refentry>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-parent-document: "v4l2.sgml"
+indent-tabs-mode: nil
+End:
+-->
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
index 4a8648a..bffd26c 100644
--- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml
@@ -83,12 +83,13 @@ or the timing values are not correct, the driver returns &EINVAL;.</para>
<row>
<entry>__u32</entry>
<entry><structfield>width</structfield></entry>
- <entry>Width of the active video in pixels</entry>
+ <entry>Width of the active video in pixels.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>height</structfield></entry>
- <entry>Height of the active video in lines</entry>
+ <entry>Height of the active video frame in lines. So for interlaced formats the
+ height of the active video in each field is <structfield>height</structfield>/2.</entry>
</row>
<row>
<entry>__u32</entry>
@@ -125,32 +126,52 @@ bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_H
<row>
<entry>__u32</entry>
<entry><structfield>vfrontporch</structfield></entry>
- <entry>Vertical front porch in lines</entry>
+ <entry>Vertical front porch in lines. For interlaced formats this refers to the
+ odd field (aka field 1).</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>vsync</structfield></entry>
- <entry>Vertical sync length in lines</entry>
+ <entry>Vertical sync length in lines. For interlaced formats this refers to the
+ odd field (aka field 1).</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>vbackporch</structfield></entry>
- <entry>Vertical back porch in lines</entry>
+ <entry>Vertical back porch in lines. For interlaced formats this refers to the
+ odd field (aka field 1).</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>il_vfrontporch</structfield></entry>
- <entry>Vertical front porch in lines for bottom field of interlaced field formats</entry>
+ <entry>Vertical front porch in lines for the even field (aka field 2) of
+ interlaced field formats.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>il_vsync</structfield></entry>
- <entry>Vertical sync length in lines for bottom field of interlaced field formats</entry>
+ <entry>Vertical sync length in lines for the even field (aka field 2) of
+ interlaced field formats.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>il_vbackporch</structfield></entry>
- <entry>Vertical back porch in lines for bottom field of interlaced field formats</entry>
+ <entry>Vertical back porch in lines for the even field (aka field 2) of
+ interlaced field formats.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>standards</structfield></entry>
+ <entry>The video standard(s) this format belongs to. This will be filled in by
+ the driver. Applications must set this to 0. See <xref linkend="dv-bt-standards"/>
+ for a list of standards.</entry>
+ </row>
+ <row>
+ <entry>__u32</entry>
+ <entry><structfield>flags</structfield></entry>
+ <entry>Several flags giving more information about the format.
+ See <xref linkend="dv-bt-flags"/> for a description of the flags.
+ </entry>
</row>
</tbody>
</tgroup>
@@ -211,6 +232,89 @@ bit 0 (V4L2_DV_VSYNC_POS_POL) is for vertical sync polarity and bit 1 (V4L2_DV_H
</tbody>
</tgroup>
</table>
+ <table pgwide="1" frame="none" id="dv-bt-standards">
+ <title>DV BT Timing standards</title>
+ <tgroup cols="2">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>Timing standard</entry>
+ <entry>Description</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_STD_CEA861</entry>
+ <entry>The timings follow the CEA-861 Digital TV Profile standard</entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_STD_DMT</entry>
+ <entry>The timings follow the VESA Discrete Monitor Timings standard</entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_STD_CVT</entry>
+ <entry>The timings follow the VESA Coordinated Video Timings standard</entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_BT_STD_GTF</entry>
+ <entry>The timings follow the VESA Generalized Timings Formula standard</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table pgwide="1" frame="none" id="dv-bt-flags">
+ <title>DV BT Timing flags</title>
+ <tgroup cols="2">
+ &cs-str;
+ <tbody valign="top">
+ <row>
+ <entry>Flag</entry>
+ <entry>Description</entry>
+ </row>
+ <row>
+ <entry></entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_FL_REDUCED_BLANKING</entry>
+ <entry>CVT/GTF specific: the timings use reduced blanking (CVT) or the 'Secondary
+GTF' curve (GTF). In both cases the horizontal and/or vertical blanking
+intervals are reduced, allowing a higher resolution over the same
+bandwidth. This is a read-only flag, applications must not set this.
+ </entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_FL_NTSC_COMPATIBLE</entry>
+ <entry>CEA-861 specific: set for CEA-861 formats with a framerate of a multiple
+of six. These formats can be optionally played at 1 / 1.001 speed to
+be compatible with the normal NTSC framerate of 29.97 frames per second.
+This is a read-only flag, applications must not set this.
+ </entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_FL_DIVIDE_CLOCK_BY_1_001</entry>
+ <entry>CEA-861 specific: only valid for video transmitters, the flag is cleared
+by receivers. It is also only valid for formats with the V4L2_DV_FL_NTSC_COMPATIBLE flag
+set, for other formats the flag will be cleared by the driver.
+
+If the application sets this flag, then the pixelclock used to set up the transmitter is
+divided by 1.001 to make it compatible with NTSC framerates. If the transmitter
+can't generate such frequencies, then the flag will also be cleared.
+ </entry>
+ </row>
+ <row>
+ <entry>V4L2_DV_FL_HALF_LINE</entry>
+ <entry>Specific to interlaced formats: if set, then field 1 (aka the odd field)
+is really one half-line longer and field 2 (aka the even field) is really one half-line
+shorter, so each field has exactly the same number of half-lines. Whether half-lines can be
+detected or used depends on the hardware.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</refsect1>
<refsect1>
&return-value;
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 0000000..9d7ac43
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml
@@ -0,0 +1,98 @@
+<refentry id="vidioc-query-dv-timings">
+ <refmeta>
+ <refentrytitle>ioctl VIDIOC_QUERY_DV_TIMINGS</refentrytitle>
+ &manvol;
+ </refmeta>
+
+ <refnamediv>
+ <refname>VIDIOC_QUERY_DV_TIMINGS</refname>
+ <refpurpose>Sense the DV preset received by the current
+input</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>ioctl</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>int <parameter>request</parameter></paramdef>
+ <paramdef>struct v4l2_dv_timings *<parameter>argp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Arguments</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>fd</parameter></term>
+ <listitem>
+ <para>&fd;</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>request</parameter></term>
+ <listitem>
+ <para>VIDIOC_QUERY_DV_TIMINGS</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>argp</parameter></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>The hardware may be able to detect the current DV timings
+automatically, similar to sensing the video standard. To do so, applications
+call <constant>VIDIOC_QUERY_DV_TIMINGS</constant> with a pointer to a
+&v4l2-dv-timings;. Once the hardware detects the timings, it will fill in the
+timings structure.
+
+If the timings could not be detected because there was no signal, then
+<errorcode>ENOLINK</errorcode> is returned. If a signal was detected, but
+it was unstable and the receiver could not lock to the signal, then
+<errorcode>ENOLCK</errorcode> is returned. If the receiver could lock to the signal,
+but the format is unsupported (e.g. because the pixelclock is out of range
+of the hardware capabilities), then the driver fills in whatever timings it
+could find and returns <errorcode>ERANGE</errorcode>. In that case the application
+can call &VIDIOC-DV-TIMINGS-CAP; to compare the found timings with the hardware's
+capabilities in order to give more precise feedback to the user.
+</para>
+ </refsect1>
+
+ <refsect1>
+ &return-value;
+
+ <variablelist>
+ <varlistentry>
+ <term><errorcode>ENOLINK</errorcode></term>
+ <listitem>
+ <para>No timings could be detected because no signal was found.
+</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><errorcode>ENOLCK</errorcode></term>
+ <listitem>
+ <para>The signal was unstable and the hardware could not lock on to it.
+</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><errorcode>ERANGE</errorcode></term>
+ <listitem>
+ <para>Timings were found, but they are out of range of the hardware
+capabilities.
+</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+</refentry>
--
1.7.8.3
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
