From acd2b672b45e557829c1f080e46457586aab9d74 Mon Sep 17 00:00:00 2001 From: Ricardo Ribalda Date: Fri, 20 Mar 2015 11:13:14 -0300 Subject: [PATCH] [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 --- Documentation/DocBook/media/v4l/vidioc-dqevent.xml | 6 +++--- Documentation/DocBook/media/v4l/vidioc-queryctrl.xml | 12 +++++++++++- Documentation/video4linux/v4l2-controls.txt | 4 +++- 3 files changed, 17 insertions(+), 5 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 @@ V4L2_EVENT_CTRL_CH_VALUE 0x0001 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. + changed. Special cases: Volatile controls do no generate this event; + If a control has the V4L2_CTRL_FLAG_EXECUTE_ON_WRITE + flag set, then this event is sent as well, regardless its value. V4L2_EVENT_CTRL_CH_FLAGS 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. +a volatile control will have no effect and no V4L2_EVENT_CTRL_CH_VALUE +will be sent, unless the V4L2_CTRL_FLAG_EXECUTE_ON_WRITE flag +(see below) is also set. Otherwise the new value will just be ignored. V4L2_CTRL_FLAG_HAS_PAYLOAD @@ -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. + + V4L2_CTRL_FLAG_EXECUTE_ON_WRITE + 0x0200 + 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 V4L2_CTRL_TYPE_BUTTON have this flag set. + diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 0f84ce8c9a7b..5517db602f37 100644 --- a/Documentation/video4linux/v4l2-controls.txt +++ b/Documentation/video4linux/v4l2-controls.txt @@ -344,7 +344,9 @@ implement g_volatile_ctrl like this: } Note that you use the 'new value' union as well in g_volatile_ctrl. In general -controls that need to implement g_volatile_ctrl are read-only controls. +controls that need to implement g_volatile_ctrl are read-only controls. If they +are not, a V4L2_EVENT_CTRL_CH_VALUE will not be generated when the control +changes. To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE: -- 2.30.2