[media] V4L2: Mark the DV Preset API as deprecated

The DV Preset API will be phased out in favor of the more flexible DV Timings
API. Mark the preset API accordingly in the header and documentation.

Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml
index 81b7cf384a398ac3fd44bea1a769162e9aa51a09..4101aeb565406b6ed08219feff76bdd735f1fd33 100644 (file)
--- a/Documentation/DocBook/media/v4l/common.xml
+++ b/Documentation/DocBook/media/v4l/common.xml
@@ -744,11 +744,13 @@ header can be used to get the timings of the formats in the <xref linkend="cea86
        </para>
        </listitem>
        <listitem>
-       <para>DV Presets: Digital Video (DV) presets. These are IDs representing a
+       <para>DV Presets: Digital Video (DV) presets (<emphasis role="bold">deprecated</emphasis>).
+       These are IDs representing a
 video timing at the input/output. Presets are pre-defined timings implemented
 by the hardware according to video standards. A __u32 data type is used to represent
 a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions
-to support as many different presets as needed.</para>
+to support as many different presets as needed. This API is deprecated in favor of the DV Timings
+API.</para>
        </listitem>
        </itemizedlist>
        <para>To enumerate and query the attributes of the DV timings supported by a device,

diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index cd19d21085db25a6fa6578b3a6bfafbeef030455..ea42ef824948cd6392189328faa65725c22013f8 100644 (file)
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2602,6 +2602,10 @@ interfaces and should not be implemented in new drivers.</para>
 <constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls,
 <xref linkend="extended-controls" />.</para>
         </listitem>
+        <listitem>
+         <para>&VIDIOC-G-DV-PRESET;, &VIDIOC-S-DV-PRESET;, &VIDIOC-ENUM-DV-PRESETS; and
+         &VIDIOC-QUERY-DV-PRESET; ioctls. Use the DV Timings API (<xref linkend="dv-timings" />).</para>
+        </listitem>
         <listitem>
          <para><constant>VIDIOC_SUBDEV_G_CROP</constant> and
          <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctls. Use

diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml
index 7940c114939310a7210216a35382743227aebe7d..61be9fa3803acbb707277e7e3b5527b4d681533b 100644 (file)
--- a/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml
@@ -48,6 +48,12 @@
 
   <refsect1>
     <title>Description</title>
+
+    <para>These ioctls are <emphasis role="bold">deprecated</emphasis>.
+    New drivers and applications should use &VIDIOC-G-DV-TIMINGS; and &VIDIOC-S-DV-TIMINGS;
+    instead.
+    </para>
+
     <para>To query and select the current DV preset, applications
 use the <constant>VIDIOC_G_DV_PRESET</constant> and <constant>VIDIOC_S_DV_PRESET</constant>
 ioctls which take a pointer to a &v4l2-dv-preset; type as argument.

diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml
index 23b17f60421144900e5cc5daabb3d036cecb11df..1bc8aeb3ff1fe2a57516f39dd54128fc4c30e116 100644 (file)
--- a/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml
@@ -49,6 +49,10 @@ input</refpurpose>
   <refsect1>
     <title>Description</title>
 
+    <para>This ioctl is <emphasis role="bold">deprecated</emphasis>.
+    New drivers and applications should use &VIDIOC-QUERY-DV-TIMINGS; instead.
+    </para>
+
     <para>The hardware may be able to detect the current DV preset
 automatically, similar to sensing the video standard. To do so, applications
 call <constant> VIDIOC_QUERY_DV_PRESET</constant> with a pointer to a

diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h
index 13d84ed9d3a87ad319e955ba369b2d7be1d41689..370d11106c1116811b8bf668892bf4fadf6a8b0d 100644 (file)
--- a/include/linux/videodev2.h
+++ b/include/linux/videodev2.h
@@ -944,6 +944,9 @@ struct v4l2_standard {
        __u32                reserved[4];
 };
 
+/* The DV Preset API is deprecated in favor of the DV Timings API.
+   New drivers shouldn't use this anymore! */
+
 /*
  *     V I D E O       T I M I N G S   D V     P R E S E T
  */
@@ -2608,6 +2611,9 @@ struct v4l2_create_buffers {
 #endif
 
 #define VIDIOC_S_HW_FREQ_SEEK   _IOW('V', 82, struct v4l2_hw_freq_seek)
+
+/* These four DV Preset ioctls are deprecated in favor of the DV Timings
+   ioctls. */
 #define        VIDIOC_ENUM_DV_PRESETS  _IOWR('V', 83, struct v4l2_dv_enum_preset)
 #define        VIDIOC_S_DV_PRESET      _IOWR('V', 84, struct v4l2_dv_preset)
 #define        VIDIOC_G_DV_PRESET      _IOWR('V', 85, struct v4l2_dv_preset)