Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 6756207a authored by Hans Verkuil's avatar Hans Verkuil Committed by Mauro Carvalho Chehab
Browse files

V4L/DVB: V4L Doc: correct the documentation for VIDIOC_QUERYMENU 



The VIDIOC_QUERYMENU documentation was not correct. EINVAL can be returned
if the driver does not support some of the menu items. I.e. in a list of
MPEG bitrates a driver generally supports only a subset of these.

This behavior has been in place for years, but was never properly documented.

Signed-off-by: default avatarHans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@redhat.com>
parent 0827d066

Documentation/DocBook/v4l/controls.xml

+0 −3
Original line number Original line Diff line number Diff line
@@ -364,9 +364,6 @@ enumerate_menu (void) 
	      querymenu.index++) {

	      querymenu.index++) {

		if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {

		if (0 == ioctl (fd, &VIDIOC-QUERYMENU;, &amp;querymenu)) {

			printf ("  %s\n", querymenu.name);

			printf ("  %s\n", querymenu.name);

		} else {

			perror ("VIDIOC_QUERYMENU");

			exit (EXIT_FAILURE);

		}

		}

	}

	}

}

}

Documentation/DocBook/v4l/vidioc-queryctrl.xml

+12 −6
Original line number Original line Diff line number Diff line
@@ -103,8 +103,12 @@ structure. The driver fills the rest of the structure or returns an 
<structfield>index</structfield> is invalid. Menu items are enumerated

<structfield>index</structfield> is invalid. Menu items are enumerated

by calling <constant>VIDIOC_QUERYMENU</constant> with successive

by calling <constant>VIDIOC_QUERYMENU</constant> with successive

<structfield>index</structfield> values from &v4l2-queryctrl;

<structfield>index</structfield> values from &v4l2-queryctrl;

<structfield>minimum</structfield> (0) to

<structfield>minimum</structfield> to

<structfield>maximum</structfield>, inclusive.</para>

<structfield>maximum</structfield>, inclusive. Note that it is possible

for <constant>VIDIOC_QUERYMENU</constant> to return an &EINVAL; for some

indices between <structfield>minimum</structfield> and <structfield>maximum</structfield>.

In that case that particular menu item is not supported by this driver. Also note that

the <structfield>minimum</structfield> value is not necessarily 0.</para>





    <para>See also the examples in <xref linkend="control" />.</para>

    <para>See also the examples in <xref linkend="control" />.</para>
@@ -139,7 +143,7 @@ string. This information is intended for the user.</entry> 
	    <entry><structfield>minimum</structfield></entry>

	    <entry><structfield>minimum</structfield></entry>

	    <entry>Minimum value, inclusive. This field gives a lower

	    <entry>Minimum value, inclusive. This field gives a lower

bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the

bound for <constant>V4L2_CTRL_TYPE_INTEGER</constant> controls and the

lowest valid index (always 0) for <constant>V4L2_CTRL_TYPE_MENU</constant> controls.

lowest valid index for <constant>V4L2_CTRL_TYPE_MENU</constant> controls.

For <constant>V4L2_CTRL_TYPE_STRING</constant> controls the minimum value

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

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

zero</emphasis>. It may not be valid for any other type of control, including
@@ -279,7 +283,7 @@ values which are actually different on the hardware.</entry> 
	  </row>

	  </row>

	  <row>

	  <row>

	    <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry>

	    <entry><constant>V4L2_CTRL_TYPE_MENU</constant></entry>

	    <entry>0</entry>

	    <entry>&ge; 0</entry>

	    <entry>1</entry>

	    <entry>1</entry>

	    <entry>N-1</entry>

	    <entry>N-1</entry>

	    <entry>The control has a menu of N choices. The names of

	    <entry>The control has a menu of N choices. The names of
@@ -405,8 +409,10 @@ writing a value will cause the device to carry out a given action 
	<term><errorcode>EINVAL</errorcode></term>

	<term><errorcode>EINVAL</errorcode></term>

	<listitem>

	<listitem>

	  <para>The &v4l2-queryctrl; <structfield>id</structfield>

	  <para>The &v4l2-queryctrl; <structfield>id</structfield>

is invalid. The &v4l2-querymenu; <structfield>id</structfield> or

is invalid. The &v4l2-querymenu; <structfield>id</structfield> is

<structfield>index</structfield> is invalid.</para>

invalid or <structfield>index</structfield> is out of range (less than

<structfield>minimum</structfield> or greater than <structfield>maximum</structfield>)

or this particular menu item is not supported by the driver.</para>

	</listitem>

	</listitem>

      </varlistentry>

      </varlistentry>

      <varlistentry>

      <varlistentry>