Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_EXT_CTRLS:
   4
   5 ******************************************************************
   6 ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS
   7 ******************************************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct v4l2_ext_controls *argp )
  19
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <func-open>`.
  26
  27 ``request``
  28     VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS,
  29     VIDIOC_TRY_EXT_CTRLS
  30
  31 ``argp``
  32
  33
  34 Description
  35 ===========
  36
  37 These ioctls allow the caller to get or set multiple controls
  38 atomically. Control IDs are grouped into control classes (see
  39 :ref:`ctrl-class`) and all controls in the control array must belong
  40 to the same control class.
  41
  42 Applications must always fill in the ``count``, ``which``, ``controls``
  43 and ``reserved`` fields of struct
  44 :ref:`v4l2_ext_controls <v4l2-ext-controls>`, and initialize the
  45 struct :ref:`v4l2_ext_control <v4l2-ext-control>` array pointed to
  46 by the ``controls`` fields.
  47
  48 To get the current value of a set of controls applications initialize
  49 the ``id``, ``size`` and ``reserved2`` fields of each struct
  50 :ref:`v4l2_ext_control <v4l2-ext-control>` and call the
  51 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls controls must also set the
  52 ``string`` field. Controls of compound types
  53 (``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field.
  54
  55 If the ``size`` is too small to receive the control result (only
  56 relevant for pointer-type controls like strings), then the driver will
  57 set ``size`` to a valid value and return an ``ENOSPC`` error code. You
  58 should re-allocate the memory to this new size and try again. For the
  59 string type it is possible that the same issue occurs again if the
  60 string has grown in the meantime. It is recommended to call
  61 :ref:`VIDIOC_QUERYCTRL` first and use
  62 ``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is
  63 sufficient memory.
  64
  65 N-dimensional arrays are set and retrieved row-by-row. You cannot set a
  66 partial array, all elements have to be set or retrieved. The total size
  67 is calculated as ``elems`` * ``elem_size``. These values can be obtained
  68 by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.
  69
  70 To change the value of a set of controls applications initialize the
  71 ``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
  72 of each struct :ref:`v4l2_ext_control <v4l2-ext-control>` and call
  73 the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all*
  74 control values are valid.
  75
  76 To check if a set of controls have correct values applications
  77 initialize the ``id``, ``size``, ``reserved2`` and
  78 ``value/value64/string/ptr`` fields of each struct
  79 :ref:`v4l2_ext_control <v4l2-ext-control>` and call the
  80 :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. It is up to the driver whether wrong
  81 values are automatically adjusted to a valid value or if an error is
  82 returned.
  83
  84 When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error
  85 code. When the value is out of bounds drivers can choose to take the
  86 closest valid value or return an ``ERANGE`` error code, whatever seems more
  87 appropriate. In the first case the new value is set in struct
  88 :ref:`v4l2_ext_control <v4l2-ext-control>`. If the new control value
  89 is inappropriate (e.g. the given menu index is not supported by the menu
  90 control), then this will also result in an ``EINVAL`` error code error.
  91
  92 The driver will only set/get these controls if all control values are
  93 correct. This prevents the situation where only some of the controls
  94 were set/get. Only low-level errors (e. g. a failed i2c command) can
  95 still cause this situation.
  96
  97
  98 .. _v4l2-ext-control:
  99
 100 .. flat-table:: struct v4l2_ext_control
 101     :header-rows:  0
 102     :stub-columns: 0
 103     :widths:       1 1 1 2
 104
 105
 106     -  .. row 1
 107
 108        -  __u32
 109
 110        -  ``id``
 111
 112        -
 113        -  Identifies the control, set by the application.
 114
 115     -  .. row 2
 116
 117        -  __u32
 118
 119        -  ``size``
 120
 121        -
 122        -  The total size in bytes of the payload of this control. This is
 123           normally 0, but for pointer controls this should be set to the
 124           size of the memory containing the payload, or that will receive
 125           the payload. If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value is
 126           less than is required to store the payload result, then it is set
 127           to a value large enough to store the payload result and ``ENOSPC`` is
 128           returned.
 129
 130           .. note:: For string controls, this ``size`` field should
 131              not be confused with the length of the string. This field refers
 132              to the size of the memory that contains the string. The actual
 133              *length* of the string may well be much smaller.
 134
 135     -  .. row 3
 136
 137        -  __u32
 138
 139        -  ``reserved2``\ [1]
 140
 141        -
 142        -  Reserved for future extensions. Drivers and applications must set
 143           the array to zero.
 144
 145     -  .. row 4
 146
 147        -  union
 148
 149        -  (anonymous)
 150
 151     -  .. row 5
 152
 153        -
 154        -  __s32
 155
 156        -  ``value``
 157
 158        -  New value or current value. Valid if this control is not of type
 159           ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
 160           not set.
 161
 162     -  .. row 6
 163
 164        -
 165        -  __s64
 166
 167        -  ``value64``
 168
 169        -  New value or current value. Valid if this control is of type
 170           ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
 171           not set.
 172
 173     -  .. row 7
 174
 175        -
 176        -  char *
 177
 178        -  ``string``
 179
 180        -  A pointer to a string. Valid if this control is of type
 181           ``V4L2_CTRL_TYPE_STRING``.
 182
 183     -  .. row 8
 184
 185        -
 186        -  __u8 *
 187
 188        -  ``p_u8``
 189
 190        -  A pointer to a matrix control of unsigned 8-bit values. Valid if
 191           this control is of type ``V4L2_CTRL_TYPE_U8``.
 192
 193     -  .. row 9
 194
 195        -
 196        -  __u16 *
 197
 198        -  ``p_u16``
 199
 200        -  A pointer to a matrix control of unsigned 16-bit values. Valid if
 201           this control is of type ``V4L2_CTRL_TYPE_U16``.
 202
 203     -  .. row 10
 204
 205        -
 206        -  __u32 *
 207
 208        -  ``p_u32``
 209
 210        -  A pointer to a matrix control of unsigned 32-bit values. Valid if
 211           this control is of type ``V4L2_CTRL_TYPE_U32``.
 212
 213     -  .. row 11
 214
 215        -
 216        -  void *
 217
 218        -  ``ptr``
 219
 220        -  A pointer to a compound type which can be an N-dimensional array
 221           and/or a compound type (the control's type is >=
 222           ``V4L2_CTRL_COMPOUND_TYPES``). Valid if
 223           ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control.
 224
 225
 226
 227 .. _v4l2-ext-controls:
 228
 229 .. flat-table:: struct v4l2_ext_controls
 230     :header-rows:  0
 231     :stub-columns: 0
 232     :widths:       1 1 2 1
 233
 234
 235     -  .. row 1
 236
 237        -  union
 238
 239        -  (anonymous)
 240
 241     -  .. row 2
 242
 243        -
 244        -  __u32
 245
 246        -  ``ctrl_class``
 247
 248        -  The control class to which all controls belong, see
 249           :ref:`ctrl-class`. Drivers that use a kernel framework for
 250           handling controls will also accept a value of 0 here, meaning that
 251           the controls can belong to any control class. Whether drivers
 252           support this can be tested by setting ``ctrl_class`` to 0 and
 253           calling :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a ``count`` of 0. If that
 254           succeeds, then the driver supports this feature.
 255
 256     -  .. row 3
 257
 258        -
 259        -  __u32
 260
 261        -  ``which``
 262
 263        -  Which value of the control to get/set/try.
 264           ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of the
 265           control and ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
 266           value of the control.
 267
 268           .. note:: You can only get the default value of the control,
 269              you cannot set or try it.
 270
 271           For backwards compatibility you can also use a control class here
 272           (see :ref:`ctrl-class`). In that case all controls have to
 273           belong to that control class. This usage is deprecated, instead
 274           just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old
 275           drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and
 276           that require a control class here. You can test for such drivers
 277           by setting ctrl_class to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling
 278           VIDIOC_TRY_EXT_CTRLS with a count of 0. If that fails, then the
 279           driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``.
 280
 281     -  .. row 4
 282
 283        -  __u32
 284
 285        -  ``count``
 286
 287        -  The number of controls in the controls array. May also be zero.
 288
 289     -  .. row 5
 290
 291        -  __u32
 292
 293        -  ``error_idx``
 294
 295        -  Set by the driver in case of an error. If the error is associated
 296           with a particular control, then ``error_idx`` is set to the index
 297           of that control. If the error is not related to a specific
 298           control, or the validation step failed (see below), then
 299           ``error_idx`` is set to ``count``. The value is undefined if the
 300           ioctl returned 0 (success).
 301
 302           Before controls are read from/written to hardware a validation
 303           step takes place: this checks if all controls in the list are
 304           valid controls, if no attempt is made to write to a read-only
 305           control or read from a write-only control, and any other up-front
 306           checks that can be done without accessing the hardware. The exact
 307           validations done during this step are driver dependent since some
 308           checks might require hardware access for some devices, thus making
 309           it impossible to do those checks up-front. However, drivers should
 310           make a best-effort to do as many up-front checks as possible.
 311
 312           This check is done to avoid leaving the hardware in an
 313           inconsistent state due to easy-to-avoid problems. But it leads to
 314           another problem: the application needs to know whether an error
 315           came from the validation step (meaning that the hardware was not
 316           touched) or from an error during the actual reading from/writing
 317           to hardware.
 318
 319           The, in hindsight quite poor, solution for that is to set
 320           ``error_idx`` to ``count`` if the validation failed. This has the
 321           unfortunate side-effect that it is not possible to see which
 322           control failed the validation. If the validation was successful
 323           and the error happened while accessing the hardware, then
 324           ``error_idx`` is less than ``count`` and only the controls up to
 325           ``error_idx-1`` were read or written correctly, and the state of
 326           the remaining controls is undefined.
 327
 328           Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is
 329           also no need to handle the validation step in this special way, so
 330           ``error_idx`` will just be set to the control that failed the
 331           validation step instead of to ``count``. This means that if
 332           :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``,
 333           then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the
 334           actual control that failed the validation step. Unfortunately,
 335           there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`.
 336
 337     -  .. row 6
 338
 339        -  __u32
 340
 341        -  ``reserved``\ [2]
 342
 343        -  Reserved for future extensions. Drivers and applications must set
 344           the array to zero.
 345
 346     -  .. row 7
 347
 348        -  struct :ref:`v4l2_ext_control <v4l2-ext-control>` *
 349
 350        -  ``controls``
 351
 352        -  Pointer to an array of ``count`` v4l2_ext_control structures.
 353           Ignored if ``count`` equals zero.
 354
 355
 356
 357 .. _ctrl-class:
 358
 359 .. flat-table:: Control classes
 360     :header-rows:  0
 361     :stub-columns: 0
 362     :widths:       3 1 4
 363
 364
 365     -  .. row 1
 366
 367        -  ``V4L2_CTRL_CLASS_USER``
 368
 369        -  0x980000
 370
 371        -  The class containing user controls. These controls are described
 372           in :ref:`control`. All controls that can be set using the
 373           :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and
 374           :ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this
 375           class.
 376
 377     -  .. row 2
 378
 379        -  ``V4L2_CTRL_CLASS_MPEG``
 380
 381        -  0x990000
 382
 383        -  The class containing MPEG compression controls. These controls are
 384           described in :ref:`mpeg-controls`.
 385
 386     -  .. row 3
 387
 388        -  ``V4L2_CTRL_CLASS_CAMERA``
 389
 390        -  0x9a0000
 391
 392        -  The class containing camera controls. These controls are described
 393           in :ref:`camera-controls`.
 394
 395     -  .. row 4
 396
 397        -  ``V4L2_CTRL_CLASS_FM_TX``
 398
 399        -  0x9b0000
 400
 401        -  The class containing FM Transmitter (FM TX) controls. These
 402           controls are described in :ref:`fm-tx-controls`.
 403
 404     -  .. row 5
 405
 406        -  ``V4L2_CTRL_CLASS_FLASH``
 407
 408        -  0x9c0000
 409
 410        -  The class containing flash device controls. These controls are
 411           described in :ref:`flash-controls`.
 412
 413     -  .. row 6
 414
 415        -  ``V4L2_CTRL_CLASS_JPEG``
 416
 417        -  0x9d0000
 418
 419        -  The class containing JPEG compression controls. These controls are
 420           described in :ref:`jpeg-controls`.
 421
 422     -  .. row 7
 423
 424        -  ``V4L2_CTRL_CLASS_IMAGE_SOURCE``
 425
 426        -  0x9e0000
 427
 428        -  The class containing image source controls. These controls are
 429           described in :ref:`image-source-controls`.
 430
 431     -  .. row 8
 432
 433        -  ``V4L2_CTRL_CLASS_IMAGE_PROC``
 434
 435        -  0x9f0000
 436
 437        -  The class containing image processing controls. These controls are
 438           described in :ref:`image-process-controls`.
 439
 440     -  .. row 9
 441
 442        -  ``V4L2_CTRL_CLASS_FM_RX``
 443
 444        -  0xa10000
 445
 446        -  The class containing FM Receiver (FM RX) controls. These controls
 447           are described in :ref:`fm-rx-controls`.
 448
 449     -  .. row 10
 450
 451        -  ``V4L2_CTRL_CLASS_RF_TUNER``
 452
 453        -  0xa20000
 454
 455        -  The class containing RF tuner controls. These controls are
 456           described in :ref:`rf-tuner-controls`.
 457
 458
 459 Return Value
 460 ============
 461
 462 On success 0 is returned, on error -1 and the ``errno`` variable is set
 463 appropriately. The generic error codes are described at the
 464 :ref:`Generic Error Codes <gen-errors>` chapter.
 465
 466 EINVAL
 467     The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``id`` is
 468     invalid, the struct :ref:`v4l2_ext_controls <v4l2-ext-controls>`
 469     ``which`` is invalid, or the struct
 470     :ref:`v4l2_ext_control <v4l2-ext-control>` ``value`` was
 471     inappropriate (e.g. the given menu index is not supported by the
 472     driver). This error code is also returned by the
 473     :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or
 474     more control values are in conflict.
 475
 476 ERANGE
 477     The struct :ref:`v4l2_ext_control <v4l2-ext-control>` ``value``
 478     is out of bounds.
 479
 480 EBUSY
 481     The control is temporarily not changeable, possibly because another
 482     applications took over control of the device function this control
 483     belongs to.
 484
 485 ENOSPC
 486     The space reserved for the control's payload is insufficient. The
 487     field ``size`` is set to a value that is enough to store the payload
 488     and this error code is returned.
 489
 490 EACCES
 491     Attempt to try or set a read-only control or to get a write-only
 492     control.