From patchwork Mon Jan 7 12:09:47 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 1940911 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork2.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork2.kernel.org (Postfix) with ESMTP id 4B202DF230 for ; Mon, 7 Jan 2013 12:10:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754402Ab3AGMKB (ORCPT ); Mon, 7 Jan 2013 07:10:01 -0500 Received: from smtp-vbr8.xs4all.nl ([194.109.24.28]:3755 "EHLO smtp-vbr8.xs4all.nl" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754004Ab3AGMKB (ORCPT ); Mon, 7 Jan 2013 07:10:01 -0500 Received: from alastor.dyndns.org (166.80-203-20.nextgentel.com [80.203.20.166]) (authenticated bits=0) by smtp-vbr8.xs4all.nl (8.13.8/8.13.8) with ESMTP id r07C9rjG026828 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Mon, 7 Jan 2013 13:09:55 +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 6BFC811E0118; Mon, 7 Jan 2013 13:09:51 +0100 (CET) From: Hans Verkuil To: linux-media@vger.kernel.org Cc: Laurent Pinchart , Hans Verkuil Subject: [REVIEW PATCHv1 1/2] DocBook: improve the error_idx field documentation. Date: Mon, 7 Jan 2013 13:09:47 +0100 Message-Id: <50256813dbb6df25776aed847787d1eac9dbc9fa.1357560529.git.hans.verkuil@cisco.com> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1357560588-5263-1-git-send-email-hverkuil@xs4all.nl> References: <1357560588-5263-1-git-send-email-hverkuil@xs4all.nl> 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 --- .../DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 51 +++++++++++++++++--- 1 file changed, 44 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..c07c657 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -199,13 +199,50 @@ 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, then error_idx is set to count. + +The behavior is different for VIDIOC_G_EXT_CTRLS and +VIDIOC_S_EXT_CTRLS: if +error_idx is equal to count, +then no actual changes were made to the controls. For example, if you try to +write to a read-only control, then VIDIOC_TRY_EXT_CTRLS +will set error_idx to the index of that read-only +control, but VIDIOC_S_EXT_CTRLS will set +error_idx to count instead +and none of the controls in the list will be set. + +The same is true when trying to e.g. read a write-only control: +VIDIOC_G_EXT_CTRLS will set error_idx +to count and none of the controls in the list will +have been retrieved. + +The reason for this behavior is that it is important when setting and getting +controls to do this as atomically as possible, so simple sanity checks like testing +for read-only controls are done first before an attempt is made to apply/retrieve the new +control values to/from the hardware. It is important for an application to know whether +VIDIOC_S_EXT_CTRLS or VIDIOC_G_EXT_CTRLS actually +made changes to controls or not. So if error_idx is equal +to count, then you know that no actual controls were set or +retrieved. In the case of VIDIOC_S_EXT_CTRLS you can call +VIDIOC_TRY_EXT_CTRLS with the same control list to see if the +problem was with a specific control or not (VIDIOC_TRY_EXT_CTRLS +never modifies controls, so that ioctl will just set error_idx +to the control that caused the problem). No such option exists for VIDIOC_G_EXT_CTRLS +though, unfortunately. + +If error_idx as returned by VIDIOC_S_EXT_CTRLS +or VIDIOC_G_EXT_CTRLS is less than count, +then only the controls up to error_idx-1 were modified and control +error_idx is the one that caused the error. In the case of +VIDIOC_S_EXT_CTRLS this might have left the hardware in an +inconsistent state. These types of errors should not normally happen, and such +errors are typically caused by problems in communicating with the hardware. + +Finally, note that the error_idx value is undefined +if the ioctl returned 0 (success). __u32