428 lines
17 KiB
XML
428 lines
17 KiB
XML
<refentry id="vidioc-g-ext-ctrls">
|
|
<refmeta>
|
|
<refentrytitle>ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
|
|
VIDIOC_TRY_EXT_CTRLS</refentrytitle>
|
|
&manvol;
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>VIDIOC_G_EXT_CTRLS</refname>
|
|
<refname>VIDIOC_S_EXT_CTRLS</refname>
|
|
<refname>VIDIOC_TRY_EXT_CTRLS</refname>
|
|
<refpurpose>Get or set the value of several controls, try control
|
|
values</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ioctl</function></funcdef>
|
|
<paramdef>int <parameter>fd</parameter></paramdef>
|
|
<paramdef>int <parameter>request</parameter></paramdef>
|
|
<paramdef>struct v4l2_ext_controls
|
|
*<parameter>argp</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Arguments</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>fd</parameter></term>
|
|
<listitem>
|
|
<para>&fd;</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>request</parameter></term>
|
|
<listitem>
|
|
<para>VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
|
|
VIDIOC_TRY_EXT_CTRLS</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>argp</parameter></term>
|
|
<listitem>
|
|
<para></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>These ioctls allow the caller to get or set multiple
|
|
controls atomically. Control IDs are grouped into control classes (see
|
|
<xref linkend="ctrl-class" />) and all controls in the control array
|
|
must belong to the same control class.</para>
|
|
|
|
<para>Applications must always fill in the
|
|
<structfield>count</structfield>,
|
|
<structfield>ctrl_class</structfield>,
|
|
<structfield>controls</structfield> and
|
|
<structfield>reserved</structfield> fields of &v4l2-ext-controls;, and
|
|
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>,
|
|
<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. Controls
|
|
of compound types (<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set)
|
|
must set the <structfield>ptr</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
|
|
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
|
|
<structfield>maximum</structfield>+1 as the new <structfield>size</structfield>
|
|
value. It is guaranteed that that is sufficient memory.
|
|
</para>
|
|
|
|
<para>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 <structfield>elems</structfield> * <structfield>elem_size</structfield>.
|
|
These values can be obtained by calling &VIDIOC-QUERY-EXT-CTRL;.</para>
|
|
|
|
<para>To change the value of a set of controls applications
|
|
initialize the <structfield>id</structfield>, <structfield>size</structfield>,
|
|
<structfield>reserved2</structfield> and
|
|
<structfield>value/value64/string/ptr</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 a set of controls have correct values applications
|
|
initialize the <structfield>id</structfield>, <structfield>size</structfield>,
|
|
<structfield>reserved2</structfield> and
|
|
<structfield>value/value64/string/ptr</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>
|
|
|
|
<para>When the <structfield>id</structfield> or
|
|
<structfield>ctrl_class</structfield> is invalid drivers return an
|
|
&EINVAL;. When the value is out of bounds drivers can choose to take
|
|
the closest valid value or return an &ERANGE;, whatever seems more
|
|
appropriate. In the first case the new value is set in
|
|
&v4l2-ext-control;. If the new control value is inappropriate (e.g. the
|
|
given menu index is not supported by the menu control), then this will
|
|
also result in an &EINVAL; error.</para>
|
|
|
|
<para>The driver will only set/get these controls if all control
|
|
values are correct. This prevents the situation where only some of the
|
|
controls were set/get. Only low-level errors (⪚ a failed i2c
|
|
command) can still cause this situation.</para>
|
|
|
|
<table pgwide="1" frame="none" id="v4l2-ext-control">
|
|
<title>struct <structname>v4l2_ext_control</structname></title>
|
|
<tgroup cols="4">
|
|
&cs-ustr;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>id</structfield></entry>
|
|
<entry></entry>
|
|
<entry>Identifies the control, set by the
|
|
application.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</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>
|
|
</row>
|
|
<row>
|
|
<entry>union</entry>
|
|
<entry>(anonymous)</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>__s32</entry>
|
|
<entry><structfield>value</structfield></entry>
|
|
<entry>New value or current value. Valid if this control is not of
|
|
type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
|
|
<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>__s64</entry>
|
|
<entry><structfield>value64</structfield></entry>
|
|
<entry>New value or current value. Valid if this control is of
|
|
type <constant>V4L2_CTRL_TYPE_INTEGER64</constant> and
|
|
<constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is not set.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>char *</entry>
|
|
<entry><structfield>string</structfield></entry>
|
|
<entry>A pointer to a string. Valid if this control is of
|
|
type <constant>V4L2_CTRL_TYPE_STRING</constant>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>__u8 *</entry>
|
|
<entry><structfield>p_u8</structfield></entry>
|
|
<entry>A pointer to a matrix control of unsigned 8-bit values.
|
|
Valid if this control is of type <constant>V4L2_CTRL_TYPE_U8</constant>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>__u16 *</entry>
|
|
<entry><structfield>p_u16</structfield></entry>
|
|
<entry>A pointer to a matrix control of unsigned 16-bit values.
|
|
Valid if this control is of type <constant>V4L2_CTRL_TYPE_U16</constant>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry></entry>
|
|
<entry>void *</entry>
|
|
<entry><structfield>ptr</structfield></entry>
|
|
<entry>A pointer to a compound type which can be an N-dimensional array and/or a
|
|
compound type (the control's type is >= <constant>V4L2_CTRL_COMPOUND_TYPES</constant>).
|
|
Valid if <constant>V4L2_CTRL_FLAG_HAS_PAYLOAD</constant> is set for this control.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table pgwide="1" frame="none" id="v4l2-ext-controls">
|
|
<title>struct <structname>v4l2_ext_controls</structname></title>
|
|
<tgroup cols="3">
|
|
&cs-str;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>ctrl_class</structfield></entry>
|
|
<entry>The control class to which all controls belong, see
|
|
<xref linkend="ctrl-class" />. Drivers that use a kernel framework for handling
|
|
controls will also accept a value of 0 here, meaning that the controls can
|
|
belong to any control class. Whether drivers support this can be tested by setting
|
|
<structfield>ctrl_class</structfield> to 0 and calling <constant>VIDIOC_TRY_EXT_CTRLS</constant>
|
|
with a <structfield>count</structfield> of 0. If that succeeds, then the driver
|
|
supports this feature.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>count</structfield></entry>
|
|
<entry>The number of controls in the controls array. May
|
|
also be zero.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>error_idx</structfield></entry>
|
|
<entry><para>Set by the driver in case of an error. If the error is
|
|
associated with a particular control, then <structfield>error_idx</structfield>
|
|
is set to the index of that control. If the error is not related to a specific
|
|
control, or the validation step failed (see below), then
|
|
<structfield>error_idx</structfield> is set to <structfield>count</structfield>.
|
|
The value is undefined if the ioctl returned 0 (success).</para>
|
|
|
|
<para>Before controls are read from/written to hardware a validation step
|
|
takes place: this checks if all controls in the list are valid controls,
|
|
if no attempt is made to write to a read-only control or read from a write-only
|
|
control, and any other up-front checks that can be done without accessing the
|
|
hardware. The exact validations done during this step are driver dependent
|
|
since some checks might require hardware access for some devices, thus making
|
|
it impossible to do those checks up-front. However, drivers should make a
|
|
best-effort to do as many up-front checks as possible.</para>
|
|
|
|
<para>This check is done to avoid leaving the hardware in an inconsistent state due
|
|
to easy-to-avoid problems. But it leads to another problem: the application needs to
|
|
know whether an error came from the validation step (meaning that the hardware
|
|
was not touched) or from an error during the actual reading from/writing to hardware.</para>
|
|
|
|
<para>The, in hindsight quite poor, solution for that is to set <structfield>error_idx</structfield>
|
|
to <structfield>count</structfield> if the validation failed. This has the
|
|
unfortunate side-effect that it is not possible to see which control failed the
|
|
validation. If the validation was successful and the error happened while
|
|
accessing the hardware, then <structfield>error_idx</structfield> is less than
|
|
<structfield>count</structfield> and only the controls up to
|
|
<structfield>error_idx-1</structfield> were read or written correctly, and the
|
|
state of the remaining controls is undefined.</para>
|
|
|
|
<para>Since <constant>VIDIOC_TRY_EXT_CTRLS</constant> does not access hardware
|
|
there is also no need to handle the validation step in this special way,
|
|
so <structfield>error_idx</structfield> will just be set to the control that
|
|
failed the validation step instead of to <structfield>count</structfield>.
|
|
This means that if <constant>VIDIOC_S_EXT_CTRLS</constant> fails with
|
|
<structfield>error_idx</structfield> set to <structfield>count</structfield>,
|
|
then you can call <constant>VIDIOC_TRY_EXT_CTRLS</constant> to try to discover
|
|
the actual control that failed the validation step. Unfortunately, there
|
|
is no <constant>TRY</constant> equivalent for <constant>VIDIOC_G_EXT_CTRLS</constant>.
|
|
</para></entry>
|
|
</row>
|
|
<row>
|
|
<entry>__u32</entry>
|
|
<entry><structfield>reserved</structfield>[2]</entry>
|
|
<entry>Reserved for future extensions. Drivers and
|
|
applications must set the array to zero.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>&v4l2-ext-control; *</entry>
|
|
<entry><structfield>controls</structfield></entry>
|
|
<entry>Pointer to an array of
|
|
<structfield>count</structfield> v4l2_ext_control structures. Ignored
|
|
if <structfield>count</structfield> equals zero.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<table pgwide="1" frame="none" id="ctrl-class">
|
|
<title>Control classes</title>
|
|
<tgroup cols="3">
|
|
&cs-def;
|
|
<tbody valign="top">
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_USER</constant></entry>
|
|
<entry>0x980000</entry>
|
|
<entry>The class containing user controls. These controls
|
|
are described in <xref linkend="control" />. All controls that can be set
|
|
using the &VIDIOC-S-CTRL; and &VIDIOC-G-CTRL; ioctl belong to this
|
|
class.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_MPEG</constant></entry>
|
|
<entry>0x990000</entry>
|
|
<entry>The class containing MPEG compression controls.
|
|
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>
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_FM_TX</constant></entry>
|
|
<entry>0x9b0000</entry>
|
|
<entry>The class containing FM Transmitter (FM TX) controls.
|
|
These controls are described in <xref
|
|
linkend="fm-tx-controls" />.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_FLASH</constant></entry>
|
|
<entry>0x9c0000</entry>
|
|
<entry>The class containing flash device controls.
|
|
These controls are described in <xref
|
|
linkend="flash-controls" />.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_JPEG</constant></entry>
|
|
<entry>0x9d0000</entry>
|
|
<entry>The class containing JPEG compression controls.
|
|
These controls are described in <xref
|
|
linkend="jpeg-controls" />.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_IMAGE_SOURCE</constant></entry>
|
|
<entry>0x9e0000</entry> <entry>The class containing image
|
|
source controls. These controls are described in <xref
|
|
linkend="image-source-controls" />.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_IMAGE_PROC</constant></entry>
|
|
<entry>0x9f0000</entry> <entry>The class containing image
|
|
processing controls. These controls are described in <xref
|
|
linkend="image-process-controls" />.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_FM_RX</constant></entry>
|
|
<entry>0xa10000</entry>
|
|
<entry>The class containing FM Receiver (FM RX) controls.
|
|
These controls are described in <xref
|
|
linkend="fm-rx-controls" />.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><constant>V4L2_CTRL_CLASS_RF_TUNER</constant></entry>
|
|
<entry>0xa20000</entry>
|
|
<entry>The class containing RF tuner controls.
|
|
These controls are described in <xref linkend="rf-tuner-controls" />.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
&return-value;
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><errorcode>EINVAL</errorcode></term>
|
|
<listitem>
|
|
<para>The &v4l2-ext-control; <structfield>id</structfield>
|
|
is invalid, the &v4l2-ext-controls;
|
|
<structfield>ctrl_class</structfield> is invalid, or the &v4l2-ext-control;
|
|
<structfield>value</structfield> was inappropriate (e.g. the given menu
|
|
index is not supported by the driver). This error code is
|
|
also returned by the <constant>VIDIOC_S_EXT_CTRLS</constant> and
|
|
<constant>VIDIOC_TRY_EXT_CTRLS</constant> ioctls if two or more
|
|
control values are in conflict.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>ERANGE</errorcode></term>
|
|
<listitem>
|
|
<para>The &v4l2-ext-control; <structfield>value</structfield>
|
|
is out of bounds.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><errorcode>EBUSY</errorcode></term>
|
|
<listitem>
|
|
<para>The control is temporarily not changeable, possibly
|
|
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>
|
|
<varlistentry>
|
|
<term><errorcode>EACCES</errorcode></term>
|
|
<listitem>
|
|
<para>Attempt to try or set a read-only control or to get a
|
|
write-only control.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
</refentry>
|
|
|