From 0568aeeeef467ac6e22d5d549cd50e8c93abf959 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 11 Jan 2013 10:33:30 -0300 Subject: [PATCH] [media] DocBook: improve the error_idx field documentation The documentation of the error_idx field was incomplete and confusing. This patch improves it. Signed-off-by: Hans Verkuil Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- .../DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 47 ++++++++++++++++++---- 1 file changed, 40 insertions(+), 7 deletions(-) diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index 0a4b90f..42ffbff 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -199,13 +199,46 @@ also be zero. __u32 error_idx - 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). + Set by the driver in case of an error. If the error is +associated with a particular control, then error_idx +is set to the index of that control. If the error is not related to a specific +control, or the validation step failed (see below), then +error_idx is set to count. +The value is undefined if the ioctl returned 0 (success). + +Before controls are read from/written to hardware a validation step +takes place: this checks if all controls in the list are valid controls, +if no attempt is made to write to a read-only control or read from a write-only +control, and any other up-front checks that can be done without accessing the +hardware. The exact validations done during this step are driver dependent +since some checks might require hardware access for some devices, thus making +it impossible to do those checks up-front. However, drivers should make a +best-effort to do as many up-front checks as possible. + +This check is done to avoid leaving the hardware in an inconsistent state due +to easy-to-avoid problems. But it leads to another problem: the application needs to +know whether an error came from the validation step (meaning that the hardware +was not touched) or from an error during the actual reading from/writing to hardware. + +The, in hindsight quite poor, solution for that is to set error_idx +to count if the validation failed. This has the +unfortunate side-effect that it is not possible to see which control failed the +validation. If the validation was successful and the error happened while +accessing the hardware, then error_idx is less than +count and only the controls up to +error_idx-1 were read or written correctly, and the +state of the remaining controls is undefined. + +Since VIDIOC_TRY_EXT_CTRLS does not access hardware +there is also no need to handle the validation step in this special way, +so error_idx will just be set to the control that +failed the validation step instead of to count. +This means that if VIDIOC_S_EXT_CTRLS fails with +error_idx set to count, +then you can call VIDIOC_TRY_EXT_CTRLS to try to discover +the actual control that failed the validation step. Unfortunately, there +is no TRY equivalent for VIDIOC_G_EXT_CTRLS. + __u32 -- 2.7.4