From patchwork Mon Jan 20 12:46:11 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 3512481 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork1.web.kernel.org (Postfix) with ESMTP id EBED89F2D6 for ; Mon, 20 Jan 2014 12:47:23 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 82E5E20108 for ; Mon, 20 Jan 2014 12:47:22 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 0A4D4200F2 for ; Mon, 20 Jan 2014 12:47:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753579AbaATMrR (ORCPT ); Mon, 20 Jan 2014 07:47:17 -0500 Received: from smtp-vbr14.xs4all.nl ([194.109.24.34]:4944 "EHLO smtp-vbr14.xs4all.nl" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753376AbaATMqx (ORCPT ); Mon, 20 Jan 2014 07:46:53 -0500 Received: from tschai.lan (173-38-208-169.cisco.com [173.38.208.169]) (authenticated bits=0) by smtp-vbr14.xs4all.nl (8.13.8/8.13.8) with ESMTP id s0KCke5q062598; 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 E61A42A00B3; 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 18/21] DocBook media: document VIDIOC_QUERY_EXT_CTRL. Date: Mon, 20 Jan 2014 13:46:11 +0100 Message-Id: <1390221974-28194-19-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 Reviewed-by: Sylwester Nawrocki --- .../DocBook/media/v4l/vidioc-queryctrl.xml | 223 +++++++++++++++++---- 1 file changed, 189 insertions(+), 34 deletions(-) diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index e6645b9..5e93c30 100644 --- a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml +++ b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml @@ -1,11 +1,12 @@ - ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU + ioctl VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU &manvol; VIDIOC_QUERYCTRL + VIDIOC_QUERY_EXT_CTRL VIDIOC_QUERYMENU Enumerate controls and menu control items @@ -24,6 +25,14 @@ int ioctl int fd int request + struct v4l2_query_ext_ctrl *argp + + + + + int ioctl + int fd + int request struct v4l2_querymenu *argp @@ -42,7 +51,7 @@ request - VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU + VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU @@ -91,7 +100,26 @@ prematurely end the enumeration). V4L2_CTRL_FLAG_NEXT_CTRL the driver returns the next supported control, or EINVAL if there is none. Drivers which do not support this flag yet always return -EINVAL. +EINVAL. Hidden controls (i.e. controls +with the V4L2_CTRL_FLAG_HIDDEN flag set) are +skipped when using the V4L2_CTRL_FLAG_NEXT_CTRL +flag. Use the VIDIOC_QUERY_EXT_CTRL for that. + + The VIDIOC_QUERY_EXT_CTRL ioctl was +introduced in order to better support controls that can use complex +types, and to expose addition control information that cannot be +returned in &v4l2-queryctrl; since that structure is full. + + VIDIOC_QUERY_EXT_CTRL is used in the +same way as VIDIOC_QUERYCTRL, except that the +reserved array must be zeroed as well. +In addition, the V4L2_CTRL_FLAG_NEXT_HIDDEN flag +can be specified to enumerate all hidden controls (i.e. controls +with the V4L2_CTRL_FLAG_HIDDEN flag set which +includes all controls with complex types). Specify both +V4L2_CTRL_FLAG_NEXT_CTRL and +V4L2_CTRL_FLAG_NEXT_HIDDEN in order to enumerate +all controls, hidden or not. Additional information is required for menu controls: the names of the menu items. To query them applications set the @@ -142,38 +170,23 @@ string. This information is intended for the user. __s32 minimum Minimum value, inclusive. This field gives a lower -bound for V4L2_CTRL_TYPE_INTEGER controls and the -lowest valid index for V4L2_CTRL_TYPE_MENU controls. -For V4L2_CTRL_TYPE_STRING controls the minimum value -gives the minimum length of the string. This length does not include the terminating -zero. It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note that this is a -signed value. +bound for the control. See &v4l2-ctrl-type; how the minimum value is to +be used for each possible control type. Note that this a signed 32-bit value. __s32 maximum Maximum value, inclusive. This field gives an upper -bound for V4L2_CTRL_TYPE_INTEGER controls and the -highest valid index for V4L2_CTRL_TYPE_MENU -controls. For V4L2_CTRL_TYPE_BITMASK controls it is the -set of usable bits. -For V4L2_CTRL_TYPE_STRING controls the maximum value -gives the maximum length of the string. This length does not include the terminating -zero. It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note that this is a -signed value. +bound for the control. See &v4l2-ctrl-type; how the maximum value is to +be used for each possible control type. Note that this a signed 32-bit value. __s32 step - This field gives a step size for -V4L2_CTRL_TYPE_INTEGER controls. For -V4L2_CTRL_TYPE_STRING controls this field refers to -the string length that has to be a multiple of this step size. -It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 -controls.Generally drivers should not scale hardware + This field gives a step size for the control. +See &v4l2-ctrl-type; how the step value is to be used for each possible +control type. Note that this an unsigned 32-bit value. +Generally drivers should not scale hardware control values. It may be necessary for example when the name or id imply a particular unit and the hardware actually accepts only multiples of @@ -192,10 +205,11 @@ be always positive. default_value The default value of a V4L2_CTRL_TYPE_INTEGER, -_BOOLEAN or _MENU control. -Not valid for other types of controls. Drivers reset controls only -when the driver is loaded, not later, in particular not when the -func-open; is called. +_BOOLEAN, _BITMASK, +_MENU or _INTEGER_MENU control. +Not valid for other types of controls. +Note that drivers reset controls to their default value only when the +driver is first loaded, never afterwards. __u32 @@ -213,6 +227,129 @@ the array to zero. + + struct <structname>v4l2_query_ext_ctrl</structname> + + &cs-str; + + + __u32 + id + Identifies the control, set by the application. See + for predefined IDs. When the ID is ORed +with V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the +flag and returns the first non-hidden control with a higher ID. When the +ID is ORed with V4L2_CTRL_FLAG_NEXT_HIDDEN the driver +clears the flag and returns the first hidden control with a higher ID. +Set both to get the first control (hidden or not) with a higher ID. + + + __u32 + type + Type of control, see . + + + char + name[32] + Name of the control, a NUL-terminated ASCII +string. This information is intended for the user. + + + char + unit[32] + The name of the unit of the control's value, a NUL-terminated ASCII +string. This information is intended for the user. This may be an empty string if no +unit is known or if it is not applicable to this particular control. + + + __s64 + minimum + Minimum value, inclusive. This field gives a lower +bound for the control. See &v4l2-ctrl-type; how the minimum value is to +be used for each possible control type. Note that this a signed 64-bit value. + + + __s64 + maximum + Maximum value, inclusive. This field gives an upper +bound for the control. See &v4l2-ctrl-type; how the maximum value is to +be used for each possible control type. Note that this a signed 64-bit value. + + + __u64 + step + This field gives a step size for the control. +See &v4l2-ctrl-type; how the step value is to be used for each possible +control type. Note that this an unsigned 64-bit value. +Generally drivers should not scale hardware +control values. It may be necessary for example when the +name or id imply +a particular unit and the hardware actually accepts only multiples of +said unit. If so, drivers must take care values are properly rounded +when scaling, such that errors will not accumulate on repeated +read-write cycles.This field gives the smallest change of +an integer control actually affecting hardware. Often the information +is needed when the user can change controls by keyboard or GUI +buttons, rather than a slider. When for example a hardware register +accepts values 0-511 and the driver reports 0-65535, step should be +128. + + + __s64 + default_value + The default value of a +V4L2_CTRL_TYPE_INTEGER, _INTEGER64, +_BOOLEAN, _BITMASK, +_MENU or _INTEGER_MENU control. +Not valid for other types of controls. +Note that drivers reset controls to their default value only when the +driver is first loaded, never afterwards. + + + + __u32 + flags + Control flags, see . + + + __u32 + cols + The number of columns in the matrix. If this control +is not a matrix, then both cols and +rows are 1. cols +can never be 0. + + + __u32 + rows + The number of rows in the matrix. If this control +is not a matrix, then both cols and +rows are 1. rows +can never be 0. + + + __u32 + elem_size + The size in bytes of a single element of the matrix. +Given a char pointer p to the matrix you can find the +position of cell (y, x) as follows: +p + (y * cols + x) * elem_size. elem_size +is always valid, also when the control isn't a matrix. For string controls +elem_size is equal to maximum + 1. + + + + __u32 + reserved[17] + Reserved for future extensions. Applications and drivers +must set the array to zero. + + + +
+ struct <structname>v4l2_querymenu</structname> @@ -347,11 +484,14 @@ Drivers must ignore the value passed with V4L2_CTRL_TYPE_INTEGER64 - n/a - n/a - n/a + any + any + any A 64-bit integer valued control. Minimum, maximum -and step size cannot be queried. +and step size cannot be queried using VIDIOC_QUERYCTRL. +Only VIDIOC_QUERY_EXT_CTRL can retrieve the 64-bit +min/max/step values, they should be interpreted as n/a when using +VIDIOC_QUERYCTRL. V4L2_CTRL_TYPE_STRING @@ -450,6 +590,21 @@ is in auto-gain mode. In such a case the hardware calculates the gain value base the lighting conditions which can change over time. Note that setting a new value for a volatile control will have no effect. The new value will just be ignored. + + V4L2_CTRL_FLAG_HIDDEN + 0x0100 + This control is hidden and should not be shown in a GUI application. +Hidden controls are skipped when enumerating them using V4L2_CTRL_FLAG_NEXT_CTRL, +and they can only be enumerated by using the V4L2_CTRL_FLAG_NEXT_HIDDEN +flag. All controls that have a complex type have this flag set. + + + V4L2_CTRL_FLAG_IS_PTR + 0x0200 + This control has a pointer type, so its value has to be accessed +using one of the pointer fields of &v4l2-ext-control;. This flag is set for controls +that are a matrix, string, or have a complex type. +