From 6055b12ae0f433314cba98f423fb8c5fc211ca8d Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Wed, 11 Jan 2012 07:30:55 -0300 Subject: [PATCH] [media] V4L2 Spec: fix extended control documentation Update the spec to the behavior implemented by the control framework. This should have been documented long ago but for some reason it was never done. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 18 +++++++++++----- Documentation/video4linux/v4l2-controls.txt | 21 ------------------- 2 files changed, 13 insertions(+), 26 deletions(-) diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index 6f1f9a629dc3..b17a7aac6997 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -183,7 +183,12 @@ applications must set the array to zero. __u32 ctrl_class The control class to which all controls belong, see -. +. Drivers that use a kernel framework for handling +controls will also accept a value of 0 here, meaning that the controls can +belong to any control class. Whether drivers support this can be tested by setting +ctrl_class to 0 and calling VIDIOC_TRY_EXT_CTRLS +with a count of 0. If that succeeds, then the driver +supports this feature. __u32 @@ -194,10 +199,13 @@ also be zero. __u32 error_idx - Set by the driver in case of an error. It is the -index of the control causing the error or equal to 'count' when the -error is not associated with a particular control. Undefined when the -ioctl returns 0 (success). + Set by the driver in case of an error. If it is equal +to count, then no actual changes were made to +controls. In other words, the error was not associated with setting a particular +control. If it is another value, then only the controls up to error_idx-1 +were modified and control error_idx is the one that +caused the error. The error_idx value is undefined +if the ioctl returned 0 (success). __u32 diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 26aa0573933e..e2492a9d1027 100644 --- a/Documentation/video4linux/v4l2-controls.txt +++ b/Documentation/video4linux/v4l2-controls.txt @@ -666,27 +666,6 @@ a control of this type whenever the first control belonging to a new control class is added. -Differences from the Spec -========================= - -There are a few places where the framework acts slightly differently from the -V4L2 Specification. Those differences are described in this section. We will -have to see whether we need to adjust the spec or not. - -1) It is no longer required to have all controls contained in a -v4l2_ext_control array be from the same control class. The framework will be -able to handle any type of control in the array. You need to set ctrl_class -to 0 in order to enable this. If ctrl_class is non-zero, then it will still -check that all controls belong to that control class. - -If you set ctrl_class to 0 and count to 0, then it will only return an error -if there are no controls at all. - -2) Clarified the way error_idx works. For get and set it will be equal to -count if nothing was done yet. If it is less than count then only the controls -up to error_idx-1 were successfully applied. - - Proposals for Extensions ========================