From 715bfb3e1f0ca0f6c6bd7805d90f31325fb61b72 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Tue, 10 Jun 2014 07:21:04 -0300 Subject: [media] DocBook media: document VIDIOC_QUERY_EXT_CTRL Document the new VIDIOC_QUERY_EXT_CTRL ioctl. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../DocBook/media/v4l/vidioc-queryctrl.xml | 211 +++++++++++++++++---- 1 file changed, 175 insertions(+), 36 deletions(-) (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml b/Documentation/DocBook/media/v4l/vidioc-queryctrl.xml index e6645b996558..04589e53f38b 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 @@ -19,6 +20,14 @@ struct v4l2_queryctrl *argp + + + int ioctl + int fd + int request + struct v4l2_query_ext_ctrl *argp + + int ioctl @@ -42,7 +51,7 @@ request - VIDIOC_QUERYCTRL, VIDIOC_QUERYMENU + VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL, VIDIOC_QUERYMENU @@ -89,9 +98,23 @@ prematurely end the enumeration). When the application ORs id with 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. +next supported non-compound control, or EINVAL +if there is none. In addition, the V4L2_CTRL_FLAG_NEXT_COMPOUND +flag can be specified to enumerate all compound controls (i.e. controls +with type ≥ V4L2_CTRL_COMPOUND_TYPES). Specify both +V4L2_CTRL_FLAG_NEXT_CTRL and +V4L2_CTRL_FLAG_NEXT_COMPOUND in order to enumerate +all controls, compound or not. Drivers which do not support these flags yet +always return EINVAL. + + The VIDIOC_QUERY_EXT_CTRL ioctl was +introduced in order to better support controls that can use compound +types, and to expose additional 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. Additional information is required for menu controls: the names of the menu items. To query them applications set the @@ -142,38 +165,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 +200,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 +222,125 @@ 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-compound control with a higher ID. When the +ID is ORed with V4L2_CTRL_FLAG_NEXT_COMPOUND the driver +clears the flag and returns the first compound control with a higher ID. +Set both to get the first control (compound 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. + + + __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 + elem_size + The size in bytes of a single element of the array. +Given a char pointer p to a 3-dimensional array you can find the +position of cell (z, y, x) as follows: +p + ((z * dims[1] + y) * dims[0] + x) * elem_size. elem_size +is always valid, also when the control isn't an array. For string controls +elem_size is equal to maximum + 1. + + + + __u32 + elems + The number of elements in the N-dimensional array. If this control +is not an array, then elems is 1. The elems +field can never be 0. + + + __u32 + nr_of_dims + The number of dimension in the N-dimensional array. If this control +is not an array, then this field is 0. + + + __u32 + dims[V4L2_CTRL_MAX_DIMS] + The size of each dimension. The first nr_of_dims +elements of this array must be non-zero, all remaining elements must be zero. + + + __u32 + reserved[32] + Reserved for future extensions. Applications and drivers +must set the array to zero. + + + +
+ struct <structname>v4l2_querymenu</structname> @@ -347,11 +475,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 +581,14 @@ 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_HAS_PAYLOAD + 0x0100 + 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 an array, string, or have a compound type. In all cases you have to set a +pointer to memory containing the payload of the control. +
-- cgit