[media] videodev2.h: add V4L2_CTRL_FLAG_VOLATILE

Add a new VOLATILE control flag that is set for volatile controls.
That way applications know whether the value of the control is volatile
(i.e. can change continuously) or not.

Until now this was an internal property, but it is useful to know in
userspace as well.

A typical use case is the gain value when autogain is on. In that case the
hardware will continuously adjust the gain based various environmental
factors.

This patch just adds and documents the flag, it's not yet used.

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

diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml
index ce1004a7da5233f96d1a33636a11b24879ae69a1..91410b6e7e08cf6a3eaabb036fb3e90c4983f6e2 100644 (file)
--- a/Documentation/DocBook/media/v4l/compat.xml
+++ b/Documentation/DocBook/media/v4l/compat.xml
@@ -2370,6 +2370,14 @@ that used it. It was originally scheduled for removal in 2.6.35.
         </listitem>
       </orderedlist>
     </section>
+    <section>
+      <title>V4L2 in Linux 3.2</title>
+      <orderedlist>
+        <listitem>
+         <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para>
+        </listitem>
+      </orderedlist>
+    </section>
 
     <section id="other">
       <title>Relation of V4L2 to other Linux multimedia APIs</title>

diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml
index 0d05e8747c12e24da9a2a4cebcdce4826e0858a4..40132c2776476a582bdf0eff818fc81c5f007c0f 100644 (file)
--- a/Documentation/DocBook/media/v4l/v4l2.xml
+++ b/Documentation/DocBook/media/v4l/v4l2.xml
@@ -127,6 +127,13 @@ structs, ioctls) must be noted in more detail in the history chapter
 (compat.xml), along with the possible impact on existing drivers and
 applications. -->
 
+      <revision>
+       <revnumber>3.2</revnumber>
+       <date>2011-08-26</date>
+       <authorinitials>hv</authorinitials>
+       <revremark>Added V4L2_CTRL_FLAG_VOLATILE.</revremark>
+      </revision>
+
       <revision>
        <revnumber>3.1</revnumber>
        <date>2011-06-27</date>
@@ -410,7 +417,7 @@ and discussions on the V4L mailing list.</revremark>
 </partinfo>
 
 <title>Video for Linux Two API Specification</title>
- <subtitle>Revision 3.1</subtitle>
+ <subtitle>Revision 3.2</subtitle>
 
   <chapter id="common">
     &sub-common;

diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
index 677ea646c29fc71c6d8b9970cbb230d1784a46d1..0ac0057a51c4c9cb47da092159b955eb1ff11ad9 100644 (file)
--- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
@@ -406,6 +406,15 @@ flag is typically present for relative controls or action controls where
 writing a value will cause the device to carry out a given action
 (&eg; motor control) but no meaningful value can be returned.</entry>
          </row>
+         <row>
+           <entry><constant>V4L2_CTRL_FLAG_VOLATILE</constant></entry>
+           <entry>0x0080</entry>
+           <entry>This control is volatile, which means that the value of the control
+changes continuously. A typical example would be the current gain value if the device
+is in auto-gain mode. In such a case the hardware calculates the gain value based on
+the lighting conditions which can change over time. Note that setting a new value for
+a volatile control will have no effect. The new value will just be ignored.</entry>
+         </row>
        </tbody>
       </tgroup>
     </table>

diff --git a/include/linux/videodev2.h b/include/linux/videodev2.h
index a5359c6e7577e030dec279bd3e74fd124d1799aa..9d14523487d15cd515704af1afa251e4931df8bd 100644 (file)
--- a/include/linux/videodev2.h
+++ b/include/linux/videodev2.h
@@ -1082,6 +1082,7 @@ struct v4l2_querymenu {
 #define V4L2_CTRL_FLAG_INACTIVE        0x0010
 #define V4L2_CTRL_FLAG_SLIDER          0x0020
 #define V4L2_CTRL_FLAG_WRITE_ONLY      0x0040
+#define V4L2_CTRL_FLAG_VOLATILE                0x0080
 
 /*  Query flag, to be ORed with the control ID */
 #define V4L2_CTRL_FLAG_NEXT_CTRL       0x80000000