From 31901a2ad985c7839b68b5b43788d5d62ea32f58 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sun, 2 Aug 2009 11:58:43 +0200 Subject: v4l2-spec: document the new string control type. From: Hans Verkuil Priority: normal Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- v4l2-spec/Makefile | 1 + v4l2-spec/compat.sgml | 3 ++ v4l2-spec/controls.sgml | 3 +- v4l2-spec/v4l2.sgml | 4 +-- v4l2-spec/vidioc-g-ext-ctrls.sgml | 72 ++++++++++++++++++++++++++++++++------- v4l2-spec/vidioc-queryctrl.sgml | 42 +++++++++++++++++------ 6 files changed, 98 insertions(+), 27 deletions(-) diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile index 616445137..3b4c321c4 100644 --- a/v4l2-spec/Makefile +++ b/v4l2-spec/Makefile @@ -307,6 +307,7 @@ ERRORS = \ EINVAL \ ENFILE \ ENOMEM \ + ENOSPC \ ENOTTY \ ENXIO \ EMFILE \ diff --git a/v4l2-spec/compat.sgml b/v4l2-spec/compat.sgml index bcc372c18..c18ddf3db 100644 --- a/v4l2-spec/compat.sgml +++ b/v4l2-spec/compat.sgml @@ -2303,6 +2303,9 @@ more information. Added new capabilities for modulators and RDS encoders. + + Added support for string controls. + diff --git a/v4l2-spec/controls.sgml b/v4l2-spec/controls.sgml index a806eddcd..dbe4f6f86 100644 --- a/v4l2-spec/controls.sgml +++ b/v4l2-spec/controls.sgml @@ -492,8 +492,7 @@ supported. The control array is a &v4l2-ext-control; array. The v4l2_ext_control structure is very similar to &v4l2-control;, except for the fact that it also allows for 64-bit -values and pointers to be passed (although the latter is not yet used -anywhere). +values and pointers to be passed. It is important to realize that due to the flexibility of controls it is necessary to check whether the control you want to set diff --git a/v4l2-spec/v4l2.sgml b/v4l2-spec/v4l2.sgml index a433a1fc2..fe13602f7 100644 --- a/v4l2-spec/v4l2.sgml +++ b/v4l2-spec/v4l2.sgml @@ -159,10 +159,10 @@ applications. --> 0.26 - 2009-06-15 + 2009-07-23 hv Finalized the RDS capture API. Added modulator and RDS encoder -capabilities. +capabilities. Added support for string controls. diff --git a/v4l2-spec/vidioc-g-ext-ctrls.sgml b/v4l2-spec/vidioc-g-ext-ctrls.sgml index 510520254..44a8f5575 100644 --- a/v4l2-spec/vidioc-g-ext-ctrls.sgml +++ b/v4l2-spec/vidioc-g-ext-ctrls.sgml @@ -68,20 +68,35 @@ initialize the &v4l2-ext-control; array pointed to by the controls fields. To get the current value of a set of controls applications -initialize the id field of each -&v4l2-ext-control; and call the -VIDIOC_G_EXT_CTRLS ioctl. +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. + + 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 +recommended to call &VIDIOC-QUERYCTRL; first and use +maximum+1 as the new size +value. It is guaranteed that that is sufficient memory. + To change the value of a set of controls applications -initialize the id and -value fields of a &v4l2-ext-control; and +initialize the id, size, +reserved2 and +value/string 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. - To check if the a set of controls have correct values -applications initialize the id and -value fields of a &v4l2-ext-control; and + 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 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. @@ -112,7 +127,23 @@ application. __u32 - reserved2[2] + size + + The total size in bytes of the payload of this +control. This is normally 0, but for pointer controls this should be +set to the size of the memory containing the payload, or that will +receive the payload. If VIDIOC_G_EXT_CTRLS finds +that this value is less than is required to store +the payload result, then it is set to a value large enough to store the +payload result and ENOSPC is returned. Note that for string controls +this size field should not be confused with the length of the string. +This field refers to the size of the memory that contains the string. +The actual length of the string may well be much smaller. + + + + __u32 + reserved2[1] Reserved for future extensions. Drivers and applications must set the array to zero. @@ -135,9 +166,9 @@ applications must set the array to zero. - void * - reserved - Reserved for future pointer-type controls. Currently unused. + char * + string + A pointer to a string. @@ -202,9 +233,16 @@ class. V4L2_CTRL_CLASS_MPEG 0x990000 The class containing MPEG compression controls. -These controls are described in section . + + V4L2_CTRL_CLASS_CAMERA + 0x9a0000 + The class containing camera controls. +These controls are described in . + @@ -241,6 +279,14 @@ because another applications took over control of the device function this control belongs to. + + ENOSPC + + The space reserved for the control's payload is insufficient. +The field size is set to a value that is enough +to store the payload and this error code is returned. + + diff --git a/v4l2-spec/vidioc-queryctrl.sgml b/v4l2-spec/vidioc-queryctrl.sgml index 9908a964d..413930226 100644 --- a/v4l2-spec/vidioc-queryctrl.sgml +++ b/v4l2-spec/vidioc-queryctrl.sgml @@ -93,8 +93,8 @@ next supported control, or EINVAL if there is none. Drivers which do not support this flag yet always return EINVAL. - Additional information is required for menu controls, the -name of menu items. To query them applications set the + Additional information is required for menu controls: the +names of the menu items. To query them applications set the id and index fields of &v4l2-querymenu; and call the VIDIOC_QUERYMENU ioctl with a pointer to this @@ -138,9 +138,12 @@ 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. It may -not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note this is a +bound for V4L2_CTRL_TYPE_INTEGER controls and the +lowest valid index (always 0) 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. @@ -149,16 +152,21 @@ signed value. 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. It may not be valid for any other type of control, including -V4L2_CTRL_TYPE_INTEGER64 controls. Note this is a +controls. +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. __s32 step This field gives a step size for -V4L2_CTRL_TYPE_INTEGER controls. It may not be -valid for any other type of control, including +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 control values. It may be necessary for example when the @@ -171,7 +179,7 @@ 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.Note although signed, the step value is supposed to +128.Note that although signed, the step value is supposed to be always positive. @@ -295,6 +303,20 @@ Drivers must ignore the value passed with n/a A 64-bit integer valued control. Minimum, maximum and step size cannot be queried. + + + V4L2_CTRL_TYPE_STRING + >=0 + >=1 + >=0 + The minimum and maximum string lengths. The step size +means that the string must be (minimum + N * step) characters long for +N >= 0. These lengths do not include the terminating zero, so in order to +pass a string of length 8 to &VIDIOC-S-EXT-CTRLS; you need to set the +size field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can +set the size field to maximum+1. +Which character encoding is used will depend on the string control itself and +should be part of the control documentation. V4L2_CTRL_TYPE_CTRL_CLASS -- cgit v1.2.3