123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434 |
- <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>__u32 *</entry>
- <entry><structfield>p_u32</structfield></entry>
- <entry>A pointer to a matrix control of unsigned 32-bit values.
- Valid if this control is of type <constant>V4L2_CTRL_TYPE_U32</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>
|