path: root/Documentation/DocBook
diff options
authorRicardo Ribalda <>2015-03-20 11:13:14 -0300
committerMauro Carvalho Chehab <>2015-04-08 06:35:16 -0300
commitacd2b672b45e557829c1f080e46457586aab9d74 (patch)
tree9dc5ba94ea6425877edd6f94e254010f938b7ba7 /Documentation/DocBook
parent45f014c5264f5e68ef0e51b36f4ef5ede3d18397 (diff)
[media] media/Documentation: New flag EXECUTE_ON_WRITE
Document new flag V4L2_CTRL_FLAG_EXECUTE_ON_WRITE, and the new behavior of CH_VALUE event on VOLATILE controls. Signed-off-by: Ricardo Ribalda Delgado <> Signed-off-by: Hans Verkuil <> Signed-off-by: Mauro Carvalho Chehab <>
Diffstat (limited to 'Documentation/DocBook')
2 files changed, 14 insertions, 4 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
index a31eea07d455..50ccd33948c1 100644
--- a/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-dqevent.xml
@@ -425,9 +425,9 @@
<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>
+ changed. Special cases: Volatile controls do no generate this event;
+ If a control has the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant>
+ flag set, then this event is sent as well, regardless its value.</entry>
diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
index 2bd98fd7a4e5..dc83ad70f8dc 100644
--- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml
@@ -600,7 +600,9 @@ writing a value will cause the device to carry out a given action
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>
+a volatile control will have no effect and no <constant>V4L2_EVENT_CTRL_CH_VALUE</constant>
+will be sent, unless the <constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant> flag
+(see below) is also set. Otherwise the new value will just be ignored.</entry>
@@ -610,6 +612,14 @@ using one of the pointer fields of &v4l2-ext-control;. This flag is set for cont
that are an array, string, or have a compound type. In all cases you have to set a
pointer to memory containing the payload of the control.</entry>
+ <row>
+ <entry><constant>V4L2_CTRL_FLAG_EXECUTE_ON_WRITE</constant></entry>
+ <entry>0x0200</entry>
+ <entry>The value provided to the control will be propagated to the driver
+even if remains constant. This is required when the control represents an action
+on the hardware. For example: clearing an error flag or triggering the flash. All the
+controls of the type <constant>V4L2_CTRL_TYPE_BUTTON</constant> have this flag set.</entry>
+ </row>