From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from mailout2.w1.samsung.com ([210.118.77.12]:62291 "EHLO mailout2.w1.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752763AbaAWRYF (ORCPT ); Thu, 23 Jan 2014 12:24:05 -0500 Received: from eucpsbgm2.samsung.com (unknown [203.254.199.245]) by mailout2.w1.samsung.com (Oracle Communications Messaging Server 7u4-24.01(7.0.4.24.0) 64bit (built Nov 17 2011)) with ESMTP id <0MZV001OE7009Z50@mailout2.w1.samsung.com> for linux-media@vger.kernel.org; Thu, 23 Jan 2014 17:24:00 +0000 (GMT) Message-id: <52E15030.70002@samsung.com> Date: Thu, 23 Jan 2014 18:24:00 +0100 From: Sylwester Nawrocki MIME-version: 1.0 To: Hans Verkuil , linux-media@vger.kernel.org Cc: m.chehab@samsung.com, laurent.pinchart@ideasonboard.com, t.stanislaws@samsung.com, Hans Verkuil Subject: Re: [RFCv2 PATCH 18/21] DocBook media: document VIDIOC_QUERY_EXT_CTRL. References: <1390221974-28194-1-git-send-email-hverkuil@xs4all.nl> <1390221974-28194-19-git-send-email-hverkuil@xs4all.nl> In-reply-to: <1390221974-28194-19-git-send-email-hverkuil@xs4all.nl> Content-type: text/plain; charset=ISO-8859-1 Content-transfer-encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: On 20/01/14 13:46, Hans Verkuil wrote: > From: Hans Verkuil > > Signed-off-by: Hans Verkuil > --- > .../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 s/addition/additional ? > +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 s/"set which"/"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 + linkend="v4l2-ctrl-type" />. > + > + > + 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 + linkend="control-flags" />. > + > + > + __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. > + > > >
> Reviewed-by: Sylwester Nawrocki -- Regards, Sylwester