[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 <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
This commit is contained in:
Hans Verkuil 2012-01-11 07:30:55 -03:00 committed by Mauro Carvalho Chehab
parent 047a01fdc8
commit 6055b12ae0
2 changed files with 13 additions and 26 deletions

View File

@ -183,7 +183,12 @@ applications must set the array to zero.</entry>
<entry>__u32</entry>
<entry><structfield>ctrl_class</structfield></entry>
<entry>The control class to which all controls belong, see
<xref linkend="ctrl-class" />.</entry>
<xref linkend="ctrl-class" />. 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
<structfield>ctrl_class</structfield> to 0 and calling <constant>VIDIOC_TRY_EXT_CTRLS</constant>
with a <structfield>count</structfield> of 0. If that succeeds, then the driver
supports this feature.</entry>
</row>
<row>
<entry>__u32</entry>
@ -194,10 +199,13 @@ also be zero.</entry>
<row>
<entry>__u32</entry>
<entry><structfield>error_idx</structfield></entry>
<entry>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).</entry>
<entry>Set by the driver in case of an error. If it is equal
to <structfield>count</structfield>, 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 <structfield>error_idx-1</structfield>
were modified and control <structfield>error_idx</structfield> is the one that
caused the error. The <structfield>error_idx</structfield> value is undefined
if the ioctl returned 0 (success).</entry>
</row>
<row>
<entry>__u32</entry>

View File

@ -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
========================