v4l2-spec: document the new string control type.

From: Hans Verkuil <hverkuil@xs4all.nl>

Priority: normal

Signed-off-by: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

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.</para>
 	<listitem>
 	  <para>Added new capabilities for modulators and RDS encoders.</para>
 	</listitem>
+	<listitem>
+	  <para>Added support for string controls.</para>
+	</listitem>
        </orderedlist>
      </section>
    </section>
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.</para>
       <para>The control array is a &v4l2-ext-control; array. The
 <structname>v4l2_ext_control</structname> 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).</para>
+values and pointers to be passed.</para>
 
       <para>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. -->
 
       <revision>
 	<revnumber>0.26</revnumber>
-	<date>2009-06-15</date>
+	<date>2009-07-23</date>
 	<authorinitials>hv</authorinitials>
 	<revremark>Finalized the RDS capture API. Added modulator and RDS encoder
-capabilities.</revremark>
+capabilities. Added support for string controls.</revremark>
       </revision>
 
       <revision>
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
 <structfield>controls</structfield> fields.</para>
 
     <para>To get the current value of a set of controls applications
-initialize the <structfield>id</structfield> field of each
-&v4l2-ext-control; and call the
-<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl.</para>
+initialize the <structfield>id</structfield>,
+<structfield>size</structfield> and <structfield>reserved2</structfield> fields
+of each &v4l2-ext-control; and call the
+<constant>VIDIOC_G_EXT_CTRLS</constant> ioctl. String controls controls
+must also set the <structfield>string</structfield> field.</para>
+
+    <para>If the <structfield>size</structfield> is too small to
+receive the control result (only relevant for pointer-type controls
+like strings), then the driver will set <structfield>size</structfield>
+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
+<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
+value. It is guaranteed that that is sufficient memory.
+</para>
 
     <para>To change the value of a set of controls applications
-initialize the <structfield>id</structfield> and
-<structfield>value</structfield> fields of a &v4l2-ext-control; and
+initialize the <structfield>id</structfield>, <structfield>size</structfield>,
+<structfield>reserved2</structfield> and
+<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
 call the <constant>VIDIOC_S_EXT_CTRLS</constant> ioctl. The controls
 will only be set if <emphasis>all</emphasis> control values are
 valid.</para>
 
-    <para>To check if the a set of controls have correct values
-applications initialize the <structfield>id</structfield> and
-<structfield>value</structfield> fields of a &v4l2-ext-control; and
+    <para>To check if a set of controls have correct values applications
+initialize the <structfield>id</structfield>, <structfield>size</structfield>,
+<structfield>reserved2</structfield> and
+<structfield>value/string</structfield> fields of each &v4l2-ext-control; and
 call the <constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctl. It is up to
 the driver whether wrong values are automatically adjusted to a valid
 value or if an error is returned.</para>
@@ -112,7 +127,23 @@ application.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
-	    <entry><structfield>reserved2</structfield>[2]</entry>
+	    <entry><structfield>size</structfield></entry>
+	    <entry></entry>
+	    <entry>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 <constant>VIDIOC_G_EXT_CTRLS</constant> 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 <structfield>size</structfield> 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 <emphasis>length</emphasis> of the string may well be much smaller.
+</entry>
+	  </row>
+	  <row>
+	    <entry>__u32</entry>
+	    <entry><structfield>reserved2</structfield>[1]</entry>
 	    <entry></entry>
 	    <entry>Reserved for future extensions. Drivers and
 applications must set the array to zero.</entry>
@@ -135,9 +166,9 @@ applications must set the array to zero.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
-	    <entry>void *</entry>
-	    <entry><structfield>reserved</structfield></entry>
-	    <entry>Reserved for future pointer-type controls. Currently unused.</entry>
+	    <entry>char *</entry>
+	    <entry><structfield>string</structfield></entry>
+	    <entry>A pointer to a string.</entry>
 	  </row>
 	</tbody>
       </tgroup>
@@ -202,9 +233,16 @@ class.</entry>
 	    <entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry>
 	    <entry>0x990000</entry>
 	    <entry>The class containing MPEG compression controls.
-These controls are described in section <xref
+These controls are described in <xref
 		linkend="mpeg-controls">.</entry>
 	  </row>
+	  <row>
+	    <entry><constant>V4L2_CTRL_CLASS_CAMERA</constant></entry>
+	    <entry>0x9a0000</entry>
+	    <entry>The class containing camera controls.
+These controls are described in <xref
+		linkend="camera-controls">.</entry>
+	  </row>
 	</tbody>
       </tgroup>
     </table>
@@ -241,6 +279,14 @@ because another applications took over control of the device function
 this control belongs to.</para>
 	</listitem>
       </varlistentry>
+      <varlistentry>
+	<term><errorcode>ENOSPC</errorcode></term>
+	<listitem>
+	  <para>The space reserved for the control's payload is insufficient.
+The field <structfield>size</structfield> is set to a value that is enough
+to store the payload and this error code is returned.</para>
+	</listitem>
+      </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
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 <errorcode>EINVAL</errorcode> if there is
 none. Drivers which do not support this flag yet always return
 <errorcode>EINVAL</errorcode>.</para>
 
-    <para>Additional information is required for menu controls, the
-name of menu items. To query them applications set the
+    <para>Additional information is required for menu controls: the
+names of the menu items. To query them applications set the
 <structfield>id</structfield> and <structfield>index</structfield>
 fields of &v4l2-querymenu; and call the
 <constant>VIDIOC_QUERYMENU</constant> ioctl with a pointer to this
@@ -138,9 +138,12 @@ string. This information is intended for the user.</entry>
 	    <entry>__s32</entry>
 	    <entry><structfield>minimum</structfield></entry>
 	    <entry>Minimum value, inclusive. This field gives a lower
-bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. It may
-not be valid for any other type of control, including
-<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a
+bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
+lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls.
+For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value
+gives the minimum length of the string. This length <emphasis>does not include the terminating
+zero</emphasis>. It may not be valid for any other type of control, including
+<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
 signed value.</entry>
 	  </row>
 	  <row>
@@ -149,16 +152,21 @@ signed value.</entry>
 	    <entry>Maximum value, inclusive. This field gives an upper
 bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the
 highest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant>
-controls. It may not be valid for any other type of control, including
-<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note this is a
+controls.
+For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the maximum value
+gives the maximum length of the string. This length <emphasis>does not include the terminating
+zero</emphasis>. It may not be valid for any other type of control, including
+<constant>V4L2_CTRL_TYPE_INTEGER64</constant> controls. Note that this is a
 signed value.</entry>
 	  </row>
 	  <row>
 	    <entry>__s32</entry>
 	    <entry><structfield>step</structfield></entry>
 	    <entry><para>This field gives a step size for
-<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. It may not be
-valid for any other type of control, including
+<constant>V4L2_CTRL_TYPE_INTEGER</constant> controls. For
+<constant>V4L2_CTRL_TYPE_STRING</constant> 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
 <constant>V4L2_CTRL_TYPE_INTEGER64</constant>
 controls.</para><para>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.</para><para>Note although signed, the step value is supposed to
+128.</para><para>Note that although signed, the step value is supposed to
 be always positive.</para></entry>
 	  </row>
 	  <row>
@@ -297,6 +305,20 @@ Drivers must ignore the value passed with
 and step size cannot be queried.</entry>
 	  </row>
 	  <row>
+	    <entry><constant>V4L2_CTRL_TYPE_STRING</constant></entry>
+	    <entry>>=0</entry>
+	    <entry>>=1</entry>
+	    <entry>>=0</entry>
+	    <entry>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
+<structfield>size</structfield> field of &v4l2-ext-control; to 9. For &VIDIOC-G-EXT-CTRLS; you can
+set the <structfield>size</structfield> field to <structfield>maximum</structfield>+1.
+Which character encoding is used will depend on the string control itself and
+should be part of the control documentation.</entry>
+	  </row>
+	  <row>
 	    <entry><constant>V4L2_CTRL_TYPE_CTRL_CLASS</constant></entry>
 	    <entry>n/a</entry>
 	    <entry>n/a</entry>