tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

kernel / Documentation / media / uapi / v4l / vidioc-queryctrl.rst
at v4.10-rc4 535 lines 20 kB view raw
1.. -*- coding: utf-8; mode: rst -*- 2 3.. _VIDIOC_QUERYCTRL: 4 5******************************************************************* 6ioctls VIDIOC_QUERYCTRL, VIDIOC_QUERY_EXT_CTRL and VIDIOC_QUERYMENU 7******************************************************************* 8 9Name 10==== 11 12VIDIOC_QUERYCTRL - VIDIOC_QUERY_EXT_CTRL - VIDIOC_QUERYMENU - Enumerate controls and menu control items 13 14 15Synopsis 16======== 17 18.. c:function:: int ioctl( int fd, int VIDIOC_QUERYCTRL, struct v4l2_queryctrl *argp ) 19 :name: VIDIOC_QUERYCTRL 20 21.. c:function:: int ioctl( int fd, VIDIOC_QUERY_EXT_CTRL, struct v4l2_query_ext_ctrl *argp ) 22 :name: VIDIOC_QUERY_EXT_CTRL 23 24.. c:function:: int ioctl( int fd, VIDIOC_QUERYMENU, struct v4l2_querymenu *argp ) 25 :name: VIDIOC_QUERYMENU 26 27 28Arguments 29========= 30 31``fd`` 32 File descriptor returned by :ref:`open() <func-open>`. 33 34``argp`` 35 36 37Description 38=========== 39 40To query the attributes of a control applications set the ``id`` field 41of a struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` and call the 42``VIDIOC_QUERYCTRL`` ioctl with a pointer to this structure. The driver 43fills the rest of the structure or returns an ``EINVAL`` error code when the 44``id`` is invalid. 45 46It is possible to enumerate controls by calling ``VIDIOC_QUERYCTRL`` 47with successive ``id`` values starting from ``V4L2_CID_BASE`` up to and 48exclusive ``V4L2_CID_LASTP1``. Drivers may return ``EINVAL`` if a control in 49this range is not supported. Further applications can enumerate private 50controls, which are not defined in this specification, by starting at 51``V4L2_CID_PRIVATE_BASE`` and incrementing ``id`` until the driver 52returns ``EINVAL``. 53 54In both cases, when the driver sets the ``V4L2_CTRL_FLAG_DISABLED`` flag 55in the ``flags`` field this control is permanently disabled and should 56be ignored by the application. [#f1]_ 57 58When the application ORs ``id`` with ``V4L2_CTRL_FLAG_NEXT_CTRL`` the 59driver returns the next supported non-compound control, or ``EINVAL`` if 60there is none. In addition, the ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` flag 61can be specified to enumerate all compound controls (i.e. controls with 62type ≥ ``V4L2_CTRL_COMPOUND_TYPES`` and/or array control, in other words 63controls that contain more than one value). Specify both 64``V4L2_CTRL_FLAG_NEXT_CTRL`` and ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` in 65order to enumerate all controls, compound or not. Drivers which do not 66support these flags yet always return ``EINVAL``. 67 68The ``VIDIOC_QUERY_EXT_CTRL`` ioctl was introduced in order to better 69support controls that can use compound types, and to expose additional 70control information that cannot be returned in struct 71:ref:`v4l2_queryctrl <v4l2-queryctrl>` since that structure is full. 72 73``VIDIOC_QUERY_EXT_CTRL`` is used in the same way as 74``VIDIOC_QUERYCTRL``, except that the ``reserved`` array must be zeroed 75as well. 76 77Additional information is required for menu controls: the names of the 78menu items. To query them applications set the ``id`` and ``index`` 79fields of struct :ref:`v4l2_querymenu <v4l2-querymenu>` and call the 80``VIDIOC_QUERYMENU`` ioctl with a pointer to this structure. The driver 81fills the rest of the structure or returns an ``EINVAL`` error code when the 82``id`` or ``index`` is invalid. Menu items are enumerated by calling 83``VIDIOC_QUERYMENU`` with successive ``index`` values from struct 84:ref:`v4l2_queryctrl <v4l2-queryctrl>` ``minimum`` to ``maximum``, 85inclusive. 86 87.. note:: 88 89 It is possible for ``VIDIOC_QUERYMENU`` to return 90 an ``EINVAL`` error code for some indices between ``minimum`` and 91 ``maximum``. In that case that particular menu item is not supported by 92 this driver. Also note that the ``minimum`` value is not necessarily 0. 93 94See also the examples in :ref:`control`. 95 96 97.. tabularcolumns:: |p{1.2cm}|p{3.6cm}|p{12.7cm}| 98 99.. _v4l2-queryctrl: 100 101.. cssclass:: longtable 102 103.. flat-table:: struct v4l2_queryctrl 104 :header-rows: 0 105 :stub-columns: 0 106 :widths: 1 1 2 107 108 * - __u32 109 - ``id`` 110 - Identifies the control, set by the application. See 111 :ref:`control-id` for predefined IDs. When the ID is ORed with 112 V4L2_CTRL_FLAG_NEXT_CTRL the driver clears the flag and 113 returns the first control with a higher ID. Drivers which do not 114 support this flag yet always return an ``EINVAL`` error code. 115 * - __u32 116 - ``type`` 117 - Type of control, see :c:type:`v4l2_ctrl_type`. 118 * - __u8 119 - ``name``\ [32] 120 - Name of the control, a NUL-terminated ASCII string. This 121 information is intended for the user. 122 * - __s32 123 - ``minimum`` 124 - Minimum value, inclusive. This field gives a lower bound for the 125 control. See enum :c:type:`v4l2_ctrl_type` how 126 the minimum value is to be used for each possible control type. 127 Note that this a signed 32-bit value. 128 * - __s32 129 - ``maximum`` 130 - Maximum value, inclusive. This field gives an upper bound for the 131 control. See enum :c:type:`v4l2_ctrl_type` how 132 the maximum value is to be used for each possible control type. 133 Note that this a signed 32-bit value. 134 * - __s32 135 - ``step`` 136 - This field gives a step size for the control. See enum 137 :c:type:`v4l2_ctrl_type` how the step value is 138 to be used for each possible control type. Note that this an 139 unsigned 32-bit value. 140 141 Generally drivers should not scale hardware control values. It may 142 be necessary for example when the ``name`` or ``id`` imply a 143 particular unit and the hardware actually accepts only multiples 144 of said unit. If so, drivers must take care values are properly 145 rounded when scaling, such that errors will not accumulate on 146 repeated read-write cycles. 147 148 This field gives the smallest change of an integer control 149 actually affecting hardware. Often the information is needed when 150 the user can change controls by keyboard or GUI buttons, rather 151 than a slider. When for example a hardware register accepts values 152 0-511 and the driver reports 0-65535, step should be 128. 153 154 Note that although signed, the step value is supposed to be always 155 positive. 156 * - __s32 157 - ``default_value`` 158 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_BOOLEAN``, 159 ``_BITMASK``, ``_MENU`` or ``_INTEGER_MENU`` control. Not valid 160 for other types of controls. 161 162 .. note:: 163 164 Drivers reset controls to their default value only when 165 the driver is first loaded, never afterwards. 166 * - __u32 167 - ``flags`` 168 - Control flags, see :ref:`control-flags`. 169 * - __u32 170 - ``reserved``\ [2] 171 - Reserved for future extensions. Drivers must set the array to 172 zero. 173 174 175 176.. tabularcolumns:: |p{1.2cm}|p{5.0cm}|p{11.3cm}| 177 178.. _v4l2-query-ext-ctrl: 179 180.. cssclass:: longtable 181 182.. flat-table:: struct v4l2_query_ext_ctrl 183 :header-rows: 0 184 :stub-columns: 0 185 :widths: 1 1 2 186 187 * - __u32 188 - ``id`` 189 - Identifies the control, set by the application. See 190 :ref:`control-id` for predefined IDs. When the ID is ORed with 191 ``V4L2_CTRL_FLAG_NEXT_CTRL`` the driver clears the flag and 192 returns the first non-compound control with a higher ID. When the 193 ID is ORed with ``V4L2_CTRL_FLAG_NEXT_COMPOUND`` the driver clears 194 the flag and returns the first compound control with a higher ID. 195 Set both to get the first control (compound or not) with a higher 196 ID. 197 * - __u32 198 - ``type`` 199 - Type of control, see :c:type:`v4l2_ctrl_type`. 200 * - char 201 - ``name``\ [32] 202 - Name of the control, a NUL-terminated ASCII string. This 203 information is intended for the user. 204 * - __s64 205 - ``minimum`` 206 - Minimum value, inclusive. This field gives a lower bound for the 207 control. See enum :c:type:`v4l2_ctrl_type` how 208 the minimum value is to be used for each possible control type. 209 Note that this a signed 64-bit value. 210 * - __s64 211 - ``maximum`` 212 - Maximum value, inclusive. This field gives an upper bound for the 213 control. See enum :c:type:`v4l2_ctrl_type` how 214 the maximum value is to be used for each possible control type. 215 Note that this a signed 64-bit value. 216 * - __u64 217 - ``step`` 218 - This field gives a step size for the control. See enum 219 :c:type:`v4l2_ctrl_type` how the step value is 220 to be used for each possible control type. Note that this an 221 unsigned 64-bit value. 222 223 Generally drivers should not scale hardware control values. It may 224 be necessary for example when the ``name`` or ``id`` imply a 225 particular unit and the hardware actually accepts only multiples 226 of said unit. If so, drivers must take care values are properly 227 rounded when scaling, such that errors will not accumulate on 228 repeated read-write cycles. 229 230 This field gives the smallest change of an integer control 231 actually affecting hardware. Often the information is needed when 232 the user can change controls by keyboard or GUI buttons, rather 233 than a slider. When for example a hardware register accepts values 234 0-511 and the driver reports 0-65535, step should be 128. 235 * - __s64 236 - ``default_value`` 237 - The default value of a ``V4L2_CTRL_TYPE_INTEGER``, ``_INTEGER64``, 238 ``_BOOLEAN``, ``_BITMASK``, ``_MENU``, ``_INTEGER_MENU``, ``_U8`` 239 or ``_U16`` control. Not valid for other types of controls. 240 241 .. note:: 242 243 Drivers reset controls to their default value only when 244 the driver is first loaded, never afterwards. 245 * - __u32 246 - ``flags`` 247 - Control flags, see :ref:`control-flags`. 248 * - __u32 249 - ``elem_size`` 250 - The size in bytes of a single element of the array. Given a char 251 pointer ``p`` to a 3-dimensional array you can find the position 252 of cell ``(z, y, x)`` as follows: 253 ``p + ((z * dims[1] + y) * dims[0] + x) * elem_size``. 254 ``elem_size`` is always valid, also when the control isn't an 255 array. For string controls ``elem_size`` is equal to 256 ``maximum + 1``. 257 * - __u32 258 - ``elems`` 259 - The number of elements in the N-dimensional array. If this control 260 is not an array, then ``elems`` is 1. The ``elems`` field can 261 never be 0. 262 * - __u32 263 - ``nr_of_dims`` 264 - The number of dimension in the N-dimensional array. If this 265 control is not an array, then this field is 0. 266 * - __u32 267 - ``dims[V4L2_CTRL_MAX_DIMS]`` 268 - The size of each dimension. The first ``nr_of_dims`` elements of 269 this array must be non-zero, all remaining elements must be zero. 270 * - __u32 271 - ``reserved``\ [32] 272 - Reserved for future extensions. Applications and drivers must set 273 the array to zero. 274 275 276 277.. tabularcolumns:: |p{1.2cm}|p{0.6cm}|p{1.6cm}|p{13.5cm}| 278 279.. _v4l2-querymenu: 280 281.. flat-table:: struct v4l2_querymenu 282 :header-rows: 0 283 :stub-columns: 0 284 :widths: 1 1 2 1 285 286 * - __u32 287 - 288 - ``id`` 289 - Identifies the control, set by the application from the respective 290 struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id``. 291 * - __u32 292 - 293 - ``index`` 294 - Index of the menu item, starting at zero, set by the application. 295 * - union 296 - 297 - 298 - 299 * - 300 - __u8 301 - ``name``\ [32] 302 - Name of the menu item, a NUL-terminated ASCII string. This 303 information is intended for the user. This field is valid for 304 ``V4L2_CTRL_FLAG_MENU`` type controls. 305 * - 306 - __s64 307 - ``value`` 308 - Value of the integer menu item. This field is valid for 309 ``V4L2_CTRL_FLAG_INTEGER_MENU`` type controls. 310 * - __u32 311 - 312 - ``reserved`` 313 - Reserved for future extensions. Drivers must set the array to 314 zero. 315 316 317 318.. tabularcolumns:: |p{5.8cm}|p{1.4cm}|p{1.0cm}|p{1.4cm}|p{6.9cm}| 319 320.. c:type:: v4l2_ctrl_type 321 322.. cssclass:: longtable 323 324.. flat-table:: enum v4l2_ctrl_type 325 :header-rows: 1 326 :stub-columns: 0 327 :widths: 30 5 5 5 55 328 329 * - Type 330 - ``minimum`` 331 - ``step`` 332 - ``maximum`` 333 - Description 334 * - ``V4L2_CTRL_TYPE_INTEGER`` 335 - any 336 - any 337 - any 338 - An integer-valued control ranging from minimum to maximum 339 inclusive. The step value indicates the increment between values. 340 * - ``V4L2_CTRL_TYPE_BOOLEAN`` 341 - 0 342 - 1 343 - 1 344 - A boolean-valued control. Zero corresponds to "disabled", and one 345 means "enabled". 346 * - ``V4L2_CTRL_TYPE_MENU`` 347 - ≥ 0 348 - 1 349 - N-1 350 - The control has a menu of N choices. The names of the menu items 351 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. 352 * - ``V4L2_CTRL_TYPE_INTEGER_MENU`` 353 - ≥ 0 354 - 1 355 - N-1 356 - The control has a menu of N choices. The values of the menu items 357 can be enumerated with the ``VIDIOC_QUERYMENU`` ioctl. This is 358 similar to ``V4L2_CTRL_TYPE_MENU`` except that instead of strings, 359 the menu items are signed 64-bit integers. 360 * - ``V4L2_CTRL_TYPE_BITMASK`` 361 - 0 362 - n/a 363 - any 364 - A bitmask field. The maximum value is the set of bits that can be 365 used, all other bits are to be 0. The maximum value is interpreted 366 as a __u32, allowing the use of bit 31 in the bitmask. 367 * - ``V4L2_CTRL_TYPE_BUTTON`` 368 - 0 369 - 0 370 - 0 371 - A control which performs an action when set. Drivers must ignore 372 the value passed with ``VIDIOC_S_CTRL`` and return an ``EINVAL`` error 373 code on a ``VIDIOC_G_CTRL`` attempt. 374 * - ``V4L2_CTRL_TYPE_INTEGER64`` 375 - any 376 - any 377 - any 378 - A 64-bit integer valued control. Minimum, maximum and step size 379 cannot be queried using ``VIDIOC_QUERYCTRL``. Only 380 ``VIDIOC_QUERY_EXT_CTRL`` can retrieve the 64-bit min/max/step 381 values, they should be interpreted as n/a when using 382 ``VIDIOC_QUERYCTRL``. 383 * - ``V4L2_CTRL_TYPE_STRING`` 384 - ≥ 0 385 - ≥ 1 386 - ≥ 0 387 - The minimum and maximum string lengths. The step size means that 388 the string must be (minimum + N * step) characters long for N ≥ 0. 389 These lengths do not include the terminating zero, so in order to 390 pass a string of length 8 to 391 :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you need to 392 set the ``size`` field of struct 393 :c:type:`v4l2_ext_control` to 9. For 394 :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` you can set 395 the ``size`` field to ``maximum`` + 1. Which character encoding is 396 used will depend on the string control itself and should be part 397 of the control documentation. 398 * - ``V4L2_CTRL_TYPE_CTRL_CLASS`` 399 - n/a 400 - n/a 401 - n/a 402 - This is not a control. When ``VIDIOC_QUERYCTRL`` is called with a 403 control ID equal to a control class code (see :ref:`ctrl-class`) 404 + 1, the ioctl returns the name of the control class and this 405 control type. Older drivers which do not support this feature 406 return an ``EINVAL`` error code. 407 * - ``V4L2_CTRL_TYPE_U8`` 408 - any 409 - any 410 - any 411 - An unsigned 8-bit valued control ranging from minimum to maximum 412 inclusive. The step value indicates the increment between values. 413 * - ``V4L2_CTRL_TYPE_U16`` 414 - any 415 - any 416 - any 417 - An unsigned 16-bit valued control ranging from minimum to maximum 418 inclusive. The step value indicates the increment between values. 419 * - ``V4L2_CTRL_TYPE_U32`` 420 - any 421 - any 422 - any 423 - An unsigned 32-bit valued control ranging from minimum to maximum 424 inclusive. The step value indicates the increment between values. 425 426 427 428.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| 429 430.. _control-flags: 431 432.. cssclass:: longtable 433 434.. flat-table:: Control Flags 435 :header-rows: 0 436 :stub-columns: 0 437 :widths: 3 1 4 438 439 * - ``V4L2_CTRL_FLAG_DISABLED`` 440 - 0x0001 441 - This control is permanently disabled and should be ignored by the 442 application. Any attempt to change the control will result in an 443 ``EINVAL`` error code. 444 * - ``V4L2_CTRL_FLAG_GRABBED`` 445 - 0x0002 446 - This control is temporarily unchangeable, for example because 447 another application took over control of the respective resource. 448 Such controls may be displayed specially in a user interface. 449 Attempts to change the control may result in an ``EBUSY`` error code. 450 * - ``V4L2_CTRL_FLAG_READ_ONLY`` 451 - 0x0004 452 - This control is permanently readable only. Any attempt to change 453 the control will result in an ``EINVAL`` error code. 454 * - ``V4L2_CTRL_FLAG_UPDATE`` 455 - 0x0008 456 - A hint that changing this control may affect the value of other 457 controls within the same control class. Applications should update 458 their user interface accordingly. 459 * - ``V4L2_CTRL_FLAG_INACTIVE`` 460 - 0x0010 461 - This control is not applicable to the current configuration and 462 should be displayed accordingly in a user interface. For example 463 the flag may be set on a MPEG audio level 2 bitrate control when 464 MPEG audio encoding level 1 was selected with another control. 465 * - ``V4L2_CTRL_FLAG_SLIDER`` 466 - 0x0020 467 - A hint that this control is best represented as a slider-like 468 element in a user interface. 469 * - ``V4L2_CTRL_FLAG_WRITE_ONLY`` 470 - 0x0040 471 - This control is permanently writable only. Any attempt to read the 472 control will result in an ``EACCES`` error code error code. This flag 473 is typically present for relative controls or action controls 474 where writing a value will cause the device to carry out a given 475 action (e. g. motor control) but no meaningful value can be 476 returned. 477 * - ``V4L2_CTRL_FLAG_VOLATILE`` 478 - 0x0080 479 - This control is volatile, which means that the value of the 480 control changes continuously. A typical example would be the 481 current gain value if the device is in auto-gain mode. In such a 482 case the hardware calculates the gain value based on the lighting 483 conditions which can change over time. 484 485 .. note:: 486 487 Setting a new value for a volatile control will be ignored 488 unless 489 :ref:`V4L2_CTRL_FLAG_EXECUTE_ON_WRITE <FLAG_EXECUTE_ON_WRITE>` 490 is also set. 491 Setting a new value for a volatile control will *never* trigger a 492 :ref:`V4L2_EVENT_CTRL_CH_VALUE <ctrl-changes-flags>` event. 493 * - ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` 494 - 0x0100 495 - This control has a pointer type, so its value has to be accessed 496 using one of the pointer fields of struct 497 :c:type:`v4l2_ext_control`. This flag is set 498 for controls that are an array, string, or have a compound type. 499 In all cases you have to set a pointer to memory containing the 500 payload of the control. 501 * .. _FLAG_EXECUTE_ON_WRITE: 502 503 - ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` 504 - 0x0200 505 - The value provided to the control will be propagated to the driver 506 even if it remains constant. This is required when the control 507 represents an action on the hardware. For example: clearing an 508 error flag or triggering the flash. All the controls of the type 509 ``V4L2_CTRL_TYPE_BUTTON`` have this flag set. 510 511 512Return Value 513============ 514 515On success 0 is returned, on error -1 and the ``errno`` variable is set 516appropriately. The generic error codes are described at the 517:ref:`Generic Error Codes <gen-errors>` chapter. 518 519EINVAL 520 The struct :ref:`v4l2_queryctrl <v4l2-queryctrl>` ``id`` is 521 invalid. The struct :ref:`v4l2_querymenu <v4l2-querymenu>` ``id`` 522 is invalid or ``index`` is out of range (less than ``minimum`` or 523 greater than ``maximum``) or this particular menu item is not 524 supported by the driver. 525 526EACCES 527 An attempt was made to read a write-only control. 528 529.. [#f1] 530 ``V4L2_CTRL_FLAG_DISABLED`` was intended for two purposes: Drivers 531 can skip predefined controls not supported by the hardware (although 532 returning ``EINVAL`` would do as well), or disable predefined and private 533 controls after hardware detection without the trouble of reordering 534 control arrays and indices (``EINVAL`` cannot be used to skip private 535 controls because it would prematurely end the enumeration).