From a4c8c262f8ae71a842585d00db9fc10014061ddf Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Fri, 4 Apr 2014 08:14:55 -0300 Subject: [PATCH] [media] DocBook media: update VIDIOC_G/S/TRY_EXT_CTRLS Document the support for the new compound type controls. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- .../DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 37 +++++++++++++++---- 1 file changed, 29 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 e9f6735c0823..2a157b3f2ab2 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 compound types (V4L2_CTRL_FLAG_HAS_PAYLOAD is set) +must set the ptr 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. + N-dimensional arrays are set and retrieved row-by-row. You cannot set a partial +array, all elements have to be set or retrieved. The total size is calculated +as elems * elem_size. +These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;. + 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/ptr 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,7 +103,7 @@ 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/ptr 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. @@ -158,19 +165,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_HAS_PAYLOAD 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_HAS_PAYLOAD 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 * + ptr + A pointer to a compound type which can be an N-dimensional array and/or a +compound type (the control's type is >= V4L2_CTRL_COMPOUND_TYPES). +Valid if V4L2_CTRL_FLAG_HAS_PAYLOAD is set for this control. + -- 2.20.1