From patchwork Fri Jan 11 13:57:01 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 1966271 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork1.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork1.kernel.org (Postfix) with ESMTP id 17C463FE37 for ; Fri, 11 Jan 2013 13:57:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753238Ab3AKN5R (ORCPT ); Fri, 11 Jan 2013 08:57:17 -0500 Received: from smtp-vbr6.xs4all.nl ([194.109.24.26]:1497 "EHLO smtp-vbr6.xs4all.nl" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752409Ab3AKN5Q (ORCPT ); Fri, 11 Jan 2013 08:57:16 -0500 Received: from alastor.dyndns.org (166.80-203-20.nextgentel.com [80.203.20.166] (may be forged)) (authenticated bits=0) by smtp-vbr6.xs4all.nl (8.13.8/8.13.8) with ESMTP id r0BDv9Pl006366 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Fri, 11 Jan 2013 14:57:10 +0100 (CET) (envelope-from hverkuil@xs4all.nl) Received: from tschai.cisco.com (64-103-25-233.cisco.com [64.103.25.233]) (Authenticated sender: hans) by alastor.dyndns.org (Postfix) with ESMTPSA id 9CB491700068; Fri, 11 Jan 2013 14:57:07 +0100 (CET) From: Hans Verkuil To: linux-media@vger.kernel.org Cc: Laurent Pinchart , Hans Verkuil Subject: [REVIEW PATCHv3 2/3] DocBook: improve the error_idx field documentation. Date: Fri, 11 Jan 2013 14:57:01 +0100 Message-Id: <3a86e97ac8eb93a9110ed5fbb7eb5e825bdcdef5.1357912476.git.hans.verkuil@cisco.com> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1357912622-24736-1-git-send-email-hverkuil@xs4all.nl> References: <1357912622-24736-1-git-send-email-hverkuil@xs4all.nl> In-Reply-To: <66daf776429bc348c156f96eb36141588087783b.1357912476.git.hans.verkuil@cisco.com> References: <66daf776429bc348c156f96eb36141588087783b.1357912476.git.hans.verkuil@cisco.com> X-Virus-Scanned: by XS4ALL Virus Scanner Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org From: Hans Verkuil The documentation of the error_idx field was incomplete and confusing. This patch improves it. Signed-off-by: Hans Verkuil Acked-by: Laurent Pinchart --- .../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