[media] V4L2 spec: document control events

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/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index 4e0a7cc30812d9cc5254ad8c24ba9ed4f5e6338a..b8c4f7657d69cc96577a4a30c81dd2b2ae229eea 100644 (file)
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -79,6 +79,13 @@
            <entry>Event data for event V4L2_EVENT_VSYNC.
             </entry>
          </row>
+         <row>
+           <entry></entry>
+           <entry>&v4l2-event-ctrl;</entry>
+            <entry><structfield>ctrl</structfield></entry>
+           <entry>Event data for event V4L2_EVENT_CTRL.
+            </entry>
+         </row>
          <row>
            <entry></entry>
            <entry>__u8</entry>
@@ -109,9 +116,17 @@
             <entry></entry>
            <entry>Event timestamp.</entry>
          </row>
+         <row>
+           <entry>u32</entry>
+           <entry><structfield>id</structfield></entry>
+            <entry></entry>
+           <entry>The ID associated with the event source. If the event does not
+               have an associated ID (this depends on the event type), then this
+               is 0.</entry>
+         </row>
          <row>
            <entry>__u32</entry>
-           <entry><structfield>reserved</structfield>[9]</entry>
+           <entry><structfield>reserved</structfield>[8]</entry>
             <entry></entry>
            <entry>Reserved for future extensions. Drivers must set
            the array to zero.</entry>

diff --git a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
index 8b501791aa6801e74a4c86f74437b5b0aac61526..975f603a42eeed9faa6bd816ba1bee83ed3438fa 100644 (file)
--- a/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
@@ -64,7 +64,19 @@
          </row>
          <row>
            <entry>__u32</entry>
-           <entry><structfield>reserved</structfield>[7]</entry>
+           <entry><structfield>id</structfield></entry>
+           <entry>ID of the event source. If there is no ID associated with
+               the event source, then set this to 0. Whether or not an event
+               needs an ID depends on the event type.</entry>
+         </row>
+         <row>
+           <entry>__u32</entry>
+           <entry><structfield>flags</structfield></entry>
+           <entry>Event flags, see <xref linkend="event-flags" />.</entry>
+         </row>
+         <row>
+           <entry>__u32</entry>
+           <entry><structfield>reserved</structfield>[5]</entry>
            <entry>Reserved for future extensions. Drivers and applications
            must set the array to zero.</entry>
          </row>
@@ -99,6 +111,23 @@
            when the last of the MPEG stream has been decoded.
            </entry>
          </row>
+         <row>
+           <entry><constant>V4L2_EVENT_CTRL</constant></entry>
+           <entry>3</entry>
+           <entry>This event requires that the <structfield>id</structfield>
+               matches the control ID from which you want to receive events.
+               This event is triggered if the control's value changes, if a
+               button control is pressed or if the control's flags change.
+               This event has &v4l2-event-ctrl; associated with it. This struct
+               contains much of the same information as &v4l2-queryctrl; and
+               &v4l2-control;.
+
+               If the event is generated due to a call to &VIDIOC-S-CTRL; or
+               &VIDIOC-S-EXT-CTRLS;, then the event will not be sent to
+               the file handle that called the ioctl function. This prevents
+               nasty feedback loops.
+           </entry>
+         </row>
          <row>
            <entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
            <entry>0x08000000</entry>
@@ -108,6 +137,23 @@
       </tgroup>
     </table>
 
+    <table pgwide="1" frame="none" id="event-flags">
+      <title>Event Flags</title>
+      <tgroup cols="3">
+       &cs-def;
+       <tbody valign="top">
+         <row>
+           <entry><constant>V4L2_EVENT_SUB_FL_SEND_INITIAL</constant></entry>
+           <entry>0x0001</entry>
+           <entry>When this event is subscribed an initial event will be sent
+               containing the current status. This only makes sense for events
+               that are triggered by a status change. Other events will ignore
+               this flag.</entry>
+         </row>
+       </tbody>
+      </tgroup>
+    </table>
+
     <table frame="none" pgwide="1" id="v4l2-event-vsync">
       <title>struct <structname>v4l2_event_vsync</structname></title>
       <tgroup cols="3">
@@ -122,6 +168,100 @@
       </tgroup>
     </table>
 
+    <table frame="none" pgwide="1" id="v4l2-event-ctrl">
+      <title>struct <structname>v4l2_event_ctrl</structname></title>
+      <tgroup cols="4">
+       &cs-str;
+       <tbody valign="top">
+         <row>
+           <entry>__u32</entry>
+           <entry><structfield>changes</structfield></entry>
+           <entry></entry>
+           <entry>A bitmask that tells what has changed. See <xref linkend="changes-flags" />.</entry>
+         </row>
+         <row>
+           <entry>__u32</entry>
+           <entry><structfield>type</structfield></entry>
+           <entry></entry>
+           <entry>The type of the control. See &v4l2-ctrl-type;.</entry>
+         </row>
+         <row>
+           <entry>union (anonymous)</entry>
+           <entry></entry>
+           <entry></entry>
+           <entry></entry>
+         </row>
+         <row>
+           <entry></entry>
+           <entry>__s32</entry>
+           <entry><structfield>value</structfield></entry>
+           <entry>The 32-bit value of the control for 32-bit control types.
+               This is 0 for string controls since the value of a string
+               cannot be passed using &VIDIOC-DQEVENT;.</entry>
+         </row>
+         <row>
+           <entry></entry>
+           <entry>__s64</entry>
+           <entry><structfield>value64</structfield></entry>
+           <entry>The 64-bit value of the control for 64-bit control types.</entry>
+         </row>
+         <row>
+           <entry>__u32</entry>
+           <entry><structfield>flags</structfield></entry>
+           <entry></entry>
+           <entry>The control flags. See <xref linkend="control-flags" />.</entry>
+         </row>
+         <row>
+           <entry>__s32</entry>
+           <entry><structfield>minimum</structfield></entry>
+           <entry></entry>
+           <entry>The minimum value of the control. See &v4l2-queryctrl;.</entry>
+         </row>
+         <row>
+           <entry>__s32</entry>
+           <entry><structfield>maximum</structfield></entry>
+           <entry></entry>
+           <entry>The maximum value of the control. See &v4l2-queryctrl;.</entry>
+         </row>
+         <row>
+           <entry>__s32</entry>
+           <entry><structfield>step</structfield></entry>
+           <entry></entry>
+           <entry>The step value of the control. See &v4l2-queryctrl;.</entry>
+         </row>
+         <row>
+           <entry>__s32</entry>
+           <entry><structfield>default_value</structfield></entry>
+           <entry></entry>
+           <entry>The default value value of the control. See &v4l2-queryctrl;.</entry>
+         </row>
+       </tbody>
+      </tgroup>
+    </table>
+
+    <table pgwide="1" frame="none" id="changes-flags">
+      <title>Changes</title>
+      <tgroup cols="3">
+       &cs-def;
+       <tbody valign="top">
+         <row>
+           <entry><constant>V4L2_EVENT_CTRL_CH_VALUE</constant></entry>
+           <entry>0x0001</entry>
+           <entry>This control event was triggered because the value of the control
+               changed. Special case: if a button control is pressed, then this
+               event is sent as well, even though there is not explicit value
+               associated with a button control.</entry>
+         </row>
+         <row>
+           <entry><constant>V4L2_EVENT_CTRL_CH_FLAGS</constant></entry>
+           <entry>0x0002</entry>
+           <entry>This control event was triggered because the control flags
+               changed.</entry>
+         </row>
+       </tbody>
+      </tgroup>
+    </table>
+
   </refsect1>
 </refentry>
 <!--