summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml')
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml456
1 files changed, 0 insertions, 456 deletions
diff --git a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml b/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
deleted file mode 100644
index eb82f7e7d..000000000
--- a/Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml
+++ /dev/null
@@ -1,456 +0,0 @@
-<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>which</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>which</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 (&eg; 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>union</entry>
- <entry>(anonymous)</entry>
- </row>
- <row>
- <entry></entry>
- <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></entry>
- <entry>__u32</entry>
- <entry><structfield>which</structfield></entry>
- <entry><para>Which value of the control to get/set/try. <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>
-will return the current value of the control and <constant>V4L2_CTRL_WHICH_DEF_VAL</constant> will
-return the default value of the control. Please note that you can only get the default value of the
-control, you cannot set or try it.</para>
-<para>For backwards compatibility you can also use a control class here (see
-<xref linkend="ctrl-class" />). In that case all controls have to belong to that
-control class. This usage is deprecated, instead just use <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>.
-There are some very old drivers that do not yet support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>
-and that require a control class here. You can test for such drivers by setting ctrl_class to
-<constant>V4L2_CTRL_WHICH_CUR_VAL</constant> and calling VIDIOC_TRY_EXT_CTRLS with a count of 0.
-If that fails, then the driver does not support <constant>V4L2_CTRL_WHICH_CUR_VAL</constant>.</para>
-</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>which</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>
-