diff options
Diffstat (limited to 'Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml')
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-g-ext-ctrls.xml | 456 |
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 (⪚ 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> - |