From patchwork Mon Jan 20 12:46:12 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 3512471 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 22F07C02DC for ; Mon, 20 Jan 2014 12:47:22 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 0A71E20108 for ; Mon, 20 Jan 2014 12:47:21 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id D1881200C6 for ; Mon, 20 Jan 2014 12:47:19 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753519AbaATMrQ (ORCPT ); Mon, 20 Jan 2014 07:47:16 -0500 Received: from smtp-vbr13.xs4all.nl ([194.109.24.33]:4007 "EHLO smtp-vbr13.xs4all.nl" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751891AbaATMqy (ORCPT ); Mon, 20 Jan 2014 07:46:54 -0500 Received: from tschai.lan (173-38-208-169.cisco.com [173.38.208.169]) (authenticated bits=0) by smtp-vbr13.xs4all.nl (8.13.8/8.13.8) with ESMTP id s0KCkfTK037837; Mon, 20 Jan 2014 13:46:42 +0100 (CET) (envelope-from hverkuil@xs4all.nl) Received: from tschai.cisco.com (localhost [127.0.0.1]) by tschai.lan (Postfix) with ESMTPSA id F21E12A00B4; Mon, 20 Jan 2014 13:46:16 +0100 (CET) From: Hans Verkuil To: linux-media@vger.kernel.org Cc: m.chehab@samsung.com, laurent.pinchart@ideasonboard.com, t.stanislaws@samsung.com, Hans Verkuil Subject: [RFCv2 PATCH 19/21] DocBook media: update VIDIOC_G/S/TRY_EXT_CTRLS. Date: Mon, 20 Jan 2014 13:46:12 +0100 Message-Id: <1390221974-28194-20-git-send-email-hverkuil@xs4all.nl> X-Mailer: git-send-email 1.8.5.2 In-Reply-To: <1390221974-28194-1-git-send-email-hverkuil@xs4all.nl> References: <1390221974-28194-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 X-Spam-Status: No, score=-7.5 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Hans Verkuil Signed-off-by: Hans Verkuil --- .../DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 43 ++++++++++++++++++---- 1 file changed, 35 insertions(+), 8 deletions(-) diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml index b3bb957..bb383b9 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml @@ -72,23 +72,30 @@ initialize the id, size and reserved2 fields of each &v4l2-ext-control; and call the VIDIOC_G_EXT_CTRLS ioctl. String controls controls -must also set the string field. +must also set the string field. Controls +of complex types (V4L2_CTRL_FLAG_IS_PTR is set) +must set the p field. If the size is too small to receive the control result (only relevant for pointer-type controls like strings), then the driver will set size to a valid value and return an &ENOSPC;. You should re-allocate the -string memory to this new size and try again. It is possible that the -same issue occurs again if the string has grown in the meantime. It is +memory to this new size and try again. For the string type it is possible that +the same issue occurs again if the string has grown in the meantime. It is recommended to call &VIDIOC-QUERYCTRL; first and use maximum+1 as the new size value. It is guaranteed that that is sufficient memory. + For matrices it is possible to only get the first X +elements by setting size to X * elem_size, where +elem_size is obtained by calling &VIDIOC-QUERY-EXT-CTRL;. +Matrix elements are returned row-by-row. + To change the value of a set of controls applications initialize the id, size, reserved2 and -value/string fields of each &v4l2-ext-control; and +value/value64/string/p fields of each &v4l2-ext-control; and call the VIDIOC_S_EXT_CTRLS ioctl. The controls will only be set if all control values are valid. @@ -96,11 +103,17 @@ valid. To check if a set of controls have correct values applications initialize the id, size, reserved2 and -value/string fields of each &v4l2-ext-control; and +value/value64/string/p fields of each &v4l2-ext-control; and call the VIDIOC_TRY_EXT_CTRLS ioctl. It is up to the driver whether wrong values are automatically adjusted to a valid value or if an error is returned. + For matrices it is possible to only set or check only the first +X elements by setting size to X * elem_size, +where elem_size is obtained by calling &VIDIOC-QUERY-EXT-CTRL;. +Matrix elements are set row-by-row. Matrix elements that are not explicitly +set will be initialized to their default value. + When the id or ctrl_class is invalid drivers return an &EINVAL;. When the value is out of bounds drivers can choose to take @@ -158,19 +171,33 @@ applications must set the array to zero. __s32 value - New value or current value. + New value or current value. Valid if this control is not of +type V4L2_CTRL_TYPE_INTEGER64 and +V4L2_CTRL_FLAG_IS_PTR is not set. __s64 value64 - New value or current value. + New value or current value. Valid if this control is of +type V4L2_CTRL_TYPE_INTEGER64 and +V4L2_CTRL_FLAG_IS_PTR is not set. char * string - A pointer to a string. + A pointer to a string. Valid if this control is of +type V4L2_CTRL_TYPE_STRING. + + + + void * + p + A pointer to a complex type which can be a matrix and/or a +complex type (the control's type is >= V4L2_CTRL_COMPLEX_TYPES). +Valid if V4L2_CTRL_FLAG_IS_PTR is set for this control. +